--- title: "Return a sending health summary" method: GET path: "/v3/metrics/send/summary" tags: ["Send events"] --- # Return a sending health summary `GET /v3/metrics/send/summary` ## Request - Base URL: `https://api.us.nylas.com` - URL: `https://api.us.nylas.com/v3/metrics/send/summary` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Query parameters - `start` string, date - `end` string, date - `sending_domain` string ## Response `200` Success. Returns the summary. - object - `request_id` string: The request ID. - `data` SendSummary - `health` object: An overall grade for your sending. Health always covers the last 7 days, including today, whatever window you request. - `state` '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` Window: A date window. Both days are UTC dates and both are included. - `start` string, date: The first day of the window. - `end` string, 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` SendFinding[]: Up to 3 likely causes when the state is `at_risk` or `critical`, most serious first. Empty otherwise. - `rule` '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` '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` '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` '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, 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` Counts: 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` Window: A date window. Both days are UTC dates and both are included. - `start` string, date: The first day of the window. - `end` string, 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` Counts: 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: A rate for the window, compared with the same rate in the previous window of equal length. - `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` 'ok' | 'warn' | 'crit' | 'null', nullable: How the rate compares with healthy limits. `null` when the rate is `null`. - `bounce_rate` object: A rate for the window, compared with the same rate in the previous window of equal length. - `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` 'ok' | 'warn' | 'crit' | 'null', nullable: How the rate compares with healthy limits. `null` when the rate is `null`. - `complaint_rate` object: A rate for the window, compared with the same rate in the previous window of equal length. - `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` 'ok' | 'warn' | 'crit' | 'null', nullable: How the rate compares with healthy limits. `null` when the rate is `null`. - `prior_period` Window: A date window. Both days are UTC dates and both are included. - `start` string, date: The first day of the window. - `end` string, date: The last day of the window. ## Other responses - `400`: Bad request. A query parameter or the request body isn't valid. - `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/metrics/send/summary/get.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)