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)"
}

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"

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.

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

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"
}, {
  "_id": "cam_aaXwBiebA8pWPKqpK",
  "name": "Campaign2"
}]

This endpoint retrieves the list of all campaigns.

HTTP Request

GET https://api.lemlist.com/api/campaigns

Query Parameters

No parameters.

Export Statistics of a Campaign

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.

HTTP Request

GET https://api.lemlist.com/api/campaigns/:campaignId/export

URL Parameters

Export Leads of a Campaign

curl https://api.lemlist.com/api/campaigns/cam_123456/export/list \
  --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

URL Parameters

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

This endpoint adds a lead in a specific campaign. If the lead doesn't exist, it'll be created, then inserted to the campaign.

You can just add the email without any body.

HTTP Request

POST https://api.lemlist.com/api/campaigns/:campaignId/leads/:email

URL Parameters

Query Parameters

curl POST "https://api.lemlist.com/api/campaigns/cam_aa7uvyxECcni5KXBM/leads/richard@piedpiper.com?deduplicate=true" \
  -H "Content-Type: application/json" \
  --data '{"firstName":"Richard","lastName":"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",
  "email":"richard@piedpiper.com",
  "firstName":"Richard",
  "lastName":"Hendricks"
}

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:

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 unsuscribe a lead from a specific campaign.

HTTP Request

DELETE https://api.lemlist.com/api/campaigns/:campaignId/leads/:email

URL Parameters

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

Query Parameters

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

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

Activities

Get Team Information

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"
}]

This endpoint retrieves the last 100 activities.

HTTP Request

GET https://api.lemlist.com/api/activities

Query Parameters

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

Export the List of Unsubscribes

curl https://api.lemlist.com/api/unsubscribes/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.

HTTP Request

GET https://api.lemlist.com/api/unsubscribes/export

URL Parameters

No parameters.

Add an Email Address 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"
}

This endpoint adds a lead in the unsubscribed list.

HTTP Request

POST https://api.lemlist.com/api/unsubscribes/:email

URL Parameters

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

Hooks

Hooks are a way to for us to contact your server when an even happen 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.

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.

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

Errors

The lemlist API uses the following error codes: