curl --request POST \
--url https://api.lemlist.com/api/deliverability/alerts \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"widget": "outreach",
"metric": "bounceRate",
"severity": "critical",
"scope": "mailbox",
"threshold": 5,
"comparisonOperator": "above",
"periodDays": 1,
"periodMode": "rolling"
}
'
{
"_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
}Deliverability alerts
Create Deliverability Alert
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.
POST
/
deliverability
/
alerts
curl --request POST \
--url https://api.lemlist.com/api/deliverability/alerts \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"widget": "outreach",
"metric": "bounceRate",
"severity": "critical",
"scope": "mailbox",
"threshold": 5,
"comparisonOperator": "above",
"periodDays": 1,
"periodMode": "rolling"
}
'
{
"_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
}Choosing the right dimensions
Each alert is defined by the combination ofwidget, 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… |
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 lastperiodDaysdays. Best for noisy rate metrics likebounceRateordeliveryRate.consecutive— requires the condition to hold on every one of the lastperiodDaysdays. Useful withscore-style metrics that are reported once per day.
Notification channels
Set at least one channel toenabled: 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 listedaddresses. At least one address is required when this channel is enabled.webhook— posts adeliverabilityAlertTriggeredevent to every webhook subscribed to that event. Configure the destination URL with Add Webhook.slack— sends a Slack message. Requires a Slack integration to be connected on the team.
Authorizations
Body
application/json
Response
Alert created
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.
Was this page helpful?