lemlist Unsubscribes API
Suppression management - unsubscribe and re-subscribe contacts and variables, list and export the suppression set, and the legacy email/domain surface.
OpenAPI Specification
openapi: 3.0.0
info:
title: lemlist Unsubscribes API
version: 1.0.0
description: The Unsubscribes 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: Unsubscribes
paths:
/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
/unsubs/export:
get:
deprecated: true
summary: Export Unsubscribes
tags:
- Unsubscribes
parameters: []
responses:
'200':
description: Success
content:
text/csv:
example: 'value,source,createdAt
william.davis@fake.org,lead,2019-12-19T21:56:34.672Z
emma.johnson@sample.com,abuse,2020-09-30T08:34:17.298Z
michael.brown@domain.net,api,2021-03-12T14:12:56.534Z
jane.smith@example.org,bounce,2022-11-23T18:23:45.890Z
john.doe@example.com,user,2023-06-15T10:45:21.367Z
alice.brown@domainexample.com,lead,2023-07-21T09:14:25.521Z
bob.smith@example.net,user,2023-08-01T17:34:43.679Z
charlie.doe@mockmail.com,api,2023-09-12T11:05:37.874Z
david.jones@sampledomain.org,abuse,2023-10-05T15:23:54.129Z
eve.wilson@fakemail.com,bounce,2024-01-07T08:19:45.213Z'
'400':
description: Bad team
content:
text/plain:
example: Bad team
'401':
description: Unauthorized
/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
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
/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
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
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
/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
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
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
/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
/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
/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 @'
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
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
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
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