Skip to main content

Get campaign

Fetch a campaign. Use this endpoint to review your campaign settings, including sending limits, attached mailboxes, and the content and settings for each step and version, such as delivery times and tracking options. You can also obtain the step or version IDs for use in update requests.

If you are looking for:

  • Campaign IDs - see rest/v1/campaign_list endpoint here
  • Campaign statistics - see rest/v1/campaign_list?id={id} endpoint here or consider predefined reports

Request​

Endpoint​

https://api.woodpecker.co/rest/v2/campaigns/{campaign_id}

Headers​

x-api-key: {YOUR_API_KEY}

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

Request sample​

Sample request​

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

Response​

Response examples​

Successful response

The below payload represents a simple one-step campaign sent from one email address. The campaign and step settings are the default values where applicable.

{
  "id": 12345678,
  "name": "One step campaign",
  "status": "DRAFT",
  "email_account_ids": [112233],
  "settings": {
    "timezone": "Europe/Warsaw",
    "prospect_timezone": false,
    "daily_enroll": 50,
    "gdpr_unsubscribe": false,
    "list_unsubscribe": false,
    "open_disabled_list": [],
    "auto_pause_prospect_from_domain": false,
    "catch_all_verification_mode": "BALANCED"
  },
  "steps": {
    "id": "b90637e7-8ccd-4df1-86a6-d07581abbf3e",
    "type": "START",
    "followup": {
      "id": "169486a5-e375-48cd-81a1-01a7f2a1895f",
      "followup": null,
      "type": "EMAIL",
      "followup_after": { "range": "DAY", "value": 1 },
      "delivery_time": {
        "MONDAY": [{ "from": "08:00", "to": "18:00" }],
        "TUESDAY": [{ "from": "08:00", "to": "18:00" }],
        "WEDNESDAY": [{ "from": "08:00", "to": "18:00" }],
        "THURSDAY": [{ "from": "08:00", "to": "18:00" }],
        "FRIDAY": [{ "from": "08:00", "to": "18:00" }]
      },
      "body": {
        "versions": [
          {
            "id": "2af5c091205511bb54acb86b43c59d378a795f67g9a8a73df34601q293e1664f",
            "version": "A",
            "subject": "Example subject line",
            "message": "<div><p>Hi {{FIRST_NAME | \"there\"}},</p><p>This is an example cold email message.</p><p>Best wishes,<br /><a href=\"https://woodpecker.co\">Woodpecker</a> team</p></div>",
            "signature": "SENDER",
            "track_opens": true
          }
        ]
      }
    }
  }
}

This section provides the body schema for each object in the campaign payloads. For a more detailed overview, please refer to the campaign schema.

Campaign configuration object
FieldTypeDescription
idintegerUnique identifier of the campaign
namestringName of the campaign
statusstringCurrent campaign status. Possible values: RUNNING, DRAFT, STOPPED, PAUSED, EDITED, COMPLETED
email_account_idsarray[integer]List of email account SMTP IDs used in this campaign. Use /mailboxes endpoint to review them
settingsobjectCampaign-level settings like timezone, sending limit, unsubscribe settings, etc
└─timezonestringThe default timezone of a campaign. It will be used when setting.prospect_timezone is disabled or when it is enabled but the prospect's timezone is not specified
└─prospect_timezonebooleanWhether to adjust sending times to prospect's timezone instead of the campaign timezone
└─daily_enrollintegerMaximum number of opening emails that can be sent per day. The limit is shared between all mailboxes
└─gdpr_unsubscribebooleanWhether the unsubscribe link should provide prospects with an option for GDPR-compliant data removal. This option will work only if the {{UNSUBSCRIBE}} snippet is included in your email or account signature
└─list_unsubscribebooleanWhether to include List-Unsubscribe header. This option will work only if the {{UNSUBSCRIBE}} snippet is included in your email or account signature
└─open_disabled_listarray[string]/nullList of email service providers (recipient's ESP) for which open tracking is disabled. Available options: google.com, outlook.com, OTHER_PROVIDER
└─auto_pause_prospect_from_domainboolean/nullWhether to automatically pause sending to prospects after a response from the same domain (free providers excluded)
└─catch_all_verification_modestringCatch-all email verification mode - how to approach contacting prospects using catch-all emails.
  • NONE - contact all catch-all emails, including undeliverable
  • BALANCED - contact deliverable and risky catch-all emails
  • MAXIMUM - contact only deliverable catch-all emails
  • ONLY_VERIFY - do not contact catch-all emails
stepsobjectCampaign steps, including all emails and their delivery times, content, etc
Steps objects
FieldTypeDescription
idstringUnique identifier of the step (UUID)
typestringSTART is always the first step of a campaign; the remaining steps are EMAIL
delivery_timeobjectTime intervals during which emails can be sent
bodyobjectEmail content configuration including A/B test versions
followup_afterobjectObject that specifies the time delay before processing a prospect in the next step; if delivery_time allows it
└─rangestringTime unit - DAY, HOUR, MINUTE
└─valueintegerValue of the time unit
followupobject/nullNext step in the sequence. Consists of an EMAIL step object. Null indicates end of sequence

Delivery time object​

FieldTypeDescription
MONDAY...SUNDAYarray[object]Array of time windows for each day. Maximum 2 windows per day. The valid keys are the days of the week: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
└─[].fromstringCampaign start time in "HH:mm" format (24-hour)
└─[].tostringCampaign end time in "HH:mm" format (24-hour)
Body object
FieldTypeDescription
body.versionsarray[object]Array of email version objects and their definitions
└─[].idstringUnique identifier of the email version (hash-based ID, 64 characters)
└─[].versionstringVersion Identifier: The default version is A. Available versions are A through E
└─[].subjectstring/nullEmail subject line. If null, the message will use the same subject line as the previous step and will be sent as a follow-up in the same thread
└─[].messagestringEmail body content in HTML format
└─[].signaturestringWhether to use the sender's email account signature. The available options are: SENDER or NO_SIGNATURE
└─[].track_opensbooleanWhether to track email opens for this email version