Return a sending health summary - Send Events - API Reference

GET

https://api.us.nylas.com/v3/metrics/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.

NYLAS API KEY

Parameters

Query parameters

startstring<date>

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.

Example: "2026-10-01"

endstring<date>

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.

Example: "2026-10-30"

sending_domainstring

Return only data for messages sent from this domain.

Example: "mail.example.com"

Responses

request_idstring

The request ID.

dataobject

healthobject

An overall grade for your sending. Health always covers the last 7 days, including today, whatever window you request.

statestring

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.

healthyat_riskcriticalinsufficient_data

Example: "at_risk"

windowobject

A date window. Both days are UTC dates and both are included.

min_assess_volumeinteger

The number of messages that must be sent in the last 7 days before health is graded.

Example: 100

findingsarray<object>

Up to 3 likely causes when the state is at_risk or critical, most serious first. Empty otherwise.

Array items:

rulestring

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.

concentrationspikeoverall

Example: "concentration"

severitystring

high when the rate is past the critical line, watch when it's past the warning line.

highwatch

Example: "high"

titlestring

A one-line summary of the finding.

evidenceobject

The numbers behind the finding.

recommendationstring

What to do next.

logs_filterobject

Query parameters for List send events that return the events behind the finding.

Example: {"recipient_domain":"example.org","event_type":["bounced"],"bounce_class":"hard"}

totalsobject

Message counts. Each message counts once per recipient, on the day it was sent.

metricsobject

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

prior_periodany

The previous window of equal length that the rates are compared with. null when it's older than the data Nylas keeps.