# Return a sending health summary

> **GET** `https://api.us.nylas.com/v3/metrics/send/summary`

Source: https://developer.nylas.com/docs/reference/api/send-events/get-send-summary/

Returns your delivery, bounce, and complaint rates for a date window, compared with the previous
window of the same length, plus an overall health grade for the last 7 days. When health is
`at_risk` or `critical`, `findings` points to the likely cause, such as one recipient domain
bouncing most of your mail, and gives you a filter for the events behind it.

Messages count on the day they were sent, so the rates for recent days can still change as
delivery results arrive.

**Authentication:** NYLAS_API_KEY

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `start` | string, format: date | No | The first day of the window, as a UTC date in `YYYY-MM-DD` format. Defaults to six days before `end`, so the default window covers 7 days. A window can cover up to 365 days. |
| `end` | string, format: date | No | The last day of the window, as a UTC date in `YYYY-MM-DD` format. Defaults to today. Today is included as a partial day. |
| `sending_domain` | string, maxLength: 255 | No | Return only data for messages sent from this domain. |

## Responses

### 200 - Success. Returns the summary.

- `request_id` (string) - The request ID.
- `data` (object)
  - `health` (object) - An overall grade for your sending. Health always covers the last 7 days, including today,
whatever window you request.
    - `state` (string, one of: `healthy`, `at_risk`, `critical`, `insufficient_data`) - `critical` when any rate is past its critical line, `at_risk` when any rate is past its
warning line, and `healthy` otherwise. `insufficient_data` when fewer messages than
`min_assess_volume` were sent.
    - `window` (object) - A date window. Both days are UTC dates and both are included.
      - `start` (string, format: date) - The first day of the window.
      - `end` (string, format: date) - The last day of the window.
    - `min_assess_volume` (integer) - The number of messages that must be sent in the last 7 days before health is graded.
    - `findings` (array) - Up to 3 likely causes when the state is `at_risk` or `critical`, most serious first. Empty otherwise.
      - `rule` (string, one of: `concentration`, `spike`, `overall`) - The kind of finding. `concentration` means most of the problem comes from one sending domain,
sender, or recipient domain. `spike` means one day was much worse than usual. `overall` means
the problem is spread across your sending.
      - `severity` (string, one of: `high`, `watch`) - `high` when the rate is past the critical line, `watch` when it's past the warning line.
      - `title` (string) - A one-line summary of the finding.
      - `evidence` (object) - The numbers behind the finding.
        - `metric` (string, one of: `delivery_rate`, `bounce_rate`, `complaint_rate`) - The rate the finding is about.
        - `value` (number) - The rate for the subject of the finding, as a percentage.
        - `threshold` (number) - The healthy limit for the rate, as a percentage.
        - `dimension` (string, one of: `sending_domain`, `agent_account`, `recipient_domain`, ``) - For a `concentration` finding, what the subject is grouped by. Empty for other findings.
        - `dimension_value` (string) - For a `concentration` finding, the sending domain, sender, or recipient domain the problem comes from.
        - `share_of_excess` (number) - For a `concentration` finding, the share of the problem that comes from this subject, as a fraction from 0 to 1.
        - `day` (string, format: date) - For a `spike` finding, the day of the spike.
        - `baseline_value` (number) - For a `spike` finding, the usual rate over the previous 28 days, as a percentage.
        - `totals` (object) - Message counts. Each message counts once per recipient, on the day it was sent.
          - `sent` (integer) - The number of messages Nylas accepted for delivery.
          - `delivered` (integer) - The number of messages the recipient's mail server accepted.
          - `bounced_hard` (integer) - The number of permanent bounces, such as an address that doesn't exist. Includes recipients on a suppression list.
          - `bounced_soft` (integer) - The number of temporary bounces, such as a full mailbox.
          - `bounced_undetermined` (integer) - The number of bounces the recipient's server didn't classify.
          - `rejected` (integer) - The number of messages Nylas didn't send because they contained a virus or other bad content.
          - `complaints` (integer) - The number of recipients who marked the message as spam.
        - `window` (object) - A date window. Both days are UTC dates and both are included.
          - `start` (string, format: date) - The first day of the window.
          - `end` (string, format: date) - The last day of the window.
      - `recommendation` (string) - What to do next.
      - `logs_filter` (object) - Query parameters for [List send events](/docs/reference/api/send-events/list-send-events/)
that return the events behind the finding.
  - `totals` (object) - Message counts. Each message counts once per recipient, on the day it was sent.
    - `sent` (integer) - The number of messages Nylas accepted for delivery.
    - `delivered` (integer) - The number of messages the recipient's mail server accepted.
    - `bounced_hard` (integer) - The number of permanent bounces, such as an address that doesn't exist. Includes recipients on a suppression list.
    - `bounced_soft` (integer) - The number of temporary bounces, such as a full mailbox.
    - `bounced_undetermined` (integer) - The number of bounces the recipient's server didn't classify.
    - `rejected` (integer) - The number of messages Nylas didn't send because they contained a virus or other bad content.
    - `complaints` (integer) - The number of recipients who marked the message as spam.
  - `metrics` (object) - Rates for the window you requested. Each rate has a `status`:

| Rate | `ok` | `warn` | `crit` |
| --- | --- | --- | --- |
| `delivery_rate` | 95% or more | 90% or more | below 90% |
| `bounce_rate` | below 5% | below 10% | 10% or more |
| `complaint_rate` | below 0.1% | below 0.5% | 0.5% or more |
    - `delivery_rate` (object) - Delivered messages as a percentage of sent messages.
      - `value` (number, nullable) - The rate for the window, as a percentage from 0 to 100. `null` when there is nothing to divide by.
      - `delta_pp` (number, nullable) - The change from the previous window, in percentage points (`value` minus `prior_value`). `null` when either value is `null`.
      - `prior_value` (number, nullable) - The same rate for the previous window. `null` when it can't be calculated.
      - `status` (string, nullable, one of: `ok`, `warn`, `crit`, `null`) - How the rate compares with healthy limits. `null` when the rate is `null`.
    - `bounce_rate` (object) - Hard bounces as a percentage of sent messages.
      - `value` (number, nullable) - The rate for the window, as a percentage from 0 to 100. `null` when there is nothing to divide by.
      - `delta_pp` (number, nullable) - The change from the previous window, in percentage points (`value` minus `prior_value`). `null` when either value is `null`.
      - `prior_value` (number, nullable) - The same rate for the previous window. `null` when it can't be calculated.
      - `status` (string, nullable, one of: `ok`, `warn`, `crit`, `null`) - How the rate compares with healthy limits. `null` when the rate is `null`.
    - `complaint_rate` (object) - Complaints as a percentage of delivered messages.
      - `value` (number, nullable) - The rate for the window, as a percentage from 0 to 100. `null` when there is nothing to divide by.
      - `delta_pp` (number, nullable) - The change from the previous window, in percentage points (`value` minus `prior_value`). `null` when either value is `null`.
      - `prior_value` (number, nullable) - The same rate for the previous window. `null` when it can't be calculated.
      - `status` (string, nullable, one of: `ok`, `warn`, `crit`, `null`) - How the rate compares with healthy limits. `null` when the rate is `null`.
  - `prior_period` (any) - The previous window of equal length that the rates are compared with. `null` when it's older than the data Nylas keeps.
    - **object**
      - `start` (string, format: date) - The first day of the window.
      - `end` (string, format: date) - The last day of the window.
    - **null**

### 400 - Bad request. A query parameter or the request body isn't valid.

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 403 - Forbidden. These endpoints need your application's API key, not a grant access token.

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl --request GET \
  --url "https://api.us.nylas.com/v3/metrics/send/summary?start=2026-10-24&end=2026-10-30" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
```