Skip to main content

Add campaign step

This endpoint lets you add a new step to a campaign. The new step can only be added at the end of the campaign and cannot be inserted between existing steps. Additionally, it can only be added if the parent step has not yet processed any prospects.

Only campaigns with a status of DRAFT or EDITED can be updated. To change the campaign status to EDITED use the /make_editable endpoint.

Request​

Endpoint​

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

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 order to fetch the parent_id you can use the GET /campaigns structure endpoint

{
  "parent_id": "9e8e8ebb-c6e1-4b8f-be37-a5542513dbge",
  "step": {
    "type": "EMAIL",
    "delivery_time": {
      "TUESDAY": [{ "from": "09:00", "to": "18:00" }],
      "WEDNESDAY": [{ "from": "09:00", "to": "18:00" }],
      "THURSDAY": [{ "from": "09:00", "to": "18:00" }]
    },
    "body": {
      "versions": [
        {
          "subject": null,
          "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>",
          "signature": "SENDER",
          "track_opens": true
        },
        {
          "subject": "Example subject line - version B",
          "message": "<div>{{SPINTAX | \"Hi\" | \"Hello\" | \"Good morning\"}} {{FIRST_NAME}},</div><div><br /></div><div>Yet another example of a cold email message.&nbsp;</div><div><br /></div><div>All the best,&nbsp;</div><div><a href=\"https://woodpecker.co\">Woodpecker</a> team</div><div><a href=\"{{UNSUBSCRIBE}}\">unsubscribe</a></div>",
          "signature": "NO_SIGNATURE",
          "track_opens": false
        }
      ]
    },
    "followup_after": {
      "range": "HOUR",
      "value": 10
    }
  }
}

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.

Step object

This object defines a step of a campaign, including its content, versions, delivery times, and follow-ups.

FieldTypeDefaultRequiredDescription
typestring-YESOnly accepted value is EMAIL to indicate it is an email step`
delivery_timeobject-YESTime intervals during which emails can be sent
bodyobject-YESEmail content configuration including A/B test versions
followup_afterobject1 DAYNOObject that specifies the time delay before processing a prospect in the next step; or the delay after which a prospect will be marked as NONRESPONSIVE
└─rangestringDAYNOTime unit - DAY, HOUR, MINUTE
└─valueinteger1NOValue of the time unit
Delivery time object

The delivery_time object defines the time intervals during which email messages can be sent. The timezone will follow the settings of the timezone and prospect_timezone of the campaign configuration.

FieldTypeDefaultRequiredDescription
MONDAY...SUNDAYarray[object]-YESArray of time windows for each day. Maximum 2 windows per day, at least one day must be present. The valid keys are the days of the week: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
└─[].fromstring-YESStart time in "HH:mm" format (24-hour)
└─[].tostring-YESEnd time in "HH:mm" format (24-hour)
Body object

The body and versions objects define the email content, A/B test versions, open tracking, and signature settings. Each of these can be configured individually for each version, and at least one version must be present.

FieldTypeDefaultRequiredDescription
body.versionsarray[object]-YESArray of email version objects and their definitions. At least one version is required. A/B versions will be assigned based on the order of the array
└─[].subjectstring/null-NOEmail subject line. To send the email as a follow-up in the same thread, leave this field empty. If you enter a subject line, the email will be sent in a new thread. Supports snippets like {{FIRST_NAME}} and spintax
└─[].messagestring-YESEmail body content in HTML format. Supports snippets like {{FIRST_NAME}} and spintax
└─[].signaturestringNO_SIGNATURENOWhether to use the sender's email account signature. The available options are: SENDER or NO_SIGNATURE
└─[].track_opensboolean-YESWhether to track email opens for this email version

Request sample​

Create campaign​

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/campaigns/{campaign_id}/steps" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "parent_id": "9e8e8ebb-c6e1-4b8f-be37-a5542513dbge",
    "step": {
      "type": "EMAIL",
      "delivery_time": {
        "TUESDAY": [
          {
            "from": "09:00",
            "to": "18:00"
          }
        ]
      },
      "body": {
        "versions": [
          {
            "subject": null,
            "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>",
            "signature": "SENDER",
            "track_opens": true
          }
        ]
      },
      "followup_after": {
        "range": "HOUR",
        "value": 10
      }
    }
  }'

Response​

Response examples​

The step has been added. A full campaign payload will be returned.