Skip to main content
POST

​
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

​
scope

​
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.
  • slack — sends a Slack message. Requires a Slack integration to be connected on the team.

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json
​
widget
enum<string>
required
Available options:
warmup,
outreach
​
metric
enum<string>
required
Available options:
inboxRate,
spamRate,
score,
deliveryRate,
bounceRate
​
severity
enum<string>
required
Available options:
warning,
critical
​
scope
enum<string>
required
Available options:
global,
mailbox,
domain
​
threshold
number
required
Required range: 0 <= x <= 100
​
comparisonOperator
enum<string>
required
Available options:
equal,
below,
above
​
periodDays
integer
required
Required range: 1 <= x <= 30
​
periodMode
enum<string>
required
Available options:
rolling,
consecutive
​
scopeEntities
string[]

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).

​
channelConfig
any
​
recheckDelayHours
integer

Cool-down between re-evaluations after the alert triggers, in hours. Defaults to 12.

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.

​
_id
string

Unique alert configuration identifier (prefixed with dac_).

​
teamId
string

ID of the team that owns the alert.

​
createdBy
string

ID of the user who created the alert.

​
createdAt
string<date-time>

Creation timestamp.

​
updatedAt
string<date-time>

Last update timestamp.

​
widget
enum<string>

Data source the alert evaluates. warmup checks lemwarm metrics; outreach checks campaign-sending metrics.

Available options:
warmup,
outreach
​
metric
enum<string>

Metric being monitored. Valid combinations depend on widget: warmup supports inboxRate, spamRate, score; outreach supports deliveryRate, bounceRate.

Available options:
inboxRate,
spamRate,
score,
deliveryRate,
bounceRate
​
severity
enum<string>

Alert severity.

Available options:
warning,
critical
​
scope
enum<string>

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.

Available options:
global,
mailbox,
domain
​
scopeEntities
string[]

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.

​
threshold
number

Threshold value the metric is compared against (0–100, expressed as a percentage for rate metrics).

Required range: 0 <= x <= 100
​
comparisonOperator
enum<string>

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.

Available options:
equal,
below,
above
​
periodDays
integer

Length of the evaluation window, in days (1–30).

Required range: 1 <= x <= 30
​
periodMode
enum<string>

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.

Available options:
rolling,
consecutive
​
channelConfig
object

Notification channels triggered when the alert fires. At least one channel must be enabled. If omitted on creation, defaults to inapp only.

​
enabled
boolean

Whether the alert is currently active. Disabled alerts are not evaluated.

​
lastCheckedAt
string<date-time>

Last time the alert was evaluated.

​
lastTriggeredAt
string<date-time>

Last time the alert fired.

​
recheckDelayHours
integer

Cool-down between re-evaluations after the alert has triggered, in hours. Defaults to 12.