Get a list of campaigns

warning

This is a v1 legacy endpoint. It uses a different path /rest/v1 and may return different error codes and response formats compared to v2. While it remains functional, consider handling errors accordingly.

Fetch all campaigns associated with your account, with the option to filter by status for more targeted results.

The response includes basic campaign information. You can use the campaign ID further to:

• fetch campaign statistics - see rest/v1/campaign_list?id={id} endpoint here
• fetch campaign settings and content - see v2/campaigns/{id} endpoint here

Request

Endpoint

GET https://api.woodpecker.co/rest/v1/campaign_list

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

Parameter	Required	Description
status	No	Filter campaigns by their status. Comma-separated list of statuses: RUNNING, DRAFT, EDITED, PAUSED, STOPPED, COMPLETED
id	No	Comma-separated list of campaign ids. Requesting only one id returns detailed information about it; see dedicated article for more information

Request sample

Fetch RUNNING and PAUSED campaigns

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v1/campaign_list?status=RUNNING,PAUSED" \
  --header "x-api-key: {YOUR_API_KEY}"

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY";
    String url = "https://api.woodpecker.co/rest/v1/campaign_list?status=RUNNING,PAUSED";

    HttpClient client = HttpClient.newHttpClient();

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .header("x-api-key", apiKey)
      .GET()
      .build();

    try {
      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println("Response: " + response.body());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

const apiKey = "YOUR_API_KEY";
const url = "https://api.woodpecker.co/rest/v1/campaign_list?status=RUNNING,PAUSED";

async function fetchCampaigns() {
  try {
    const response = await axios.get(url, {
      headers: {
        "x-api-key": apiKey,
      },
    });

    console.log("Response:", response.data);
  } catch (error) {
    console.error("Error fetching campaigns:", error.response ? error.response.data : error.message);
  }
}

fetchCampaigns();

Response

Response examples

200

An array of all campaigns meeting your criteria.

[
  {
    "id": 1234567,
    "name": "SaaS CEOs",
    "status": "RUNNING",
    "created": "2025-02-10T13:14:57+0100",
    "from_name": "Erlich Bachman",
    "from_names": ["Erlich Bachman", "Jared Dunn", "Richard Hendricks", "Jian"],
    "gdpr_unsubscribe": false,
    "folder_name": "SaaS in America",
    "folder_id": 987,
    "from_email": "erlich.bachman@piedpiper.com",
    "from_emails": [
      "erlich.bachman@piedpiper.com",
      "jared.dunn@piedpiper.com",
      "richard.hendricks@piedpiper.com",
      "jian@bachmanity.com"
    ],
    "per_day": 200,
    "bcc": "",
    "cc": "",
    "error": ""
  },
  {
    "id": 1235678,
    "name": "Test campaign",
    "status": "COMPLETED",
    "created": "2025-02-03T16:10:11+0100",
    "from_name": "Erlich Bachman",
    "from_names": ["Erlich Bachman", "Jared Dunn"],
    "gdpr_unsubscribe": true,
    "folder_name": "Finished campaigns",
    "folder_id": 954,
    "from_email": "erlich.bachman@piedpiper.com",
    "from_emails": [
      "erlich.bachman@piedpiper.com",
      "jared.dunn@piedpiper.com"
    ],
    "per_day": 120,
    "bcc": "sentemails@crm.com",
    "cc": "",
    "error": ""
  }
]

Body schema

Field	Type	Description
id	integer	Unique identifier of the campaign
name	string	Name of the campaign
status	string	Current campaign status. Possible values: RUNNING, DRAFT, STOPPED, PAUSED, EDITED, COMPLETED
created	string	Campaign creation date (ISO 8601)
from_name	string	One of the sending emails 'from name'. If multiple are used, refer to from_names instead
from_names	array[string]	A list of sender names used in the campaign
gdpr_unsubscribe	boolean	Whether GDPR-compliant unsubscribe is enabled
folder_name	string	Name of the folder the campaign is assigned to
folder_id	integer	ID of the folder the campaign is assigned to. 0 stands for general UNASSIGNED folder
from_email	string	One of the campaign sending email addresses. If multiple are used, refer to from_emails instead
from_emails	array[string]	List of campaign sending email addresses
per_day	integer	Maximum number of opening emails that can be sent per day. The limit is shared between all mailboxes
bcc	string	Email address that receives a blind copy of outgoing messages
cc	string	Email address that receives a carbon copy of outgoing messages
error	deprecated	Deprecated. Empty string

204

There are no campaigns matching your criteria

Status: 204
Body: None

400

Invalid request or malformed request syntax. Please review the request

{
  "status": {
    "status": "ERROR",
    "code": "E_WRONG_PARAM",
    "msg": "Wrong param [status]=active" | "Unknown param:state"
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

401

An issue with authorization. Please review the authorization guide

{
  "status": {
    "status": "ERROR",
    "code": "E_SESSION",
    "msg": "The API key you've entered is incorrect or no longer valid. Check if you pasted the key correctly. You can generate a new key in Woodpecker: Settings -> API Keys."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

403

API access denied. You subscription might not be active, lack the API add-on, or the key belongs to an inactive client company.

{
  "status": {
    "status": "ERROR",
    "code": "E_NO_PERMISSION",
    "msg": "Api access denied." | "You need to have an API keys addon to access our API."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

404

Please review the request URL

{
  "status": {
    "status": "ERROR",
    "code": "E_URL_NOT_FOUND",
    "msg": "URL not found: /Woodpecker/rest/v1/webhooks/someMadeUpURL"
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

409

Please review the rate limits. API v1 is subject to the same rate limits as v2, however the response code is 409 instead of 429.

{
  "status": {
    "status": "ERROR",
    "code": "E_TOO_MANY_REQUESTS",
    "msg": "Too many requests in one time"
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

500

An unknown error. Please try again later.

{
  "status": {
    "status": "ERROR",
    "code": "E_UNNOWN",
    "msg": "Unknown error."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message