Get deliverability statistics

Retrieve quantitative data on your clients' campaign performance.

This endpoint provides key campaign metrics, including the total number of emails sent, delivered, opened, replied to, and bounced within a specified period. Additionally, it includes a comparison with the previous period of the same duration.

The returned numbers represent the total counts of specific actions for each client account. For example, emails_sent reflects the total number of emails sent across multiple steps in campaigns, not the number of unique prospects contacted. If a company has had no activity within the specified period, it will not be included in the response payload.

The data returned by the API represents the data available in the Agency Panel under the deliverability tab.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/agency/deliverability

Headers

x-api-key: {YOUR_API_KEY}

For details on how to authenticate your requests, please see the authentication guide.

Parameters

By default the API returns results for up to 20 companies, for the last 30 days. You can modify the date range and the quantity of returned companies by using the below parameters.

Parameter	Required	Description
`from`	No	the start date (YYYY-MM-DD) for the report, based on the user's timezone
`to`	No	the end date (YYYY-MM-DD) for the report, based on the user's timezone
`page`	No	Requested results page (1-based)
`per_page`	No	Number of companies per page. Default: 20, maximum: 50

Request sample

Fetch deliverability data for the last 30 days

cURL
Java
Node.js

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/agency/deliverability" \
  --header "x-api-key: {YOUR_API_KEY}"

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    try {
      String apiUrl = "https://api.woodpecker.co/rest/v2/agency/deliverability";
      URL url = new URL(apiUrl);
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();

      connection.setRequestMethod("GET");
      connection.setRequestProperty("x-api-key", "YOUR_API_KEY");

      int responseCode = connection.getResponseCode();
      if (responseCode == HttpURLConnection.HTTP_OK) {
        BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
        StringBuilder response = new StringBuilder();
        String line;
        while ((line = reader.readLine()) != null) {
            response.append(line);
        }
        reader.close();

        System.out.println("Response: " + response.toString());
      } else {
        System.out.println("Request failed. HTTP Code: " + responseCode);
      }

      connection.disconnect();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

const axios = require("axios");

const API_URL = "https://api.woodpecker.co/rest/v2/agency/deliverability";
const API_KEY = "YOUR_API_KEY";

async function fetchDeliverabilityReport() {
  try {
    const response = await axios.get(API_URL, {
      headers: {
        "x-api-key": API_KEY,
      },
    });
    console.log("Response:", response.data);
  } catch (error) {
    console.error("Error:", error.response ? error.response.data : error.message);
  }
}

fetchDeliverabilityReport();

Response

Response examples

{
  "content": [
    {
      "id": 123,
      "name": "First client company",
      "emails_sent": {
        "current_period": 1016,
        "previous_period": 462
      },
      "delivered_emails": {
        "current_period": 998,
        "previous_period": 438
      },
      "views": {
        "current_period": 712,
        "previous_period": 303
      },
      "replies": {
        "current_period": 73,
        "previous_period": 34
      },
      "bounces": {
        "current_period": 18,
        "previous_period": 24
      }
    },
    {
      "id": 456,
      "name": "Second client company",
      "emails_sent": {
        "current_period": 1981,
        "previous_period": 1199
      },
      "delivered_emails": {
        "current_period": 1957,
        "previous_period": 1187
      },
      "views": {
        "current_period": 1063,
        "previous_period": 717
      },
      "replies": {
        "current_period": 113,
        "previous_period": 64
      },
      "bounces": {
        "current_period": 24,
        "previous_period": 12
      }
    }
  ],
  "pagination_data": {
    "total_count": 22,
    "pages_count": 2,
    "current_page_number": 2,
    "page_size": 20
  }
}

Body schema

Field	Type	Description
`content`	array[object]	List of client companies and their deliverability statistics
└─`[].id`	Integer	Unique identifier for the client company
└─`[].name`	String	Name of the client company
└─`[].emails_sent`	Object	Object containing information about sent emails
└─`current_period`	Integer	Number of emails sent in the requested period
└─`previous_period`	Integer/null	Number of emails sent in the previous period
└─`[].delivered_emails`	Object	Object containing information about delivered emails
└─`current_period`	Integer	Number of emails delivered in the requested period
└─`previous_period`	Integer/null	Number of emails delivered in the previous period
└─`[].views`	Object	Object containing information about opened emails
└─`current_period`	Integer	Number of email views in the requested period
└─`previous_period`	Integer/null	Number of email views in the previous period
└─`[].replies`	Object	Object containing information about replies
└─`current_period`	Integer	Number of replies in the requested period
└─`previous_period`	Integer/null	Number of replies in the previous period
└─`[].bounces`	Object	Object containing information about bounced emails
└─`current_period`	Integer	Number of email bounces in the requested period
└─`previous_period`	Integer/null	Number of email bounces in the previous period

Invalid request parameters or malformed request syntax.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Value of from is incorrect" | "Value of to is incorrect" | "From date has to be later then 2021-01-01 UTC" | "From date has to be before to date",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Please review the request URL.

{
  "title": "Not Found",
  "status": 404,
  "detail": "Requested resource does not exist",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Unknown error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Pagination

The response body contains pagination details. It will support you in navigating through larger datasets.

Use the per_page parameter to reduce or increase the number of returned domains per page. Default value: 20, maximum value: 50. Use page parameter to view a specific page.

"pagination_data": {
    "total_elements": 501,
    "total_pages": 21,
    "current_page_number": 3,
    "page_size": 25
  }

Field	Type	Description
`pagination_data`	object	Pagination information
└─`total_elements`	integer	Total number of returned companies
└─`total_pages`	integer	Total number of available pages
└─`current_page_number`	integer	Current page number (1-based)
└─`page_size`	integer	Maximum number of items per page

Retrieve quantitative data on your clients' campaign performance.​

Request​

Endpoint​

Headers​

Parameters​

Request sample​

Fetch deliverability data for the last 30 days​

Response​

Response examples​

Body schema​

Body schema​

Body schema​

Body schema​

Body schema​

Pagination​

Retrieve quantitative data on your clients' campaign performance.

Request

Endpoint

Headers

Parameters

Request sample

Fetch deliverability data for the last 30 days

Response

Response examples

Body schema

Body schema

Body schema

Body schema

Body schema

Pagination