lemlist Unsubscribes API
Suppression management - unsubscribe and re-subscribe contacts and variables, list and export the suppression set, and the legacy email/domain surface.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/lemlist-unsubscribes-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Lemlist Unsubscribes API
version: 1.0.0
description: 'Operations tagged Unsubscribes across 3 of this provider''s published API definitions: lemlist-openapi-v1-legacy.json, lemlist-openapi-v2.json, lemlist-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.lemlist.com/api
tags:
- name: Unsubscribes
paths:
/unsubscribes/:
parameters: []
get:
summary: Retrieve Unsubscribes
tags:
- Unsubscribes
parameters:
- name: offset
in: query
required: false
description: (Optional) Offset from the start. For pagination.
example: '0'
schema:
type: integer
- name: limit
in: query
required: false
description: (Optional) Number of email to retrieve. 100 per default.
example: '5'
schema:
type: integer
- name: Content
in: header
required: false
example: application/json
schema:
type: string
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
description: Retrieve Unsubscribes
content:
application/json:
schema:
type: array
items:
type: object
properties:
_id:
type: string
createdAt:
type: string
format: date-time
value:
type: string
format: email
source:
type: string
example:
- _id: uns_Y9Lf5R2mpNWs8x0cz
createdAt: '2023-06-12T10:45:21.367Z'
value: john.doe@example.com
source: user
- _id: uns_B8Tq7U4dnGXp9a1wy
createdAt: '2023-06-09T18:23:45.890Z'
value: jane.smith@example.org
source: bounce
- _id: uns_D5Jr6W3yfPQt0b2vx
createdAt: '2023-06-08T14:12:56.534Z'
value: michael.brown@domain.net
source: api
- _id: uns_F4Gs8V1hnLYc3w9kt
createdAt: '2023-06-05T08:34:17.298Z'
value: emma.johnson@sample.com
source: abuse
- _id: uns_H3Jf9X2lpKZw4y7bv
createdAt: '2023-06-01T21:56:34.672Z'
value: william.davis@fake.org
source: lead
servers:
- url: https://api.lemlist.com/api
/unsubs/export:
parameters: []
get:
summary: Export Unsubscribes
tags:
- Unsubscribes
parameters:
- name: Content
in: header
required: false
example: application/json
schema:
type: string
responses:
'200':
headers: {}
description: Export Unsubscribes
servers:
- url: https://api.lemlist.com/api
/unsubscribes/john.doe@domain.com:
parameters: []
get:
summary: Get Unsubscribe Email
tags:
- Unsubscribes
parameters:
- name: Content
in: header
required: false
example: application/json
schema:
type: string
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
createdAt:
type: string
format: date-time
value:
type: string
format: email
source:
type: string
example:
_id: uns_Y9Lf5R2mpNWs8x0cz
createdAt: '2023-06-12T10:45:21.367Z'
value: john.doe@example.com
source: user
'404':
headers: {}
description: Not found
post:
summary: Add Unsubscribe Email/Domain
tags:
- Unsubscribes
parameters:
- name: Content
in: header
required: false
example: application/json
schema:
type: string
responses:
'200':
description: Success
delete:
summary: Delete Unsubscribe Email
tags:
- Unsubscribes
parameters:
- name: Content
in: header
required: false
example: application/json
schema:
type: string
responses:
'200':
description: Success
servers:
- url: https://api.lemlist.com/api
/unsubscribes:
get:
deprecated: true
summary: Get Many Unsubscribes
tags:
- Unsubscribes
parameters:
- name: offset
in: query
required: false
description: Offset for pagination
example: '0'
schema:
type: integer
- name: limit
in: query
required: false
description: 'Number of unsubscribes to retrieve. Default: 100'
example: '5'
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Unsubscribe'
example:
- _id: uns_ZfdZWc7dvCqXdgQmb
createdAt: '2023-06-12T10:45:21.367Z'
value: john.doe@example.com
source: user
'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
security:
- basicAuth: []
servers:
- url: https://api.lemlist.com/api
/v2/unsubscribes/variables:
get:
summary: List Unsubscribed Variables
description: Retrieves a paginated list of all unsubscribed variables (emails, domains, LinkedIn URLs, phone numbers).
tags:
- Unsubscribes
parameters:
- name: offset
in: query
required: false
description: Number of entries to skip for pagination
example: '0'
schema:
type: integer
default: 0
- name: limit
in: query
required: false
description: Number of entries to return (max 100)
example: '50'
schema:
type: integer
default: 100
maximum: 100
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UnsubscribedVariable'
example:
- _id: uns_ZfdZWc7dvCqXdgQmb
value: john.doe@example.com
source: user
createdAt: '2023-06-12T10:45:21.367Z'
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
security:
- basicAuth: []
post:
summary: Bulk Unsubscribe Variables
description: Unsubscribes up to 10,000 variables in a single request.
tags:
- Unsubscribes
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- values
properties:
values:
type: array
items:
type: string
description: List of variables to unsubscribe (emails, domains, LinkedIn URLs, or phone numbers). Maximum 10,000 values.
maxItems: 10000
example:
values:
- john.doe@example.com
- '@example.org'
- '+1234567890'
responses:
'200':
description: Success
content:
application/json:
example: Variables unsubscribed
'400':
description: Validation error
content:
text/plain:
example: Maximum 10000 values allowed
'401':
description: Unauthorized
security:
- basicAuth: []
servers:
- url: https://api.lemlist.com/api
/v2/unsubscribes/variables/{value}:
get:
summary: Get Unsubscribed Variable
description: Retrieves a specific unsubscribed variable by its value.
tags:
- Unsubscribes
parameters:
- name: value
in: path
required: true
description: The variable value (email, domain, LinkedIn URL, or phone number)
example: john.doe@example.com
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
description: Unique identifier
value:
type: string
description: The unsubscribed variable
variable:
type: string
description: Alias of value
source:
type: string
description: Origin of the unsubscription
enum:
- api
- bounced
- lead
- user
- abuse
example:
_id: uns_ZfdZWc7dvCqXdgQmb
value: john.doe@example.com
variable: john.doe@example.com
source: user
'400':
description: Bad request
content:
text/plain:
example: No value
'401':
description: Unauthorized
'404':
description: Variable not found
content:
text/plain:
example: Variable not found
security:
- basicAuth: []
post:
summary: Unsubscribe Variable
description: Unsubscribes a single variable. This operation is idempotent — if the variable is already unsubscribed, the existing record is returned.
tags:
- Unsubscribes
parameters:
- name: value
in: path
required: true
description: The variable value to unsubscribe (email, domain, LinkedIn URL, or phone number)
example: john.doe@example.com
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
description: Unique identifier
value:
type: string
description: The unsubscribed variable
variable:
type: string
description: Alias of value
source:
type: string
description: Origin of the unsubscription
enum:
- api
- bounced
- lead
- user
- abuse
example:
_id: uns_ZfdZWc7dvCqXdgQmb
value: john.doe@example.com
variable: john.doe@example.com
source: api
'400':
description: Bad request
content:
text/plain:
example: No value
'401':
description: Unauthorized
'500':
description: Server error
content:
text/plain:
example: Failed to unsubscribe variable
security:
- basicAuth: []
delete:
summary: Re-subscribe Variable
description: Removes a variable from the unsubscribe list. Variables with a protected source (LEAD or ABUSE) cannot be re-subscribed.
tags:
- Unsubscribes
parameters:
- name: value
in: path
required: true
description: The variable value to re-subscribe
example: john.doe@example.com
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
example: Variable subscribed
'400':
description: Variable not found in unsubscribe list
content:
text/plain:
example: Variable not found in unsubscribe list
'401':
description: Unauthorized
'409':
description: Variable is protected (source is LEAD or ABUSE) and cannot be re-subscribed
content:
text/plain:
example: Variable is protected and cannot be re-subscribed
security:
- basicAuth: []
servers:
- url: https://api.lemlist.com/api
/v2/unsubscribes/contacts/{contactId}:
get:
summary: Get Contact Subscription Status
description: Checks whether a contact is unsubscribed (do-not-contact).
tags:
- Unsubscribes
parameters:
- name: contactId
in: path
required: true
description: The contact identifier
example: con_aB1cD2eF3gH4iJ5kL
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ContactSubscriptionStatus'
example:
_id: con_aB1cD2eF3gH4iJ5kL
doNotContact: false
'400':
description: Bad request
content:
text/plain:
example: Bad contact identifier
'401':
description: Unauthorized
'500':
description: Server error
content:
text/plain:
example: Failed to get contact subscription
security:
- basicAuth: []
post:
summary: Unsubscribe Contact
description: Marks a contact as unsubscribed (do-not-contact).
tags:
- Unsubscribes
parameters:
- name: contactId
in: path
required: true
description: The contact identifier
example: con_aB1cD2eF3gH4iJ5kL
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
example: Contact subscription updated
'400':
description: Bad request
content:
text/plain:
example: Bad contact identifier
'401':
description: Unauthorized
'500':
description: Server error
content:
text/plain:
example: Failed to update contact subscription
security:
- basicAuth: []
delete:
summary: Re-subscribe Contact
description: Removes the unsubscribed (do-not-contact) flag from a contact.
tags:
- Unsubscribes
parameters:
- name: contactId
in: path
required: true
description: The contact identifier
example: con_aB1cD2eF3gH4iJ5kL
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
example: Contact subscription updated
'400':
description: Bad request
content:
text/plain:
example: Bad contact identifier
'401':
description: Unauthorized
'500':
description: Server error
content:
text/plain:
example: Failed to update contact subscription
security:
- basicAuth: []
servers:
- url: https://api.lemlist.com/api
/v2/unsubscribes/exports/variables:
get:
summary: Export Unsubscribed Variables
description: Exports all unsubscribed variables to a CSV file.
tags:
- Unsubscribes
responses:
'200':
description: Success
content:
text/csv:
example: '_id,value,source,createdAt
uns_ZfdZWc7dvCqXdgQmb,john.doe@example.com,user,2023-06-12T10:45:21.367Z
uns_fH5gNhZnIpnwRlxZw,@example.org,api,2023-07-21T09:14:25.521Z'
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
security:
- basicAuth: []
servers:
- url: https://api.lemlist.com/api
/v2/unsubscribes/exports/contacts:
get:
summary: Export Unsubscribed Contacts
description: Exports all contacts with their subscription status to a CSV file.
tags:
- Unsubscribes
responses:
'200':
description: Success
content:
text/csv:
example: '_id,doNotContact
con_aB1cD2eF3gH4iJ5kL,true
con_mN6oP7qR8sT9uV0wX,false'
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
security:
- basicAuth: []
servers:
- url: https://api.lemlist.com/api
/unsubscribes/{email}:
get:
deprecated: true
summary: Get Unsubscribe by Email
tags:
- Unsubscribes
parameters:
- name: email
in: path
required: true
description: Email address to check unsubscribe status
example: john.doe@domain.com
schema:
type: string
format: email
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
description: Unique identifier for the unsubscribe entry
createdAt:
type: string
format: date-time
description: Timestamp when the unsubscribe entry was created
value:
type: string
description: The unsubscribed email address
source:
type: string
description: Source of the unsubscribe (e.g., user, lead, abuse, bounce, api)
example:
_id: uns_ZfdZWc7dvCqXdgQmb
createdAt: '2023-06-12T10:45:21.367Z'
value: john.doe@example.com
source: user
'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: 'Possible errors: No user found for this API key / Unsubscriber not found'
content:
text/plain:
example: No user found for this API key
'500':
description: 'Possible errors: Invalid value / Invalid email address or domain / Invalid email address or domain. Domains must start with @'
security:
- basicAuth: []
post:
deprecated: true
summary: Add Unsubscribe Email or Domain
tags:
- Unsubscribes
parameters:
- name: email
in: path
required: true
description: Email address to add to the unsubscribes
example: john.doe@domain.com
schema:
type: string
format: email
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
description: Unique identifier for the unsubscribe entry
value:
type: string
format: email
description: The unsubscribed email address or domain
email:
type: string
format: email
description: The unsubscribed email address
required:
- _id
- value
example:
_id: uns_fH5gNhZnIpnwRlxZw
value: user@domain.com
email: user@domain.com
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
'404':
description: Unsubscribe not found
content:
text/plain:
example: Unsubscribe not found
security:
- basicAuth: []
delete:
deprecated: true
summary: Delete Unsubscribe Email
tags:
- Unsubscribes
parameters:
- name: email
in: path
required: true
description: Email address to remove from the unsubscribes
example: john.doe@domain.com
schema:
type: string
format: email
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
_id:
type: string
description: Unique identifier for the unsubscribe entry
value:
type: string
format: email
description: The unsubscribed email address
required:
- _id
- value
example:
_id: uns_QCXCLzEfEuEOlCVIu
value: john.doe@example.com
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
'404':
description: Unsubscribe not found
content:
text/plain:
example: Unsubscribe not found
security:
- basicAuth: []
servers:
- url: https://api.lemlist.com/api
components:
schemas:
ContactSubscriptionStatus:
type: object
description: Subscription status of a contact.
properties:
_id:
type: string
description: Contact identifier
doNotContact:
type: boolean
description: Whether the contact is unsubscribed
Unsubscribe:
type: object
description: A record of someone opting out of receiving emails.
properties:
_id:
type: string
description: Unique unsubscribe identifier
email:
type: string
format: email
description: Unsubscribed email address
campaignId:
type: string
description: Campaign ID from which the person unsubscribed
campaignName:
type: string
description: Campaign name from which the person unsubscribed
unsubscribedAt:
type: string
format: date-time
description: Unsubscribe timestamp
scope:
type: string
description: Unsubscribe scope
enum:
- campaign
- team
- global
UnsubscribedVariable:
type: object
description: A variable (email, domain, LinkedIn URL, or phone number) that has been unsubscribed.
properties:
_id:
type: string
description: Unique identifier for the unsubscribe entry
value:
type: string
description: The unsubscribed variable (email, domain, LinkedIn URL, or phone number)
source:
type: string
description: Origin of the unsubscription
enum:
- api
- bounced
- lead
- user
- abuse
createdAt:
type: string
format: date-time
description: When the variable was unsubscribed
securitySchemes:
basicAuth:
type: http
scheme: basic
x-refined-from:
- lemlist-openapi-v1-legacy.json
- lemlist-openapi-v2.json
- lemlist-openapi.yml