Add Step to Sequence

Creates a step or condition within a campaign sequence.

POST /sequences/{sequenceId}/steps

cURL

Email Step

curl --request POST \ --url https://api.lemlist.com/api/sequences/{sequenceId}/steps \ --header 'Authorization: Basic <encoded-value>' \ --header 'Content-Type: application/json' \ --data ' { "type": "email", "subject": "{{firstName}}, quick question about {{companyName}}", "message": "<p>Hi {{firstName}},</p><p>I noticed {{companyName}} is working on improving customer engagement. Would you be interested in discussing how we can help?</p><p>Best regards,<br>{{senderName}}</p>", "delay": 1, "index": 2 } '

200

{
  "_id": "stp_V0JHmSpWiO0rxHUkz",
  "type": "linkedinInvite",
  "delay": 2,
  "emailTemplateId": "etp_sw6csWaZNwnfdwGZ6",
  "message": "Hello, I would like..."
}

If you want to get the main sequence or a list of sequences for a campaign, you can call /api/campaigns/{campaignId}/sequences.

Adding Steps

To add a new step to a sequence, call the API with the sequence ID in the parameters and the step details in the request body.

For example, adding a LinkedIn invite step:

{
    "type": "linkedinInvite",
    "message": "Invite message...."
}

Adding Conditions

To add a condition to a sequence, you must provide the conditionKey and type conditional along with the required fields. The API will return a condition with an array of condition sequences, where you can call the same API again to add steps to those sequences.

For example, creating a LinkedIn invite condition:

{
    "type": "conditional",
    "conditionKey": "linkedinInviteAccepted",
    "delayType": "waitUntil"
}

This will return:

{
    "_id": "stp_Ae93hiemDkypHLys2",
    "type": "conditional",
    "conditions": [
        {
            "sequenceId": "seq_jacL5GNH3YpNnuNQ2",
            "label": "Accepted invite",
            "key": "linkedinInviteAccepted",
            "delay": 1,
            "delayType": "waitUntil"
        },
        {
            "sequenceId": "seq_xzrGLxhZwoo5oxukc",
            "fallback": true
        }
    ]
}

Then you can call /api/sequences/seq_jacL5GNH3YpNnuNQ2/steps to add a send step if the invite is accepted:

{
    "type": "linkedinSend",
    "message": "Hello, ..."
}

Step Types and Required Fields

The table below summarizes the required and optional fields for each step type. Note that all step requests must include a common type field.

Step Type	Required Fields	Optional Fields
email	subject, message	index, delay
manual	title	message, index, delay
phone	-	message, index, delay
api	method, url	index, delay
linkedinVisit	-	index, delay
linkedinInvite	-	message, images, videos, index, delay
linkedinSend	message	altMessage, images, videos, index, delay
linkedinVoiceNote	-	index, delay, recordMode
linkedinFollow	-	index, delay
linkedinLikeLastPost	-	index, delay
linkedinCommentLastPost	-	index, delay
linkedinEndorse	-	index, delay, skillName, endorseAnyFallback
linkedinWithdrawInvitation	-	index, delay
sendToAnotherCampaign	campaignId	index, delay
conditional	conditionKey, delayType (and delay when delayType is within)	index
whatsappMessage	message	index, delay
sms	message	index, delay

In conditional steps, if the delayType is not "within", the delay field is not required.

linkedinVoiceNote steps are created as skeletons via the API: the audio payload itself is not accepted here and must be added afterwards from the lemlist UI. The recordMode field controls how the audio is sourced — with manual (default), a user records the note themselves; with ai, a user provides a text template that lemlist converts to audio at send time.

All Request Body Fields

Field	Description
type (String, Required)	The type of step to create. Allowed values: email, manual, phone, api, linkedinVisit, linkedinInvite, linkedinSend, linkedinVoiceNote, linkedinFollow, linkedinLikeLastPost, linkedinCommentLastPost, linkedinEndorse, linkedinWithdrawInvitation, sendToAnotherCampaign, conditional, whatsappMessage, sms
index (Integer, Optional)	The position within the sequence to insert the new step. Must be an integer ≥ -1. If omitted or if the index is greater than the number of steps, the new step is added to the end
delay (Integer, Optional)	The delay (in days) before executing the step. Must be between 0 and 1500. Defaults to 0 for the first step and to 1 for subsequent steps (except for certain conditional configurations)
subject (String, Conditional)	The email subject. Required for steps of type email. Maximum 400 characters (applied to the raw template, including any Liquid syntax)
message (String, Conditional)	Content of the email or message. Used for email, linkedinInvite, linkedinSend, whatsappMessage, and sms step types, or the note of manual and phone step types. Required for linkedinSend, whatsappMessage, and sms
altMessage (String, Conditional)	An alternate message for steps of type linkedinSend
title (String, Conditional)	A title or label used in manual steps. Maximum 400 characters
method (String, Conditional)	The HTTP method to use for API steps. Allowed values: GET, POST, PUT, DELETE, PATCH
url (String, Conditional)	The URL of the API endpoint to call. Must be a valid URL (starting with http:// or https://)
conditionKey (String, Conditional)	For conditional steps only. Defines the condition key. Allowed values: hasEmailAddress, hasLinkedinUrl, hasPhoneNumber, hasScore, emailsOpened, emailsClicked, emailsUnsubscribed, meetingBooked, linkedinInviteAccepted, linkedinOpened, aircallDone, linkedinNetworkCheck, hasWhatsappAccount
delayType (String, Conditional)	For conditional steps only. Specifies the delay type. Allowed values: within, waitUntil
campaignId (String, Conditional)	For steps of type sendToAnotherCampaign only. The target campaign ID to which a lead should be sent. The specified campaign must exist in the team and not be archived
images (Array of strings, Optional)	For linkedinInvite and linkedinSend steps only. Public HTTPS URLs of images to attach to the LinkedIn message. lemlist downloads each file and re-hosts it. See the LinkedIn media constraints below
videos (Array of strings, Optional)	For linkedinInvite and linkedinSend steps only. Public HTTPS URLs of videos to attach to the LinkedIn message. lemlist downloads each file and re-hosts it. See the LinkedIn media constraints below
skillName (String, Optional)	For linkedinEndorse steps only. Name of the LinkedIn skill to endorse on the lead’s profile
endorseAnyFallback (Boolean, Optional)	For linkedinEndorse steps only. When true and the named skill is not on the lead’s profile, lemlist falls back to endorsing any available skill
recordMode (String, Optional)	For linkedinVoiceNote steps only. Determines how the audio is sourced. Allowed values: manual (user records the audio after step creation; default), ai (audio is generated from a text template provided in the lemlist UI)

LinkedIn media constraints

When you pass images or videos to a linkedinInvite or linkedinSend step, each URL must be a publicly reachable HTTPS URL. lemlist fetches the file, validates it, and re-hosts it before attaching it to the LinkedIn message.

Constraint	Value
Maximum items per step	6 (combined across images + videos)
Maximum file size	20 MB per file
Allowed image MIME types	image/png, image/jpeg, image/gif
Allowed video MIME types	video/mp4, video/quicktime

If ingestion fails, the API returns a 4xx/5xx status with one of the following error codes:

Code	HTTP status	Meaning
LINKEDIN_MEDIA_TOO_MANY	400	More than 6 items submitted
LINKEDIN_MEDIA_UNSAFE_URL	400	URL is not HTTPS or not publicly reachable
LINKEDIN_MEDIA_TOO_LARGE	413	File exceeds 20 MB
LINKEDIN_MEDIA_INVALID_TYPE	415	File MIME type is not allowed
LINKEDIN_MEDIA_GIF_INVALID	422	GIF does not meet LinkedIn’s constraints
LINKEDIN_MEDIA_DOWNLOAD_FAILED	502	lemlist could not download the file
LINKEDIN_MEDIA_AV_UNAVAILABLE	503	Antivirus scanner is unavailable
LINKEDIN_MEDIA_TIMEOUT	504	Ingestion took longer than 45 seconds

Authorizations

Authorization · string · header · required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Path Parameters

sequenceId · string · required

The unique identifier of the sequence

Body

application/json

type · enum<string>

The type of step to create

Available options: email, manual, phone, api, linkedinVisit, linkedinInvite, linkedinSend, linkedinVoiceNote, linkedinFollow, linkedinLikeLastPost, linkedinCommentLastPost, linkedinEndorse, linkedinWithdrawInvitation, sendToAnotherCampaign, conditional, whatsappMessage, sms

index · integer

The position within the sequence to insert the new step (≥ -1). If omitted or greater than the number of steps, the new step is added to the end

delay · integer

Delay in days before executing this step. Defaults to 0 for the first step and 1 for subsequent steps

subject · string

Email subject line (required for email steps)

message · string

Content of the email or message (used for email, linkedinInvite, linkedinSend, manual, phone, whatsappMessage, sms steps). Required for linkedinSend, whatsappMessage, and sms

altMessage · string

Alternate message for linkedinSend steps

title · string

Title or label for manual steps

method · enum<string>

HTTP method for API steps

Available options: GET, POST, PUT, DELETE, PATCH

url · string

URL of the API endpoint to call (required for api steps). Must start with http:// or https://

conditionKey · enum<string>

Condition key for conditional steps

Available options: hasEmailAddress, hasLinkedinUrl, hasPhoneNumber, hasScore, emailsOpened, emailsClicked, emailsUnsubscribed, meetingBooked, linkedinInviteAccepted, linkedinOpened, aircallDone, linkedinNetworkCheck, hasWhatsappAccount

delayType · enum<string>

Delay type for conditional steps

Available options: within, waitUntil

campaignId · string

Target campaign ID for sendToAnotherCampaign steps. The campaign must exist and not be archived

images · string<uri>[]

Public HTTPS URLs of images to attach to a linkedinInvite or linkedinSend step. lemlist downloads each file and re-hosts it. Allowed MIME types: image/png, image/jpeg, image/gif. Up to 20 MB per file, and up to 6 items total combined with videos.

videos · string<uri>[]

Public HTTPS URLs of videos to attach to a linkedinInvite or linkedinSend step. lemlist downloads each file and re-hosts it. Allowed MIME types: video/mp4, video/quicktime. Up to 20 MB per file, and up to 6 items total combined with images.

skillName · string

Name of the LinkedIn skill to endorse on the lead's profile. Applies to linkedinEndorse steps only.

endorseAnyFallback · boolean

Applies to linkedinEndorse steps only. When true and the named skill is not on the lead's profile, lemlist falls back to endorsing any available skill.

recordMode · enum<string>

Applies to linkedinVoiceNote steps only. Determines how the audio is sourced. manual (default) means the user records the audio themselves from the lemlist UI after step creation; ai means lemlist generates the audio from a text template provided in the lemlist UI.

Available options: manual, ai

Response

200

application/json

Success

_id · string

type · string

delay · integer

emailTemplateId · string

message · string