Introduction
Welcome to the lemlist Developer Documentation.
lemlist is very customizable and open. You'll find on this page all the API and integration you can do with lemlist.
Rate Limit
lemlist's API rate limits requests in order to prevent abuse and overload of our services.
Rate limits are applied on all routes and per api key performing the request.
The rate limits are 20 requests per 2 seconds.
The response provide any information you may need about it:
Example of values for the rate limit headers
{
"Retry-After": 2,
"X-RateLimit-Limit": 20,
"X-RateLimit-Remaining": 7,
"Retry-After" : "Tue Feb 16 2021 09:02:42 GMT+0100 (Central European Standard Time)"
}
Header | Description |
---|---|
Retry-After | The number of second in which you can retry |
X-RateLimit-Limit | The maximum requests in that time |
X-RateLimit-Remaining | The number of remaining requests you can make |
X-RateLimit-Reset | The date when the rate limit will reset |
Definitions
Lead
A lead, recipient or buddy-to-be is a person that you try to contact using lemlist. Lead is the developer term in the API and is the same thing than buddy-to-be in the app. You know... marketing...
Unsubscribe
Unsubscribe is the developer term for the graveyard. Where person decide that they don't want to receive email from you anymore.
Authentication
To authorize, use this code:
curl https://api.lemlist.com/api/team \
--user ":YourApiKey"
Or
curl https://api.lemlist.com/api/team?access_token=YourApiKey
Make sure to replace
YourApiKey
with your API key.
All API routes are using the dedicated sub domain api.lemlist.com
.
lemlist uses API keys to allow access to the API. You can get your lemlist API key at our integration page.
You need to add the Authorization
header using the Basic
authentication type. login:password
where the login is always empty and the password is the API key.
Or pass your API key as a query parameter access_token
Team
Get Team Information
curl https://api.lemlist.com/api/team \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id": "tea_aaqam5a3BkY8aje24",
"name": "PiedPiper",
"userIds": ["usr_aawMB5Gd5JJCFYvjp"],
"createdBy": "usr_aawMB5Gd5JJCFYvjp",
"createdAt": "2018-04-30T12:19:42.829Z",
"apiKey": "aa13722b45b9c475cc686231b1af6583",
"billing": {
"quantity": 1,
"ok": true,
"plan": "freetrial"
},
}
This endpoint retrieves information of your team.
HTTP Request
GET https://api.lemlist.com/api/team
Query Parameters
No parameters.
Campaigns
Get a specific campaign by id
curl https://api.lemlist.com/api/campaigns/:campaignId \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id": "cam_aaWL92T22Sei3Bz6v",
"name": "Campaign1",
"labels": ["label 1", "label 2"]
}
This endpoint retrieves a campaign. Labels in returned object is optional if there are no label on campaign
HTTP Request
GET https://api.lemlist.com/api/campaigns/:campaignId
Query Parameters
Parameter | Description |
---|---|
campaignId | Id of the campaign to retrieve. |
List All Campaigns
curl https://api.lemlist.com/api/campaigns \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id": "cam_aaWL92T22Sei3Bz6v",
"name": "Campaign1",
"labels": ["label 1", "label 2"]
}, {
"_id": "cam_aaXwBiebA8pWPKqpK",
"name": "Campaign2"
}]
Example with offset:
curl https://api.lemlist.com/api/campaigns?offset=100 \
--user ":YourApiKey"
The above command returns max 100 campaigns starting from the 100th campaign.
This endpoint retrieves the list of all campaigns.
HTTP Request
GET https://api.lemlist.com/api/campaigns
Query Parameters
Parameter | Description |
---|---|
offset | (Optional) Offset from the start. For pagination. |
limit | (Optional) Number of campaigns to retrieve. 100 per default ( and 100 max ). |
Start Export of a Campaign
curl https://api.lemlist.com/api/campaigns/cam_123456/export/start \
--user ":YourApiKey"
The above command returns an export ID for the campaign
cam_123456
{
"id":"exp_123456",
"teamId":"team_123456",
"campaignId":"cam_123456",
"campaignName":"my new campaign",
"status":"pending",
"startedAt":"2020-01-01T00:00:00.000Z",
"progressIndex":0,
"progressTime":1639138958972,
"progressLastStepDuration":0,
"progressType":"starting",
"progress":0,
"total":0
}
returned object in case of success, note the
exportId
property
{
"ok": false,
"message": "An error occurred"
}
returned object in case of failure
This endpoint start an asynchronous export of all the statistics of a campaign. The final export result is a CSV file.
You first start an export, get an export ID, and then periodically check the status of the export with the /status endpoint. You should stop as soon as you have a status that is different than "pending".
It is "export ID based" and not "campaign ID based" so multiple exports on the same campaign can be done (let's say one started by a user in the application and another by a script).
HTTP Request
GET https://api.lemlist.com/api/campaigns/:campaignId/export/start
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign to export. |
Get status of a campaign export
curl https://api.lemlist.com/api/campaigns/cam_123456/export/exp_123456/status \
--user ":YourApiKey"
The above command returns the status of a export
{
"ok":true,
"status":{
"id":"exp_123456",
"teamId":"team_123456",
"campaignId":"cam_123456",
"campaignName":"my new campaign",
"status":"done",
"startedAt":"2020-01-01T00:00:00.000Z",
"endedAt":"2020-01-01T00:00:00.000Z",
"progressIndex":6,
"progressTime":1639138959979,
"progressLastStepDuration":476,
"progressType":"done",
"progress":0,
"total":0,
"url":"https://api.lemlist.com/api/files/exports/fil_exp_my_new_campaign.csv"
}
}
returned object in case of success, note the
status
andurl
properties
This endpoint checks the status of an asynchronous export.
campaignId and exportId are required.
In the returned object :
status
can be "pending", "done", or "error".url
gives the final CSV file URL (only if the status is "done").
Expiration time
Status are available for 2h only. An export that is still pending after 2h will be considered as failed and HTTP request statusCode will be 404. When you obtain the CSV file URL, you have to download the file in a 24 hours time frame. After that, the file will be deleted.
HTTP Request
GET https://api.lemlist.com/api/campaigns/:campaignId/export/:exportId/status
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign that was exported with the /start endpoint. |
exportId | The ID of the export that was returned by the /start endpoint. |
Set an email for a campaign export
curl https://api.lemlist.com/api/campaigns/cam_123/export/exp_123/email/email@domain.com \
--user ":YourApiKey"
The above command set the email for the export
exp_123456
{
"ok":true,
"status":{
"id":"exp_123",
"teamId":"team_123",
"campaignId":"cam_123",
"campaignName":"my new campaign",
"status":"pending",
"startedAt":"2020-01-01T00:00:00.000Z",
"progressIndex":6,
"progressTime":1639139515998,
"progressLastStepDuration":367,
"progressType":"done",
"progress":0,
"total":0,
"email":"email@domain.com"
}
}
returned object in case of success, export finished
{
"ok":true,
"status":{
"id":"exp_123",
"teamId":"team_123",
"campaignId":"cam_123",
"campaignName":"my new campaign",
"status":"done",
"startedAt":"2020-01-01T00:00:00.000Z",
"endedAt":"2020-01-01T00:00:00.000Z",
"progressIndex":6,
"progressTime":1639139515998,
"progressLastStepDuration":367,
"progressType":"done",
"progress":0,
"total":0,
"url":"https://api.lemlist.com/api/files/exports/fil_exp_my_new_campaign.csv",
"email":"email@domain.com"
}
}
returned object in case of success, export in progress
This endpoint set an email for a given export. When the export is done an email with the download url will be sent to the address provided.
campaignId and exportId are required.
HTTP Request
PUT https://api.lemlist.com/api/campaigns/:campaignId/export/:exportId/email/:email
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign that was exported with the /start endpoint. |
exportId | The ID of the export that was returned by the /start endpoint. |
The email address to send the export url to when the export is done. |
Synchronously Export Statistics of a Campaign (DEPRECATED)
curl https://api.lemlist.com/api/campaigns/cam_123456/export \
--user ":YourApiKey"
The above command returns the CSV file for the campaign
cam_123456
This endpoint downloads a CSV file that contains all the statistics of a campaign.
This synchronous endpoint is DEPRECATED since Dec, 3rd 2021 and will be removed in a future version. Please use the /start asynchronous endpoint instead.
HTTP Request
GET https://api.lemlist.com/api/campaigns/:campaignId/export
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign to retrieve. |
Export Leads of a Campaign
curl https://api.lemlist.com/api/campaigns/cam_123456/export/leads?state=all \
--user ":YourApiKey"
The above command returns the CSV file for the campaign
cam_123456
This endpoint downloads a CSV file that contains all the leads of a campaign.
HTTP Request
GET https://api.lemlist.com/api/campaigns/:campaignId/export/leads?state=all
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign to retrieve. |
Query Parameters
Parameter | Description |
---|---|
state=all | Filter to export only the specified states, all will export all states. Possible states are imported, scanned, skipped, reviewed, contacted, hooked, attracted, warmed, notInterested, interested, emailsBounced, failed, emailsUnsubscribed |
State | Description |
---|---|
imported | All the leads that were imported without any other processing (not scanned, no step sent, not reviewed...) |
scanned | All the leads that were scanned by linkedIn, or dropcontact |
skipped | All the leads that were skipped during review |
reviewed | All the leads that were reviewed |
contacted | All the leads that were contacted (a step was done for this lead, without any response or click yet) |
hooked | All the leads that opened an email or linkedIn |
attracted | All the leads that clicked in an email, accepted a linkedIn invite |
warmed | All the leads that replied to an email, or a linkedIn |
notInterested | All the leads that were mark as notInterested |
interested | All the leads that were mark as interested |
emailsBounced | All the leads where at least one step bounced, either an email or a linkedIn or an api call |
emailsUnsubscribed | All the leads that were an unsubscribe |
failed | Deprecated, use emailsBounced |
Add a Lead in a Campaign
curl -X POST https://api.lemlist.com/api/campaigns/cam_aa7uvyxECcni5KXBM/leads/richard@piedpiper.com \
-H "Content-Type: application/json" \
--data '{"firstName":"Richard","lastName":"Hendricks","companyName":"Piedpiper","icebreaker":"Icebreaker text", "phone":"(555) 555-1234","picture":"https://piedpiper.com/richard-hendricks.jpg", "linkedinUrl":"https://www.linkedin.com/in/richard-hendricks/"}' \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"campaignId": "cam_aa7uvyxECcni5KXBM",
"campaignName": "Campaign1",
"leadUrl":"https://api.lemlist.com/api/leads/richard%40piedpiper.com",
"_id":"lea_aaNfSAHJoa4gj86Px",
"isPaused":false,
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks",
"companyName":"Piedpiper",
"icebreaker":"Icebreaker text",
"phone":"(555) 555-1234",
"picture":"https://piedpiper.com/richard-hendricks.jpg",
"linkedinUrl":"https://www.linkedin.com/in/richard-hendricks/"
}
This endpoint adds a lead in a specific campaign. If the lead doesn't exist, it'll be created, then inserted to the campaign. The creator of the lead is the campaign's sender
You can just add the email without any body.
For campaigns created in v3, if no scanner parameter is passed, the settings from the campaign will be used
For campaigns created in v4, you have to pass the scanner parameter to scan the lead
HTTP Request
POST https://api.lemlist.com/api/campaigns/:campaignId/leads/:email
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign to add the lead. |
email address of the lead |
Query Parameters
curl -X POST "https://api.lemlist.com/api/campaigns/cam_aa7uvyxECcni5KXBM/leads/richard@piedpiper.com?deduplicate=true&scannerLinkedin=true&scannerDropcontact=true" \
-H "Content-Type: application/json" \
--data '{"firstName":"Richard","lastName":"Hendricks","companyName":"Piedpiper","icebreaker":"Icebreaker text", "phone":"(555) 555-1234","picture":"https://piedpiper.com/richard-hendricks.jpg", "linkedinUrl":"https://www.linkedin.com/in/richard-hendricks/"}' \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"campaignId": "cam_aa7uvyxECcni5KXBM",
"campaignName": "Campaign1",
"leadUrl":"https://api.lemlist.com/api/leads/richard%40piedpiper.com",
"_id":"lea_aaNfSAHJoa4gj86Px",
"isPaused":false,
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks",
"companyName":"Piedpiper",
"icebreaker":"Icebreaker text",
"phone":"(555) 555-1234",
"picture":"https://piedpiper.com/richard-hendricks.jpg",
"linkedinUrl":"https://www.linkedin.com/in/richard-hendricks/"
}
Parameter | Description |
---|---|
deduplicate=true | search email address in another campaign, will not insert the lead if email address already inserted |
scannerLinkedin=true | activate the linkedin scanner for this import (needs Sales Engagement Plan) |
scannerDropcontact=true | activate the dropcontact scanner for this import (needs Sales Engagement Plan) |
linkedinScanBy | Id of the user that will scan the lead. User has to have linkedin connected to his lemlist account |
Body Parameters
Body is optional. If set, it must be a JSON object with any information you want to add to the lead.
There's some optional predefined key:
Parameter | Description |
---|---|
firstName | First name of the lead. |
lastName | Last name of the lead. |
companyName | Company name of the lead. |
icebreaker | Icebreaker text of the lead. |
phone | Phone number of the lead. |
picture | Picture url of the lead. |
linkedinUrl | Linkedin url of the lead. |
Update a Lead in a Campaign
curl -X PATCH https://api.lemlist.com/api/campaigns/cam_aa7uvyxECcni5KXBM/leads/richard@piedpiper.com \
-H "Content-Type: application/json" \
--data '{"companyName":"Pied Piper"}' \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"campaignId": "cam_aa7uvyxECcni5KXBM",
"campaignName": "Campaign1",
"leadUrl":"https://api.lemlist.com/api/leads/richard%40piedpiper.com",
"_id":"lea_aaNfSAHJoa4gj86Px",
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks",
"companyName": "Pied Piper"
}
This endpoint updates a lead in a specific campaign.
If the lead doesn't exist a 404 error will be returned.
HTTP Request
PATCH https://api.lemlist.com/api/campaigns/:campaignId/leads/:email
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign to add the lead. |
email address of the lead |
Body Parameters
Body is mandatory. It must be a JSON object with any information you want to update on the lead.
If no body is specified a 400 error will be returned.
Unsubscribe a Lead from a Campaign
curl -X DELETE https://api.lemlist.com/api/campaigns/cam_aa7uvyxECcni5KXBM/leads/richard@piedpiper.com \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id": "lea_aaNfSAHJoa4gj86Px",
"email": "richard@piedpiper.com"
}
This endpoint will unsubscribe a lead from all campaigns if he belongs to the specified campaign.
HTTP Request
DELETE https://api.lemlist.com/api/campaigns/:campaignId/leads/:email
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign to add the lead. |
email address of the lead |
Delete a Lead from a Campaign
curl -X DELETE https://api.lemlist.com/api/campaigns/cam_aa7uvyxECcni5KXBM/leads/richard@piedpiper.com?action=remove \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id": "lea_aaNfSAHJoa4gj86Px",
"email": "richard@piedpiper.com"
}
This endpoint delete a lead from a specific campaign.
All information, including statistics, will be deleted.
HTTP Request
DELETE https://api.lemlist.com/api/campaigns/:campaignId/leads/:email?action=remove
URL Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign to add the lead. |
email address of the lead |
Query Parameters
Parameter | Value | Description |
---|---|---|
action | remove | Force the deletion of the lead |
Leads
Get a Specific Lead by Email
curl https://api.lemlist.com/api/leads/:email \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id":"lea_aaNfSAHJoa4gj86Px",
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks",
"isPaused":true,
"campaignId":"cam_aaBB11C22Def3Gh4i"
}
This endpoint retrieves all the information of a specific lead using its email.
HTTP Request
GET https://api.lemlist.com/api/leads/:email
Query Parameters
Parameter | Description |
---|---|
email address of the lead. | |
campaignId | (Optional) Search for this lead only the specified campaign |
Pause a Specific Lead by Email
curl -X POST https://api.lemlist.com/api/leads/pause/:email \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id":"lea_aaNfSAHJoa4gj86Px",
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks"
}]
This endpoint pauses a specific lead using its email in all campaigns.
HTTP Request
POST https://api.lemlist.com/api/leads/pause/:email
Query Parameters
Parameter | Description |
---|---|
email address of the lead. |
Resume a Specific Lead by Email
curl -X POST https://api.lemlist.com/api/leads/start/:email \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id":"lea_aaNfSAHJoa4gj86Px",
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks"
}]
This endpoint starts a specific lead using its email in all campaigns.
HTTP Request
POST https://api.lemlist.com/api/leads/start/:email
Query Parameters
Parameter | Description |
---|---|
email address of the lead. |
Mark as interested a Specific Lead by Email
curl -X POST https://api.lemlist.com/api/leads/interested/:email \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id":"lea_aaNfSAHJoa4gj86Px",
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks",
"isPaused": false,
"campaignId": "cam_aaBB11C22Def3Gh4i"
}]
This endpoint marks a specific lead as interested using its email in all campaigns.
HTTP Request
POST https://api.lemlist.com/api/leads/interested/:email
Query Parameters
Parameter | Description |
---|---|
email address of the lead. |
Mark as not interested a Specific Lead by Email
curl -X POST https://api.lemlist.com/api/leads/notinterested/:email \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id":"lea_aaBcDDDDee1ff22Gh",
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks",
"isPaused": false,
"campaignId": "cam_aaBB11C22Def3Gh4i"
}]
This endpoint marks a specific lead as not interested using its email in all campaigns.
HTTP Request
POST https://api.lemlist.com/api/leads/notinterested/:email
Query Parameters
Parameter | Description |
---|---|
email address of the lead. |
Mark as interested a Lead in a Specific Campaign
curl -X POST https://api.lemlist.com/api/campaigns/:campaignId/leads/:email/interested \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id":"lea_aaNfSAHJoa4gj86Px",
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks",
"isPaused": false,
"campaignId": "cam_aaBB11C22Def3Gh4i"
}]
This endpoint marks a specific lead as interested using its email in a specific campaigns.
HTTP Request
POST https://api.lemlist.com/api/campaigns/:campaignId/leads/:email/interested
Query Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign. |
email address of the lead. |
Mark as not interested a Lead in a Specific Campaign
curl -X POST https://api.lemlist.com/api/campaigns/:campaignId/leads/:email/notinterested \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id":"lea_aaNfSAHJoa4gj86Px",
"email":"richard@piedpiper.com",
"firstName":"Richard",
"lastName":"Hendricks",
"isPaused": false,
"campaignId": "cam_aaBB11C22Def3Gh4i"
}]
This endpoint marks a specific lead as not interested using its email in a specific campaigns.
HTTP Request
POST https://api.lemlist.com/api/campaigns/:campaignId/leads/:email/notinterested
Query Parameters
Parameter | Description |
---|---|
campaignId | The ID of the campaign. |
email address of the lead. |
Activities
Get Activities
curl https://api.lemlist.com/api/activities \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id": "act_aaXiFy3Y7BNSuYwDr",
"isFirst": true,
"type": "emailsSent",
"teamId": "tea_aaqam5a3BkY8zje24",
"createdAt": "2018-08-24T14:56:39.172Z",
"sendUserId": "usr_aawMB5Gd5JJCFYvjp",
"sendUserEmail": "richard@piedpiper.com",
"sendUserName": "Richard Hendricks",
"leadId": "lea_aafF6i3BjsDRDNAWN",
"leadFirstName": "Jeanne",
"leadLastName": "Doe",
"leadEmail": "jeanne@doe.com",
"campaignId": "cam_aaktcZg9z9xJKQgqK",
"campaignName": "Campaign1",
"listId": "lst_aa5tgpggEfYeJ9vbJ",
"sequenceId": "seq_aaPoZgbALLQhcLmqz",
"sequenceStep": 2,
"emailTemplateId": "etp_aatuEkEztDPm32b23",
"emailTemplateName": "Sales: The Honest One",
"emailId": "eml_aaFHxT2ejiz7apYnn"
},{
"_id": "act_aavmrPCCZGMSsCSNw",
"isFirst": true,
"type": "emailsSent",
"teamId": "tea_aqam5a3BkY8zje24",
"createdAt": "2018-08-24T14:51:35.726Z",
"sendUserId": "usr_aawMB5Gd5JJCFYvjp",
"sendUserEmail": "richard@piedpiper.com",
"sendUserName": "Richard Hendricks",
"leadId": "lea_aafF6i3BjsDRDNAWN",
"leadFirstName": "Jeanne",
"leadLastName": "Doe",
"leadEmail": "jeanne",
"campaignId": "cam_aaktcZg9z9xJKQgqK",
"campaignName": "Campaign1",
"listId": "lst_aa5tgpggEfYeJ9vbJ",
"sequenceId": "seq_aaPoZgbALLQhcLmqz",
"sequenceStep": 1,
"emailTemplateId": "etp_aak9yNgefLCCB7ghA",
"emailTemplateName": "I Just Call",
"emailId": "eml_aabhRvzfe9sFErQ2b",
"sequenceTested": "A",
"stepTested": "A"
}]
This endpoint retrieves the last 100 activities.
HTTP Request
GET https://api.lemlist.com/api/activities
Query Parameters
Parameter | Description |
---|---|
type | (Optional) The type of activity you want to retrieve. Can be emailsSent , emailsOpened , emailsClicked , emailsReplied , emailsDone , emailsBounced , emailsFailed , emailsUnsubscribed , emailsInterested , emailsNotInterested , snoozed , annotated , aircallDone , aircallCreated , aircallEnded , aircallInterested , aircallNotInterested , apiDone , apiInterested , apiNotInterested , apiFailed , linkedinVisitDone , linkedinVisitFailed , linkedinInviteDone , linkedinSent , linkedinOpened , linkedinInviteAccepted , linkedinInviteFailed , linkedinSendFailed , linkedinReplied , linkedinInterested , linkedinNotInterested , linkedinDone , manualDone , manualInterested , manualNotInterested , paused , resumed , skipped , contacted , hooked , attracted , warmed , interested , notInterested . |
campaignId | (Optional) Retrieve activities of this campaignId . |
isFirst | (Optional) Only retrieve the first time this activity happened. |
offset | (Optional) Offset from the start. For pagination. |
limit | (Optional) Number of campaigns to retrieve. 100 per default ( and 100 max ). |
Unsubscribes
List All Unsubscribes
curl https://api.lemlist.com/api/unsubscribes \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id": "lead_123456",
"email": "a@a.com"
}, {
"_id": "lead_123457",
"email": "b@b.com"
}]
This endpoint retrieves the list of all people who are unsubscribed.
HTTP Request
GET https://api.lemlist.com/api/unsubscribes
Query Parameters
Parameter | Description |
---|---|
offset | (Optional) Offset from the start. For pagination. |
limit | (Optional) Number of email to retrieve. 100 per default. |
Export the List of Unsubscribes
curl https://api.lemlist.com/api/unsubs/export \
--user ":YourApiKey"
The above command returns the CSV file with all unsubscribed email addresses
This endpoint downloads a CSV file that contains all the unsubscribed email addresses.
Result is not sorted.
HTTP Request
GET https://api.lemlist.com/api/unsubs/export
URL Parameters
No parameters.
Add an Email Address or a Domain in the Unsubscribes
curl -X POST https://api.lemlist.com/api/unsubscribes/a@a.com \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id": "lea_aaJgm566c9tyzTBeu",
"email": "a@a.com"
}
If lead is already unsubscribed, returns JSON structured like this:
{
"_id": "lea_aaJgm566c9tyzTBeu",
"email": "a@a.com",
"alreadyUnsubscribed": true
}
To unsubscribe the entire domain 'a.com'
curl -X POST https://api.lemlist.com/api/unsubscribes/@a.com \
--user ":YourApiKey"
This endpoint adds a lead in the unsubscribed list. Domain to unsubscribe must start with @, e.g. @a.com
HTTP Request
POST https://api.lemlist.com/api/unsubscribes/:email
URL Parameters
Parameter | Description |
---|---|
email or domain | email address to unsubscribe. If this is a domain, it must start with @ |
Delete an Email Address from the Unsubscribes
curl -X DELETE https://api.lemlist.com/api/unsubscribes/a@a.com \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id": "lea_aaJgm566c9tyzTBeu",
"email": "a@a.com"
}
This endpoint deletes a lead in the unsubscribed list.
HTTP Request
DELETE https://api.lemlist.com/api/unsubscribes/:email
URL Parameters
Parameter | Description |
---|---|
email address of the lead |
Hooks
Hooks are a way to for us to contact your server when an event occurs in lemlist. You can list, add or delete hooks.
List All Hooks
curl https://api.lemlist.com/api/hooks \
--user ":YourApiKey"
The above command returns JSON structured like this:
[{
"_id": "hoo_aadabFv7dRoP2L8GJ",
"targetUrl": "https://youserver.com/lemlist-hook",
"createdAt": "2018-11-27T12:19:26.608Z"
}]
This endpoint retrieves the list of all hooks.
HTTP Request
GET https://api.lemlist.com/api/hooks
Query Parameters
No parameters.
Add a Hook
curl -X POST https://api.lemlist.com/api/hooks \
--data '{"targetUrl":"https://youserver.com/lemlist-hook"}' \
--header "Content-Type: application/json" \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id": "hoo_aadabFv7dRoP2L8GJ",
"targetUrl": "https://youserver.com/lemlist-hook",
"createdAt": "2018-11-27T12:19:26.608Z"
}
This endpoint adds a hook in our system. Each time an event happen, we'll call targetUrl
with the event data as an object. To know more about the data passed, see activities
For mails sent through the composer, the emailsSent
event is not fired
HTTP Request
POST https://api.lemlist.com/api/hooks
Body Parameters
Body is optional. If set, It must be a JSON object with one of those parameters.
Parameter | Description |
---|---|
type | (Optional) We'll call this hook only if the event is of the type type . type can be contacted , hooked , attracted , warmed , interested , skipped , notInterested , emailsSent , emailsOpened , emailsClicked , emailsReplied , emailsBounced , emailsSendFailed , emailsFailed , emailsUnsubscribed , emailsInterested , emailsNotInterested , opportunitiesDone , aircallCreated , aircallEnded , aircallDone , aircallInterested , aircallNotInterested , apiDone , apiInterested , apiNotInterested , apiFailed , linkedinVisitDone , linkedinVisitFailed , linkedinInviteDone , linkedinInviteFailed , linkedinInviteAccepted , linkedinReplied , linkedinSent , linkedinInterested , linkedinNotInterested , linkedinSendFailed , manualInterested , manualNotInterested , paused , resumed . |
campaignId | (Optional) We'll call this hook only for this campaignId . |
isFirst | (Optional) We'll call this hook only the first time this activity happened. |
Delete a Hook
curl -X DELETE https://api.lemlist.com/api/hooks/hoo_123456 \
--user ":YourApiKey"
The above command returns JSON structured like this:
{
"_id": "hoo_aadabFv7dRoP2L8GJ",
"targetUrl": "https://youserver.com/lemlist-hook",
"createdAt": "2018-11-27T12:19:26.608Z"
}
This endpoint delete a hook.
HTTP Request
DELETE https://api.lemlist.com/api/hooks/:_id
URL Parameters
Parameter | Description |
---|---|
_id | The ID of the hook that we have to remove. |
Errors
The lemlist API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The id requested is hidden for administrators only. |
404 | Not Found -- The specified id could not be found. |
405 | Method Not Allowed -- You tried to access a id with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
410 | Gone -- The id requested has been removed from our servers. |
418 | I'm a teapot. |
429 | Too Many Requests -- You're requesting too many ids! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |