lemlist Campaigns API
Campaign CRUD and lifecycle - create, update, duplicate, start, pause, validation statutes, stats, reports and asynchronous exports.
OpenAPI Specification
openapi: 3.0.0
info:
title: lemlist Campaigns API
version: 1.0.0
description: The Campaigns operations of the lemlist API, split by tag from the OpenAPI lemlist publishes
at https://developer.lemlist.com/api-reference/openapi/v2.json. Operation content is carried verbatim
from the provider spec.
servers:
- url: https://api.lemlist.com/api
security:
- basicAuth: []
tags:
- name: Campaigns
paths:
/campaigns:
get:
summary: Get Many Campaigns
tags:
- Campaigns
parameters:
- name: offset
in: query
required: false
description: Offset from the start. For pagination.
example: '24'
schema:
type: integer
- name: limit
in: query
required: false
description: 'Number of campaigns to retrieve. Default: 100. Maximum: 100.'
example: '2'
schema:
type: integer
- name: version
in: query
required: false
description: Set to 'v2' to use the latest version
example: v2
schema:
type: string
default: v2
enum:
- v2
- name: page
in: query
required: false
description: Page number to retrieve
example: '1'
schema:
type: integer
- name: sortBy
in: query
required: false
description: The field by which to sort. Currently, only 'createdAt' is supported.
example: createdAt
schema:
type: string
enum:
- createdAt
- name: sortOrder
in: query
required: false
description: The sort direction. Use 'desc' for descending order; any other value (or omission)
will sort in ascending order.
example: desc
schema:
type: string
enum:
- asc
- desc
- name: status
in: query
required: false
description: 'The campaign status. Can be: running, draft, archived, ended, paused, errors. Note:
a campaign can be in multiple statuses at one time (e.g., a paused campaign with errors).'
example: running
schema:
type: string
enum:
- running
- draft
- archived
- ended
- paused
- errors
- name: createdBy
in: query
required: false
description: Filter campaigns by creator user ID (usr_xxx format). Only returns campaigns created
by the specified user.
example: usr_QG9E94KvTmC7KWqzs
schema:
type: string
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Campaign'
example:
- _id: cam_4HrZbi8xsez4QlrnL
name: Product Launch Campaign
emoji: 🚀
timezone: Europe/Paris
labels: []
createdAt: '2025-02-20T14:45:54.230Z'
createdBy: usr_zdTCrNFyXblc4mrYK
status: running
hasError: true
errors:
- Your campaign does not have sender.
- _id: cam_k3gu2sa4KIfhRK34M
name: Sales Outreach 2025
labels: []
createdAt: '2025-02-05T09:00:07.541Z'
createdBy: usr_UEvrOEP0CTAYEoFR4
status: running
hasError: true
errors:
- One of your sender has no email provider.
- Your campaign have an invalid sender mailbox
- _id: cam_HcFmYEhnCI39Pscan
name: CRM Integration Test
labels:
- CRM
createdAt: '2023-01-27T14:58:52.482Z'
createdBy: usr_i52PiQtbq8SucjVTM
status: running
hasError: true
errors:
- One of your sender has no email provider.
- Your campaign have an invalid sender mailbox
- _id: cam_yZXeC6q3SXs3ha1FI
name: Customer Onboarding
labels: []
createdAt: '2022-06-14T13:32:57.880Z'
createdBy: usr_i52PiQtbq8SucjVTM
status: running
'400':
description: No API key provided
content:
text/plain:
example: No API key provided
'401':
description: The authentication you supplied is incorrect
content:
text/plain:
example: The authentication you supplied is incorrect
'403':
description: User linked to this API key is blocked
content:
text/plain:
example: User linked to this API key is blocked
'404':
description: No user found for this API key
content:
text/plain:
example: No user found for this API key
post:
summary: Create Campaign
tags:
- Campaigns
parameters: []
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
sequenceId:
type: string
scheduleIds:
type: array
items:
type: string
teamId:
type: string
createdBy:
type: string
createdAt:
type: string
format: date-time
state:
type: string
scannedCount:
type: integer
reviewedCount:
type: integer
inSequenceLeadCount:
type: integer
variableKeys:
type: array
items: {}
senders:
type: array
items: {}
sendUsers:
type: array
items: {}
displayedVariableKeys:
type: array
items:
type: string
emoji:
type: string
stopOnEmailReplied:
type: boolean
crmOpportunitiesOnTask:
type: boolean
unsubscribe:
type: string
name:
type: string
crm:
type: string
crmUserId:
type: string
example:
_id: cam_kok3I33Sba7mcNIO7
sequenceId: seq_ScVmFnlKdP6aVmyZN
scheduleIds:
- skd_IrCdCoQ0ZUAEeUDwR
teamId: tea_edrkv2LgUK4Wf4ZzO
createdBy: usr_Sy3xIhbEi7auHFv5A
createdAt: '2025-01-16T13:53:22.726Z'
state: running
scannedCount: 0
reviewedCount: 0
inSequenceLeadCount: 0
variableKeys: []
senders: []
sendUsers: []
displayedVariableKeys:
- companyName
emoji: 🚀
stopOnEmailReplied: true
crmOpportunitiesOnTask: true
unsubscribe: campaign
name: My new campaign
crm: hubspot
crmUserId: usr_0p9Q8ZyXSTNGpsHOe
'400':
description: No API key provided
content:
text/plain:
example: No API key provided
'401':
description: The authentication you supplied is incorrect
content:
text/plain:
example: The authentication you supplied is incorrect
'403':
description: User linked to this API key is blocked
content:
text/plain:
example: User linked to this API key is blocked
'404':
description: No user found for this API key
content:
text/plain:
example: No user found for this API key
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the campaign
timezone:
type: string
description: IANA timezone for the campaign schedule (e.g. `America/New_York`). Defaults
to `Europe/Paris` if omitted.
autoReview:
type: boolean
description: Automatically launch (review) leads as soon as they are added to the campaign,
instead of requiring manual review. Defaults to `false`.
autoReviewConditions:
type: array
items:
type: string
enum:
- deliverable
- risky
- undeliverable
- unverified
description: Email deliverability statuses for which a lead is auto-launched when `autoReview`
is enabled. Only leads whose email verification matches one of these statuses are
launched automatically. Invalid values are rejected with a `400` error.
required:
- name
example:
name: My new campaign
timezone: America/New_York
autoReview: true
autoReviewConditions:
- deliverable
- risky
/campaigns/{campaignId}:
get:
summary: Get Campaign
tags:
- Campaigns
parameters: []
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
example:
_id: cam_bSn8EORHQxbWPjHvu
name: Product Launch Campaign
createdAt: '2025-10-27T07:01:04.058Z'
status: draft
creator:
userId: usr_ahfFktBBHUIxbVG5P
userEmail: support@lemlist.com
senders:
- id: usr_rhhX1KT0qgOGCOrgE
email: support@lemlist.com
sendUserMailboxId: usm_J7BzS86A1vRMc2AuB
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
'404':
description: Campaign not found
content:
text/plain:
example: Campaign not found
parameters:
- name: campaignId
in: path
required: true
description: The unique identifier of the campaign
example: cam_A1B2C3D4E5F6G7H8I9
schema:
type: string
patch:
summary: Update Campaign
tags:
- Campaigns
parameters: []
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
description: Success
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The campaign name
stopOnEmailReplied:
type: boolean
description: Stop the campaign when a lead replies by email
stopOnMeetingBooked:
type: boolean
description: Stop the campaign when a meeting is booked
stopOnLinkClicked:
type: boolean
description: Stop the campaign when a link is clicked
leadsPausedByInterest:
type: boolean
description: Pause leads based on interest
opportunityReplied:
type: boolean
description: Create an opportunity when a lead replies
opportunityClicked:
type: boolean
description: Create an opportunity when a lead clicks a link
autoLeadInterest:
type: boolean
description: Automatically detect lead interest
disableTrackOpen:
type: boolean
description: Disable tracking of email opens
disableTrackClick:
type: boolean
description: Disable tracking of link clicks
disableTrackReply:
type: boolean
description: Disable tracking of email replies
disableOutOfOffice:
type: boolean
description: Disable out-of-office detection
sequenceSharing:
type: boolean
description: Enable sequence sharing for the campaign
stopOnLinkClickedFilter:
type: string
description: Filter for which link clicks should stop the campaign
sendUsers:
type: array
description: Configured senders for the campaign. Only present when sendUserIds was
provided in the request. Senders that lack capabilities for any campaign sending
channel are excluded.
items:
type: object
properties:
id:
type: string
description: User ID of the sender
mailboxes:
type: array
description: Connected email mailboxes
items:
type: object
properties:
sendUserMailboxId:
type: string
email:
type: string
phoneNumbers:
type: array
description: Connected phone numbers
items:
type: string
whatsappAccountIds:
type: array
description: Connected WhatsApp account IDs
items:
type: string
example:
name: New campaign name
stopOnEmailReplied: true
stopOnMeetingBooked: true
stopOnLinkClicked: false
leadsPausedByInterest: false
opportunityReplied: true
opportunityClicked: false
autoLeadInterest: true
disableTrackOpen: false
disableTrackClick: false
disableTrackReply: false
disableOutOfOffice: false
sequenceSharing: false
sendUsers:
- id: usr_2aBCdEfGHiJkLmNOp
mailboxes:
- sendUserMailboxId: smb_1aBcDeFgHiJkLmNoP
email: john@acme.com
phoneNumbers:
- '+15551234567'
whatsappAccountIds:
- wha_3xYzAbCdEfGhIjKlM
- id: usr_7xYzAbCdEfGhIjKlM
mailboxes:
- sendUserMailboxId: smb_9zYxWvUtSrQpOnMlK
email: jane@acme.com
phoneNumbers: []
whatsappAccountIds: []
'400':
description: Bad request
content:
text/plain:
schema:
type: string
examples:
badTeam:
summary: Bad team
value: Bad team
dynamicStrategy:
summary: Cannot update senders for dynamic strategy campaigns
value: Cannot update senders on campaigns with a dynamic sender strategy (contactOwner,
leadImporter, customField)
noValidSenders:
summary: No valid sender IDs
value: None of the provided sender IDs are members of this team
noCapableSenders:
summary: No senders with required capabilities
value: None of the provided senders have the required capabilities for this campaign
missingChannels:
summary: Campaign channels not covered
value: 'The provided senders do not cover the following campaign channels: linkedin,
sms'
'401':
description: Unauthorized
'404':
description: Campaign not found
content:
text/plain:
example: Campaign not found
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The campaign name
stopOnEmailReplied:
type: boolean
description: Stop the campaign when a lead replies by email
stopOnMeetingBooked:
type: boolean
description: Stop the campaign when a meeting is booked
stopOnLinkClicked:
type: boolean
description: Stop the campaign when a link is clicked
leadsPausedByInterest:
type: boolean
description: Pause leads based on interest
opportunityReplied:
type: boolean
description: Create an opportunity when a lead replies
opportunityClicked:
type: boolean
description: Create an opportunity when a lead clicks a link
autoLeadInterest:
type: boolean
description: Automatically detect lead interest
disableTrackOpen:
type: boolean
description: Disable tracking of email opens
disableTrackClick:
type: boolean
description: Disable tracking of link clicks
disableTrackReply:
type: boolean
description: Disable tracking of email replies
disableOutOfOffice:
type: boolean
description: Disable out-of-office detection
sequenceSharing:
type: boolean
description: Enable sequence sharing for the campaign
stopOnLinkClickedFilter:
type: string
description: Filter for which link clicks should stop the campaign
sendUserIds:
type: array
items:
type: string
description: 'Array of user IDs (usr_xxx format) to assign as campaign senders. Cannot
be used on campaigns with a dynamic sender strategy (contactOwner, leadImporter, customField).
Each sender is validated against the campaign''s sending channels (email, LinkedIn,
SMS, WhatsApp): senders without capabilities for at least one channel are excluded,
and all channels must be covered by at least one sender.'
autoReview:
type: boolean
description: Automatically launch (review) leads as soon as they are added to the campaign,
instead of requiring manual review.
autoReviewConditions:
type: array
items:
type: string
enum:
- deliverable
- risky
- undeliverable
- unverified
description: Email deliverability statuses for which a lead is auto-launched when `autoReview`
is enabled. Only leads whose email verification matches one of these statuses are
launched automatically. Invalid values are rejected with a `400` error.
aiFeatures:
type: object
description: AI reply-handling settings. Provide only the flags to change; omitted flags
keep their current value.
properties:
scoreReplies:
type: boolean
description: Enable AI reply scoring for this campaign.
onInterestedReply:
type: object
description: AI action when a reply is detected as INTERESTED.
properties:
enabled:
type: boolean
description: Enable the interested-reply AI action.
pauseAllCampaignsForLead:
type: boolean
description: Pause all campaigns for this lead.
pauseCampaignForCompany:
type: boolean
description: Pause this campaign for other leads in the same company.
pauseAllCampaignsForCompany:
type: boolean
description: Pause all campaigns for leads in the same company.
onNotInterestedReply:
type: object
description: AI action when a reply is detected as NOT interested.
properties:
enabled:
type: boolean
description: Enable the not-interested-reply AI action.
pauseAllCampaignsForLead:
type: boolean
description: Pause all campaigns for this lead.
pauseCampaignForCompany:
type: boolean
description: Pause this campaign for other leads in the same company.
pauseAllCampaignsForCompany:
type: boolean
description: Pause all campaigns for leads in the same company.
tracking:
type: object
description: Open / click / reply tracking toggles.
properties:
trackOpens:
type: boolean
description: Whether email open tracking is enabled.
trackClicks:
type: boolean
description: Whether link click tracking is enabled.
trackReplies:
type: boolean
description: Whether reply tracking is enabled.
onReplied:
type: object
description: Behavior when a lead replies.
properties:
createNewTask:
type: boolean
description: Create a task when a lead replies.
campaignProgress:
type: string
enum:
- continue
- pause
- stop
description: What happens to the lead on reply.
propagateProgressToCompany:
type: boolean
description: Apply the same action to other leads in the same company.
disableOutOfOffice:
type: boolean
description: Whether out-of-office detection is disabled.
onLinkClicked:
type: object
description: Behavior when a lead clicks a tracked link.
properties:
createNewTask:
type: boolean
description: Create a task when a lead clicks a link.
campaignProgress:
type: string
enum:
- continue
- pause
- stop
description: What happens to the lead on link click.
propagateProgressToCompany:
type: boolean
description: Apply the same action to other leads in the same company.
specificLinks:
type: array
items:
type: string
description: If non-empty, only these link URLs trigger the action (empty = all
links).
onMeetingBooked:
type: object
description: Behavior when a meeting is booked.
properties:
campaignProgress:
type: string
enum:
- continue
- pause
- stop
description: What happens to the lead when a meeting is booked.
propagateProgressToCompany:
type: boolean
description: Apply the same action to other leads in the same company.
example:
name: New campaign name
stopOnEmailReplied: true
stopOnMeetingBooked: true
stopOnLinkClicked: false
leadsPausedByInterest: false
opportunityReplied: true
opportunityClicked: false
autoLeadInterest: true
disableTrackOpen: false
disableTrackClick: false
disableTrackReply: false
disableOutOfOffice: false
sequenceSharing: false
sendUserIds:
- usr_2aBCdEfGHiJkLmNOp
- usr_7xYzAbCdEfGhIjKlM
autoReview: true
autoReviewConditions:
- deliverable
- risky
/campaigns/{campaignId}/pause:
post:
summary: Pause Campaign
tags:
- Campaigns
parameters: []
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
state:
type: string
example:
_id: cam_A1B2C3D4E5F6G7H8I9
state: paused
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
'404':
description: Campaign not found
content:
text/plain:
example: Campaign not found
parameters:
- name: campaignId
in: path
required: true
description: The unique identifier of the campaign
example: cam_A1B2C3D4E5F6G7H8I9
schema:
type: string
/campaigns/{campaignId}/start:
post:
summary: Start Campaign
tags:
- Campaigns
parameters: []
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
state:
type: string
example:
_id: cam_A1B2C3D4E5F6G7H8I9
state: running
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
'404':
description: Campaign not found
content:
text/plain:
example: Campaign not found
parameters:
- name: campaignId
in: path
required: true
description: The unique identifier of the campaign
example: cam_A1B2C3D4E5F6G7H8I9
schema:
type: string
/campaigns/{campaignId}/export/start:
get:
summary: Start Campaign Stats Export
description: Start an asynchronous export of all campaign statistics. The final export result is
a CSV file.
tags:
- Campaigns
parameters: []
responses:
'200':
description: Export started successfully
content:
application/json:
schema:
type: object
properties:
_id:
type: string
description: The unique identifier of the export
id:
type: string
description: The unique identifier of the export (same as _id)
teamId:
type: string
description: The team identifier
campaignId:
type: string
description: The campaign identifier
campaignName:
type: string
description: The name of the campaign
status:
type: string
enum:
- pending
- done
- error
description: Current status of the export
startedAt:
type: string
format: date-time
description: When the export was started
progressIndex:
type: integer
description: Current progress index
progressTime:
type: integer
description: Timestamp of progress
progressLastStepDuration:
type: integer
description: Duration of last step in milliseconds
progressType:
type: string
description: Type of current progress step
progress:
type: integer
description: Number of items processed
total:
type: integer
description: Total number of items to process
example:
_id: axp_Vv6lJOc8NlVVmDud5
id: axp_Vv6lJOc8NlVVmDud5
teamId: tea_c123fg5h8ijKL9noP
campaignId: cam_A1B2C3D4E5F6G7H8I9
campaignName: Insights Outreach 2024
status: pending
startedAt: '2024-07-09T13:43:52.124Z'
progressIndex: 0
progressTime: 1720532632124
progressLastStepDuration: 0
progressType: starting
progress: 0
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lemlist/refs/heads/main/openapi/lemlist-campaigns-api-openapi.yml