[API 2.0] Reports

IN THIS ARTICLE:

Reports give you a detailed information about your campaign performance in a given time period. You can check:

general statistics per campaign,
number of messages sent on each level in your campaigns,
open rate per campaign.

API Key is a part of an API Key and Integrations add-on, click here to learn how to get it on Marketplace »

Types of reports

Depending on the type of data you want to get, use the right endpoint:

general statistics per campaign

POST https://api.woodpecker.co/rest/v2/reports/campaigns

number of messages sent on each level in your campaigns

POST https://api.woodpecker.co/rest/v2/reports/messages

open rate per campaign

POST https://api.woodpecker.co/rest/v2/reports/open_rate

How to make a request for report

First part of generating your report is making the following request:

POST https://api.woodpecker.co/rest/v2/reports/campaigns

with the following request body:

{ 
   "from": "YYYY-MM-DD",
   "to": "YYYY-MM-DD"
}

where:

from – is the beginning of time period you want to generate stats for
to – is the end of that time period.

IMPORTANT! You can generate reports only for the last 30 days. Also, bear in mind that we will generate a report for the given dates in relation to the UTC timezone.

As a result, you’ll get a hashed number of your report.

{
    "hash": "123456789abcdefghijkl9876543210oplkmnadquicaiajdhia"
}

To see the stats, use this hashed number in the following request:

GET https://api.woodpecker.co/rest/v2/reports/{{hash}}

Sample payloads

General statistics per campaign:

{
    "status": "READY",
    "report": {
        "description": "General_statistics_per_campaign_2022-09-15-2022-10-14",
        "data": [ {
            "id": 1234567,
            "name": "The best campaign ever",
            "status": "RUNNING",
            "sent_from": "[email protected]",
            "sent": 172,
            "bounced": 9,
            "bounced_rate": "5.2%",
            "opened": 117,
            "open_rate": "71.8%",
            "clicked": 0,
            "opt_out": 0,
            "delivered": 163,
            "responded": 45,
            "response_rate": "27.6%",
            "interested": 38,
            "maybe_later": 3,
            "not_interested": 1
        },
        {
            "id": 1345678,
            "name": "SaaS in America",
            "status": "COMPLETED",
            "sent_from": "[email protected]",
            "sent": 227,
            "bounced": 10,
            "bounced_rate": "4.4%",
            "opened": 163,
            "open_rate": "75.1%",
            "clicked": 0,
            "opt_out": 0,
            "delivered": 217,
            "responded": 43,
            "response_rate": "19.8%",
            "interested": 33,
            "maybe_later": 4,
            "not_interested": 1
        } ]
    }
}

Response data type:

status – string, indicates whether your report is ready. Other statuses: FAILED, WAITING, PENDING, IN_PROGRESS.
report – a JSON object, contains information about the report.
description – string, shows type of the report and chosen time period.
data – a JSON object, contains detailed stats.
id – number, campaign ID.
name – string, campaign name.
status – string, campaign status.
sent_from – string, an email campaign was sent from.
sent – number, number of emails sent from this campaign.
bounced – number, number of bounces.
bounced_rate – string, bounce rate.
opened – number, number of opens.
open_rate – string, open rate.
clicked – number, number of clicks.
opt_out – number, number of unsubscribes.
delivered – number, number of emails delivered.
responded – number, number of responses.
response_rate – string, response rate.
interested – number, number of interested prospects.
maybe_later – number, number of prospects that may be interested in your offer.
not_interested – number, number of not interested prospects.

Number of messages sent on each level in your campaigns:

{
    "status": "READY",
    "report": {
        "description": "Number_of_messages_sent_from_each_level_in_campaigns_2022-09-15-2022-10-14",
        "data": [ {
            "id": 1234567,
            "name": "The best campaign ever",
            "sent_date": "2022-10-05",
            "path": "",
            "step": 1,
            "version": "A",
            "sent": "10"
        },
        {
            "id": 1234567,
            "name": "The best campaign ever",
            "sent_date": "2022-10-07",
            "path": "",
            "step": 1,
            "version": "B",
            "sent": "13"
        },
        {
            "id": 1345678,
            "name": "SaaS in America",
            "sent_date": "2022-10-05",
            "path": "Path YES",
            "step": 1,
            "version": "A",
            "sent": "22"

        } ]
    }
}

Response data type:

status – string, indicates whether your report is ready. Other statuses: FAILED, WAITING, PENDING, IN_PROGRESS.
report – a JSON object, contains information about the report.
description – string, shows type of the report and chosen time period.
data – a JSON object, contains detailed stats.
id – number, campaign ID.
name – string, campaign name.
sent_date – string, a date of sending emails from a specific step.
path – string, indicates from which path the emails were sent. Check Note for more information.
step – number, number of step a message was sent from.
version – string, email version. Check Note for more information.
sent – number, number of described emails sent on a given date.

Note:

Path parameter indicates whether your email was sent after fulfilling (or not) a condition:
- empty parameter “” – means that there’s no condition in this campaign,
- PATH YES – means that condition was fulfilled for that prospect and this email was sent from the dedicated path,
- PATH NO – means that condition wasn’t fulfilled for that prospect and this email was sent from the dedicated path,
- PATH YES/NO – means that condition is added after a different step in this campaign.
Version parameter is specifically helpful when you use A/B tests in your campaign. If you don’t, the only version you’ll see in your stats will be version A.
Data is sort in the following order: campaign ID, sent date, step, version.

Open rate per campaign:

{
    "status": "READY",
    "report": {
        "description": "Open_rate_per_campaign_2022-09-15-2022-10-14",
        "data": [ {
            "id": 1234567,
            "name": "The best campaign ever",
            "sent_date": "2022-10-05",
            "sent_from": "[email protected]",
            "path": "",
            "step": 1,
            "version": "A",
            "sent": 10,
            "delivered": 10,
            "opened": 8,
            "open_rate": "80.0%"
        },
        {
            "id": 1234567,
            "name": "The best campaign ever",
            "sent_date": "2022-10-06",
            "sent_from": "[email protected]",
            "path": "",
            "step": 1,
            "version": "A",
            "sent": 21,
            "delivered": 21,
            "opened": 11,
            "open_rate": "52.4%"
        },
        {
            "id": 1345678,
            "name": "SaaS in America",
            "sent_date": "2022-09-15",
            "sent_from": "[email protected]",
            "path": "Path YES/NO",
            "step": 1,
            "version": "A",
            "sent": 12,
            "delivered": 12,
            "opened": 5,
            "open_rate": "41.7%"
        } ]
    }
}

Response data type:

status – string, indicates whether your report is ready. Other statuses: FAILED, WAITING, PENDING, IN_PROGRESS.
report – a JSON object, contains information about the report.
description – string, shows type of the report and chosen time period.
data – a JSON object, contains detailed stats.
id – number, campaign ID.
name – string, campaign name.
sent_date – string, a date of sending emails from a specific step.
path – string, indicates from which path the emails were sent. Check Note for more information.
step – number, number of step a message was sent from.
version – string, email version. Check Note for more information.
sent – number, number of described emails sent on a given date.
delivered – number, number of messages delivered on a given date from a specific step.
opened – number of emails opened on a given date from a specific step.
open_rate – open rate for a specific step on a given date.

Note:

Data is sort in the following order: campaign ID, sent date, step, version.

Woodpecker fits your outreach needs, no matter the scale of your operations

Resources

Types of reports

How to make a request for report

Sample payloads