Skip to main content

Create campaign

Create a multichannel, LinkedIn or email campaign with a sequence of personalized follow-up messages and customizable delivery settings. Configure campaign-wide settings like timezone and daily limits, define message content with support for A/B testing, scheduled delivery windows, and time delays between steps.

Request​

Endpoint​

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

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​

The campaign payload includes several objects, which are described in detail below. In addition to the general campaign configuration, a campaign is made up of steps that define its structure and actions for each prospect. Each campaign must begin with a START step, followed by 1 to 16 EMAIL or LINKEDIN steps. Subsequent steps are linked using nested follow-up properties, forming a sequence of steps. Each step includes its own configuration and points to the next step, or null if it is the final step.

The below payload represents a simple one-step campaign sent from one email address.

{
  "name": "One-step email campaign",
  "email_account_ids": [112233],
  "settings": {
    "timezone": "Europe/Warsaw",
    "prospect_timezone": true,
    "daily_enroll": 25,
    "gdpr_unsubscribe": true,
    "list_unsubscribe": false,
    "open_disabled_list": ["google.com"],
    "auto_pause_prospect_from_domain": true,
    "catch_all_verification_mode": "BALANCED"
  },
  "steps": {
    "type": "START",
    "followup": {
      "type": "EMAIL",
      "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": [
          {
            "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": false
          }
        ]
      }
    }
  }
}

Body schema

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

The root level of the campaign payload. It provides general information about the campaign and campaign-wide settings.

FieldTypeDefaultRequiredDescription
namestring"My campaign #0"NoName of the campaign
email_account_idsarray[integer]-Yes - if campaign contains an EMAIL stepList of email account SMTP IDs used in this campaign. Use /mailboxes endpoint to review them. Chosen mailboxes must be connected to Woodpecker without issues
settingsobject-YesCampaign-level settings like timezone, sending limit, unsubscribe settings, etc
└─timezonestring-YesThe 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. List of accepted timezones
└─prospect_timezonebooleanfalseNoWhether to adjust sending times to prospect's timezone instead of the campaign timezone. Applies to EMAIL steps
└─daily_enrollinteger-YesMaximum number of prospects that can be contacted in the opening step of the campaign per day. This limit is applied per mailbox or LinkedIn account. The default maximum value is 500
└─gdpr_unsubscribebooleanfalseNoWhether 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_unsubscribebooleanfalseNoWhether 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]/null[]NoList 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/nullfalseNoWhether to automatically pause sending to prospects after a response from the same domain (free providers excluded)
└─catch_all_verification_modestringBALANCEDNoCatch-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
stepsobject-YesCampaign steps, including all LinkedIn actions or emails and their delivery times, content, etc

Step objects

The START step must always be the first (root) step of the campaign and cannot occur elsewhere.

FieldTypeDefaultRequiredDescription
typestring-YesUse START to indicate a start step
followupobject-YesThe next step in the sequence. For a START step, this field is required and must point to the first EMAIL or LINKEDIN step sent to prospects

Request samples​

Create campaign​

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/campaigns" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "email_account_ids": [ {YOUR_SMTP_IDs} ], 
    "settings": {
      "timezone": "Europe/Warsaw", 
      "daily_enroll": 30
    },
    "steps": {
      "type": "START",
      "followup": {
        "type": "EMAIL",
        "delivery_time": {
          "MONDAY": [
            {
              "from": "08:00",
              "to": "17:00"
            }
          ]
        },
        "body": {
          "versions": [
            {
              "subject": "Hi {{FIRST_NAME | \"there\"}}. {{SPINTAX | \"Hi\" | \"Hello\" | \"Good morning\"}}",
              "message": "<div>Hi {{FIRST_NAME | \"there\"}},</div><div><br /></div><div>This is an example cold email message.&nbsp;</div><div><br /></div><div>Best wishes,&nbsp;</div><div><a href=\"https://woodpecker.co\">Woodpecker</a> team</div><div><a href=\"{{UNSUBSCRIBE}}\">unsubscribe</a></div>",
              "track_opens": true
            }
          ]
        }
      }
    }
  }'

Response​

Response examples​

Campaign created. The returned body will be a full campaign payload, which consists of any optional fields that were not included in the POST request, along with the following information:

  • id - unique identifiers for the campaign, each step, and version
  • status - status of the campaign, always DRAFT after creation
  • version - version identifiers for each email, ranging from A to E

You can review the full campaign payload here.