---
title: "Create an alert rule"
method: POST
path: "/v3/alerts/send"
tags: ["Send alerts"]
---

# Create an alert rule

`POST /v3/alerts/send`

## Request

- Base URL: `https://api.us.nylas.com`
- URL: `https://api.us.nylas.com/v3/alerts/send`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nylas/apis/nylas-api/docs/v3/alerts/send/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a rule that watches the bounce, complaint, or delivery rate of each of your sending
domains. Nylas checks every rule every 5 minutes. When a domain's rate over the last
`window_hours` crosses the threshold, Nylas sends an
[`alert.triggered`](/docs/reference/notifications/send-alerts/alert-triggered/) notification. Subscribe
to that trigger with a webhook to receive it. Rules cover Agent Account and Transactional send
messages only.

## Request body

- object
  - `metric` 'bounce_rate' | 'complaint_rate' | 'delivery_rate', required: The rate to watch. `bounce_rate` and `complaint_rate` fire when the rate goes above the threshold, and `delivery_rate` fires when it goes below.
  - `threshold` number, required: The threshold, as a percentage with up to 2 decimal places. For `bounce_rate` and `complaint_rate`, at least 0 and less than 100. For `delivery_rate`, more than 0 and at most 100. The rule fires only when the rate is past the threshold, not equal to it.
  - `window_hours` integer, required: How many hours of sending the rate covers, from 1 to 24.
  - `min_volume` integer: The minimum number of messages a sending domain must send in the window before the rule can fire. Use it to avoid alerts on low volume, where one bounce is a high rate.

## Response `201`

Created. Returns the new alert rule.

- object
  - `request_id` string: The request ID.
  - `data` AlertRule: A rule that sends an `alert.triggered` webhook when a sending domain's rate crosses a threshold.
    - `id` string, uuid: The ID of the alert rule.
    - `application_id` string: The ID of your Nylas application.
    - `metric` 'bounce_rate' | 'complaint_rate' | 'delivery_rate': The rate the rule watches. `bounce_rate` is hard bounces as a percentage of sent messages, `complaint_rate` is complaints as a percentage of delivered messages, and `delivery_rate` is delivered messages as a percentage of sent messages.
    - `direction` 'above' | 'below': Whether the rule fires when the rate goes above or below the threshold. Set by the metric: `above` for `bounce_rate` and `complaint_rate`, `below` for `delivery_rate`.
    - `threshold` number: The threshold, as a percentage.
    - `window_hours` integer: How many hours of sending the rate covers.
    - `min_volume` integer: The minimum number of messages a sending domain must send in the window before the rule can fire.
    - `created_at` integer: When the rule was created, as a Unix timestamp in seconds.
    - `updated_at` integer: When the rule was last updated, as a Unix timestamp in seconds.

## Other responses

- `400`: Bad request. The request body isn't valid, or your application already has 20 alert rules.
- `401`: Unauthorized
- `403`: Forbidden. These endpoints need your application's API key, not a grant access token.

## Changes

- **2026-10-30** `7b9fe7c66c1c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nylas/apis/nylas-api/changes/v3/alerts/send/post.md)

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) - [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nylas/apis/nylas-api/revisions/7782a3e3ab70?raw)