Lemlist Developer Docs

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
}
'

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

"Bad team"

"The authentication you supplied is incorrect"

POST

sequences

{sequenceId}

steps

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
}
'

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

"Bad team"

"The authentication you supplied is incorrect"

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

Success

_id

string

type

string

delay

integer

emailTemplateId

string

message

string

Get Campaign Sequences Update Sequence Step

⌘I

Getting started

Popular Resources

Endpoints

Objects & Definitions

Add Step to Sequence

Adding Steps

Adding Conditions

Step Types and Required Fields

All Request Body Fields

LinkedIn media constraints

Authorizations

Path Parameters

Body

Response

​Adding Steps

​Adding Conditions

​Step Types and Required Fields

​All Request Body Fields

​LinkedIn media constraints

Authorizations

Path Parameters

Body

Response

Adding Steps

Adding Conditions

Step Types and Required Fields

All Request Body Fields

LinkedIn media constraints