> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lemlist.com/llms.txt
> Use this file to discover all available pages before exploring further.
> Creates a new deliverability alert that monitors a warm-up or outreach metric and notifies you through the configured channels when the threshold is breached.
# Create Deliverability Alert
export const SnippetObjectReference = ({objectName, objectPath = null}) => {
const lowerCaseObjectName = objectName.toLowerCase();
if (lowerCaseObjectName === 'lead' || lowerCaseObjectName === 'leads') {
return
This endpoint uses the {objectName} object. Make sure to also check the {lowerCaseObjectName === 'lead' ? 'Contact' : 'Lead'} object to understand the distinction between the two.
;
}
return
This endpoint uses the {objectName} object.
;
};
## Choosing the right dimensions
Each alert is defined by the combination of `widget`, `metric`, `severity`, and `scope`. These four fields, along with `threshold`, `comparisonOperator`, `periodDays`, `periodMode`, and `scopeEntities`, must be unique per team — creating a duplicate returns `409`.
### `widget` × `metric`
| widget | Allowed metrics |
| ---------- | -------------------------------- |
| `warmup` | `inboxRate`, `spamRate`, `score` |
| `outreach` | `deliveryRate`, `bounceRate` |
### `scope`
| scope | Meaning | `scopeEntities` | | |
| --------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------- |
| `global` | All mailboxes aggregated. Only valid for `widget=warmup`. | Ignored. | | |
| `mailbox` | Each mailbox evaluated individually. | Optional filter. Each entry must use the format `userId\|email\|mailboxId` (e.g. \`usr\_A1B2C3... | [john@example.com](mailto:john@example.com) | usm\_X9Y8Z7...\`). Omit to monitor every mailbox. |
| `domain` | Mailboxes grouped by their sending domain. | Optional filter. Each entry is a bare domain (e.g. `acme.com`). Omit to monitor every domain. | | |
### `periodMode`
* `rolling` — averages the metric over the last `periodDays` days. Best for noisy rate metrics like `bounceRate` or `deliveryRate`.
* `consecutive` — requires the condition to hold on **every** one of the last `periodDays` days. Useful with `score`-style metrics that are reported once per day.
## Notification channels
Set at least one channel to `enabled: true` in `channelConfig`. If you omit `channelConfig` entirely, the alert defaults to `inapp` only.
* `inapp` — surfaces the alert in the lemlist deliverability dashboard.
* `email` — sends to the listed `addresses`. At least one address is required when this channel is enabled.
* `webhook` — posts a `deliverabilityAlertTriggered` event to every webhook subscribed to that event. Configure the destination URL with [Add Webhook](/api-reference/endpoints/webhooks/add-webhook).
* `slack` — sends a Slack message. Requires a Slack integration to be connected on the team.
## OpenAPI
````yaml post /deliverability/alerts
openapi: 3.0.0
info:
title: lemlist API
version: 1.0.0
description: >-
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 provides any information you may need about it:
| Header | Description |
| --- | --- |
| Retry-After | The number of seconds 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 |
_Example of values for the rate limit headers_
``` json
{
"Retry-After": 2,
"X-RateLimit-Limit": 20,
"X-RateLimit-Remaining": 7,
"X-RateLimit-Reset" : "Tue Feb 16 2021 09:02:42 GMT+0100 (Central European Standard Time)"
}
```
# Definitions
## Team
A team is the entity of lemlist that can handle users and billing.
## Credits
Credits are the coins a team uses to enrich emails, LinkedIn URLs, etc. via
the enrich route. Each enrichment feature needs a certain amount of credits
to run.
## User
You use a user account to connect to lemlist and send messages via the
connected emails or LinkedIn account.
## Campaign
A campaign is the entity to automate outreach. A campaign has multiple
sequences composed of steps.
## Lead
A lead is a person that you try to contact via a campaign.
## Activity
An activity is the history of all the steps.
## Unsubscribe
An unsubscribe occurs when a person decides they don't want to receive
emails from you anymore.
# Authentication
All API routes use the dedicated subdomain `api.lemlist.com`.
lemlist uses API keys to allow access to the API. You can get your lemlist
API key at our [integration
page](https://app.lemlist.com/settings/integrations).
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**.
⚠️ **Don't forget to add the semicolon (**`:`**) before your API key in curl
command.**
> To authorize, use this code:
``` shell
curl https://api.lemlist.com/api/team \
--user ":YourApiKey"
```
**Make sure to replace** **`YourApiKey`** **with your API key.**
# Give feedback
If you want to report a bug, ask for data, or share with us a use case,
please fill this [form](https://lemlist.typeform.com/to/mfVlkyGf). It will
help us centralize your needs!
servers:
- url: https://api.lemlist.com/api
security:
- basicAuth: []
paths:
/deliverability/alerts:
post:
tags:
- Deliverability alerts
summary: Create Deliverability Alert
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- widget
- metric
- severity
- scope
- threshold
- comparisonOperator
- periodDays
- periodMode
properties:
widget:
type: string
enum:
- warmup
- outreach
metric:
type: string
enum:
- inboxRate
- spamRate
- score
- deliveryRate
- bounceRate
severity:
type: string
enum:
- warning
- critical
scope:
type: string
enum:
- global
- mailbox
- domain
scopeEntities:
type: array
description: >-
Required when `scope` is `mailbox` or `domain` and you want
to target specific entities. Mailbox entries use the format
`userId|email|mailboxId`. Domain entries are bare domains
(e.g. `acme.com`).
items:
type: string
threshold:
type: number
minimum: 0
maximum: 100
comparisonOperator:
type: string
enum:
- equal
- below
- above
periodDays:
type: integer
minimum: 1
maximum: 30
periodMode:
type: string
enum:
- rolling
- consecutive
channelConfig: 0d4d6a6e-1be5-4c1b-b82a-7e73d0ceae0a
recheckDelayHours:
type: integer
description: >-
Cool-down between re-evaluations after the alert triggers,
in hours. Defaults to 12.
examples:
outreachBounceRate:
summary: Critical alert on outreach bounce rate
value:
widget: outreach
metric: bounceRate
severity: critical
scope: mailbox
scopeEntities:
- >-
usr_ExampleAcmeUserId|john@example.com|usm_ExampleMailboxId
threshold: 5
comparisonOperator: above
periodDays: 1
periodMode: rolling
channelConfig:
inapp:
enabled: true
email:
enabled: true
addresses:
- alerts@example.com
warmupInboxRateGlobal:
summary: Warning when global warm-up inbox rate drops
value:
widget: warmup
metric: inboxRate
severity: warning
scope: global
threshold: 85
comparisonOperator: below
periodDays: 3
periodMode: rolling
responses:
'201':
description: Alert created
content:
application/json:
schema:
$ref: '#/components/schemas/DeliverabilityAlert'
example:
_id: dac_A1B2C3D4E5F6G7H8I
teamId: tea_ExampleAcmeTeamId
createdBy: usr_ExampleAcmeUserId
createdAt: '2026-04-12T09:30:00.000Z'
updatedAt: '2026-04-12T09:30:00.000Z'
widget: outreach
metric: bounceRate
severity: critical
scope: mailbox
scopeEntities:
- usr_ExampleAcmeUserId|john@example.com|usm_ExampleMailboxId
threshold: 5
comparisonOperator: above
periodDays: 1
periodMode: rolling
channelConfig:
inapp:
enabled: true
email:
enabled: true
addresses:
- alerts@example.com
webhook:
enabled: false
slack:
enabled: false
enabled: true
lastCheckedAt: '2026-05-07T07:00:00.000Z'
lastTriggeredAt: '2026-05-06T18:42:11.000Z'
recheckDelayHours: 12
'400':
description: >-
Validation error. The `error` field identifies which input was
rejected — e.g. `DELIVERABILITY_ALERT_INVALID_WIDGET`,
`DELIVERABILITY_ALERT_INVALID_METRIC`,
`DELIVERABILITY_ALERT_INVALID_SCOPE`,
`DELIVERABILITY_ALERT_INVALID_THRESHOLD`,
`DELIVERABILITY_ALERT_INVALID_PERIOD_DAYS`,
`DELIVERABILITY_ALERT_NO_CHANNEL_ENABLED`,
`DELIVERABILITY_ALERT_EMAIL_REQUIRED`,
`DELIVERABILITY_ALERT_INVALID_EMAIL`,
`DELIVERABILITY_ALERT_INVALID_SCOPE_ENTITY_FORMAT`.
'401':
description: Unauthorized
'403':
description: Beta feature not enabled for this team
'409':
description: >-
An alert with the same widget, metric, severity, scope,
scopeEntities, threshold, comparisonOperator, periodDays and
periodMode already exists
components:
schemas:
DeliverabilityAlert:
type: object
description: >-
A deliverability alert configuration. The alert is evaluated
periodically against your warm-up or outreach metrics and triggers
notifications through the configured channels (in-app, email, webhook,
Slack) when the threshold is breached.
properties:
_id:
type: string
description: Unique alert configuration identifier (prefixed with `dac_`).
teamId:
type: string
description: ID of the team that owns the alert.
createdBy:
type: string
description: ID of the user who created the alert.
createdAt:
type: string
format: date-time
description: Creation timestamp.
updatedAt:
type: string
format: date-time
description: Last update timestamp.
widget:
type: string
description: >-
Data source the alert evaluates. `warmup` checks lemwarm metrics;
`outreach` checks campaign-sending metrics.
enum:
- warmup
- outreach
metric:
type: string
description: >-
Metric being monitored. Valid combinations depend on `widget`:
`warmup` supports `inboxRate`, `spamRate`, `score`; `outreach`
supports `deliveryRate`, `bounceRate`.
enum:
- inboxRate
- spamRate
- score
- deliveryRate
- bounceRate
severity:
type: string
description: Alert severity.
enum:
- warning
- critical
scope:
type: string
description: >-
Aggregation level the metric is computed at. `global` covers all of
the workspace's mailboxes (warm-up only); `mailbox` evaluates each
mailbox individually; `domain` groups mailboxes by their sending
domain.
enum:
- global
- mailbox
- domain
scopeEntities:
type: array
description: >-
Restricts the alert to a subset of entities matching `scope`. When
empty, all entities of that scope are checked. For `scope=mailbox`,
each entry is a composite string `userId|email|mailboxId`. For
`scope=domain`, each entry is a domain (e.g. `acme.com`). Ignored
when `scope=global`.
items:
type: string
threshold:
type: number
description: >-
Threshold value the metric is compared against (0–100, expressed as
a percentage for rate metrics).
minimum: 0
maximum: 100
comparisonOperator:
type: string
description: >-
How `threshold` is compared to the current value. `below` triggers
when the value drops under the threshold; `above` triggers when it
exceeds it; `equal` triggers on exact match.
enum:
- equal
- below
- above
periodDays:
type: integer
description: Length of the evaluation window, in days (1–30).
minimum: 1
maximum: 30
periodMode:
type: string
description: >-
How the metric is computed over `periodDays`. `rolling` averages the
metric across the window; `consecutive` requires the condition to
hold on every one of the most recent `periodDays`.
enum:
- rolling
- consecutive
channelConfig:
type: object
description: >-
Notification channels triggered when the alert fires. At least one
channel must be enabled. If omitted on creation, defaults to `inapp`
only.
properties:
email:
type: object
properties:
enabled:
type: boolean
addresses:
type: array
description: >-
Required when `email.enabled` is `true`. At least one valid
address.
items:
type: string
format: email
inapp:
type: object
properties:
enabled:
type: boolean
description: Show the alert in the lemlist app.
webhook:
type: object
properties:
enabled:
type: boolean
description: >-
Send a webhook callback. Requires a webhook subscribed to
the `deliverabilityAlertTriggered` event (see [Add
Webhook](/api-reference/endpoints/webhooks/add-webhook)).
slack:
type: object
properties:
enabled:
type: boolean
description: >-
Send a Slack message. Requires a Slack integration to be
connected on the team.
enabled:
type: boolean
description: >-
Whether the alert is currently active. Disabled alerts are not
evaluated.
lastCheckedAt:
type: string
format: date-time
description: Last time the alert was evaluated.
lastTriggeredAt:
type: string
format: date-time
description: Last time the alert fired.
recheckDelayHours:
type: integer
description: >-
Cool-down between re-evaluations after the alert has triggered, in
hours. Defaults to 12.
securitySchemes:
basicAuth:
type: http
scheme: basic
````