Open rate per campaign

message sent on this date has this many opens.

This report focuses on the open rate of the emails sent from your campaigns. It breaks down the number of emails sent and their open rates by campaign, day, mailbox, path, step, and version. For campaigns sent from multiple mailboxes, the data will be separated by each mailbox.

You can preview example results below

Generating a report

Use the below endpoint to generate a report hash. Afterwards use the rest/v2/reports/{hash} to retrieve the statistics data.

Request

Endpoint

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

Headers

x-api-key: {YOUR_API_KEY}
Content-type: application/json

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

Body

A JSON object containing from and to date fields, that define the date period for the report's data generation.

info

You can generate data for up to 30 last days

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

Field	Type	Description	Example
from	string	Start date of the report in ISO 8601 format	"2025-01-01"
to	string	End date of the report in ISO 8601 format	"2025-01-31"

Request sample

Generate a report hash

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/reports/open_rate" \
  --header "Content-Type: application/json" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --data '{
    "from": "YYYY-MM-DD",
    "to": "YYYY-MM-DD"
  }'

Java

import com.fasterxml.jackson.databind.ObjectMapper;

public class WoodpeckerApiClient {
  public static String sendReportRequest(String apiKey, String fromDate, String toDate) throws Exception {
    HttpClient client = HttpClient.newHttpClient();
    ObjectMapper objectMapper = new ObjectMapper();

    Map<String, String> requestBody = Map.of(
      "from", fromDate,
      "to", toDate
    );

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.woodpecker.co/rest/v2/reports/open_rate"))
      .header("Content-Type", "application/json")
      .header("x-api-key", apiKey)
      .POST(HttpRequest.BodyPublishers.ofString(objectMapper.writeValueAsString(requestBody)))
      .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    Map<String, String> responseBody = objectMapper.readValue(response.body(), Map.class);
    return responseBody.get("hash");
  }
}

Node.js

const axios = require("axios");

async function sendReportRequest(apiKey, fromDate, toDate) {
  try {
    const response = await axios.post(
      "https://api.woodpecker.co/rest/v2/reports/open_rate",
      {
        from: fromDate,
        to: toDate,
      },
      {
        headers: {
          "Content-Type": "application/json",
          "x-api-key": apiKey,
        },
      }
    );

    return response.data.hash;
  } catch (error) {
    console.error("Error making API request:", error);
    throw error;
  }
}

const apiKey = "YOUR_API_KEY";
const fromDate = "YYYY-MM-DD";
const toDate = "YYYY-MM-DD";

sendReportRequest(apiKey, fromDate, toDate)
  .then((hash) => console.log("Report hash:", hash))
  .catch((error) => console.error(error));

Response

Response examples

200

The response is a hash that you should use the fetch the report content using the rest/v2/reports/{hash} endpoint.

{
  "hash":"c966572e5b7c12d73f....347b5186242782c9550d"
}

Body schema

Field	Type	Description
hash	string	Representation of the report's ID. Use it to fetch the generated data

400

Invalid request parameters or malformed request syntax. Please review the request body

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Reports can be generated from the last 30 days. Change the from parameter" | "Value of to is incorrect." | "Value of from is incorrect." | "From date cannot be later than the 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

401

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

404

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

405

Incorrect report name in the URL. Please review the endpoint URL

Status: 405
Body: None

500

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

Retrieving a report

After requesting the report generation, you can fetch it using the below endpoint. Insert the hash, obtained from the above request, to the URL.

Preparing the data may take some time. Please check the status value to monitor the progress. The possible statuses are PENDING, WAITING, IN_PROGRESS, READY and FAILED.

Request

Endpoint

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

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

By default, the results are sorted by id, sent_date, step and version ascending. You can change the order by using one of the sort parameter and one of the values.

Key	Value	Required	Description
sort	+id/-id	No	Sort the results by data[].id. Use - for descending and + for ascending
sort	+sent_date/-sent_date	No	Sort the results by data[].sent_date. Use - for descending and + for ascending

Request sample

Retrieve a report using the hash

cURL

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

Java

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) {
    String apiKey = "YOUR_API_KEY"; // Replace with your actual API key
    String hash = "YOUR_REPORT_HASH"; // Replace with the actual hash
    String endpoint = "https://api.woodpecker.co/rest/v2/reports/" + hash;

    try {
      URL url = new URL(endpoint);
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();
      connection.setRequestMethod("GET");
      connection.setRequestProperty("x-api-key", apiKey);

      int responseCode = connection.getResponseCode();
      if (responseCode == HttpURLConnection.HTTP_OK) {
        BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
        String inputLine;
        StringBuilder response = new StringBuilder();

        while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
        }
        in.close();

        System.out.println("Response: " + response.toString());
      } else {
        System.out.println("GET request failed with response code: " + responseCode);
      }

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

Node.js

const axios = require("axios");

const apiKey = "YOUR_API_KEY";
const hash = "YOUR_REPORT_HASH";
const url = `https://api.woodpecker.co/rest/v2/reports/${hash}`;

axios
  .get(url, {
    headers: {
      "x-api-key": apiKey,
    },
  })
  .then((response) => {
    console.log("Response:", response.data);
  })
  .catch((error) => {
    console.error("Error:", error.response ? error.response.data : error.message);
  });

Response

Response examples

200

This example presents campaign statistics for the period from January 10 to January 15, 2025, covering two campaigns. Each object represents a number of emails sent and their open rates, grouped by campaign, day, path, step and version.

The campaign with ID 1234567 is a linear campaign that does not have any conditions/paths and doesn't include A/B versions either. In contrast, campaign 9876543 has a condition after the first email step, contains A/B versions of the first step email and is sent from two mailboxes.

{
  "status": "READY",
  "report": {
    "description": "Open_rate_per_campaign_2025-01-10-2025-01-15",
    "data": [
      {
        "id": 1234567,
        "name": "Simple linear campaign",
        "sent_date": "2025-01-10",
        "sent_from": "email-0@mail.com",
        "path": "",
        "step": 1,
        "version": "A",
        "sent": 50,
        "delivered": 49,
        "opened": 22,
        "open_rate": "44.9%"
      },
      {
        "id": 1234567,
        "name": "Simple linear campaign",
        "sent_date": "2025-01-14",
        "sent_from": "email-0@mail.com",
        "path": "",
        "step": 2,
        "version": "A",
        "sent": 49,
        "delivered": 49,
        "opened": 20,
        "open_rate": "40.8%"
      },
      {
        "id": 9876543,
        "name": "Multiple mailboxes, condition and A/B versions",
        "sent_date": "2025-01-12",
        "sent_from": "email-1@mail.com",
        "path": "Path YES/NO",
        "step": 1,
        "version": "A",
        "sent": 25,
        "delivered": 25,
        "opened": 16,
        "open_rate": "64.0%"
      },
      {
        "id": 9876543,
        "name": "Multiple mailboxes, condition and A/B versions",
        "sent_date": "2025-01-12",
        "sent_from": "email-1@mail.com",
        "path": "Path YES/NO",
        "step": 1,
        "version": "B",
        "sent": 25,
        "delivered": 25,
        "opened": 17,
        "open_rate": "68.0%"
      },
      {
        "id": 9876543,
        "name": "Multiple mailboxes, condition and A/B versions",
        "sent_date": "2025-01-12",
        "sent_from": "email-2@mail.com",
        "path": "Path YES/NO",
        "step": 1,
        "version": "A",
        "sent": 30,
        "delivered": 29,
        "opened": 13,
        "open_rate": "44.8%"
      },
      {
        "id": 9876543,
        "name": "Multiple mailboxes, condition and A/B versions",
        "sent_date": "2025-01-12",
        "sent_from": "email-2@mail.com",
        "path": "Path YES/NO",
        "step": 1,
        "version": "B",
        "sent": 30,
        "delivered": 28,
        "opened": 16,
        "open_rate": "57.1%"
      },
      {
        "id": 9876543,
        "name": "Multiple mailboxes, condition and A/B versions",
        "sent_date": "2025-01-15",
        "sent_from": "email-1@mail.com",
        "path": "Path YES",
        "step": 2,
        "version": "A",
        "sent": 20,
        "delivered": 20,
        "opened": 10,
        "open_rate": "50.0%"
      },
      {
        "id": 9876543,
        "name": "Multiple mailboxes, condition and A/B versions",
        "sent_date": "2025-01-15",
        "sent_from": "email-1@mail.com",
        "path": "Path NO",
        "step": 2,
        "version": "A",
        "sent": 20,
        "delivered": 20,
        "opened": 9,
        "open_rate": "45.0%"
      },
      {
        "id": 9876543,
        "name": "Multiple mailboxes, condition and A/B versions",
        "sent_date": "2025-01-15",
        "sent_from": "email-2@mail.com",
        "path": "Path YES",
        "step": 2,
        "version": "A",
        "sent": 20,
        "delivered": 20,
        "opened": 11,
        "open_rate": "55.0%"
      },
      {
        "id": 9876543,
        "name": "Multiple mailboxes, condition and A/B versions",
        "sent_date": "2025-01-15",
        "sent_from": "email-2@mail.com",
        "path": "Path NO",
        "step": 2,
        "version": "A",
        "sent": 20,
        "delivered": 19,
        "opened": 9,
        "open_rate": "47.3%"
      }
    ]
  }
}

Body schema

Field	Type	Description
status	string	Status of the generation. PENDING, WAITING, IN_PROGRESS, READY, FAILED
report	object/null	Container for report details. Null if status is not READY
└─report.description	string	Full name of the report and its period
└─report.data	array	List of campaign statistics
└─data[].id	integer	Unique ID of the campaign
└─data[].name	string	Name of the campaign
└─data[].sent_date	string	Date of sending emails from a specific step YYYY-MM-DD
└─data[].path	string	Indication from which path the emails were sent. "" - there's no condition in this campaign; PATH YES - the sum of sent emails refers to the YES path on a given step; PATH NO - the sum of sent emails refers to the NO path on a given step; PATH YES/NO IF-condition is set up in a further step of the campaign, it has not been evaluated yet
└─data[].step	integer	Step of the campaign
└─data[].version	string	A/B/C/D/E version of of a step. Defaults to A
└─data[].sent	integer	Number of emails sent
└─data[].delivered	integer	Number of delivered emails
└─data[].opened	integer	Number of opened emails
└─data[].open_rate	integer	Percentage of emails opened / emails delivered

401

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

404

Report not found - please check the hash or 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

500

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