List send events - Send Events - API Reference

GET

https://api.us.nylas.com/v3/activity/send

Returns what happened to your messages, one event per recipient: accepted, delivered, bounced, marked as spam, or rejected. Filter by recipient, message, sender, or event type to find out why a message didn't reach someone, or to list every hard bounce from a sending domain.

Covers transactional and Agent Account sends. Events are kept for 90 days, and the default window is the last 7 days. Results are sorted by event time, newest first.

This endpoint is for looking back at events, not for real-time updates. Avoid polling it for new events. To act on each delivery outcome as it happens, use webhook notifications.

NYLAS API KEY

Parameters

Query parameters

event_typearray

Return only these event types. Repeat the parameter to include more than one.

Example: ["bounced"]

bounce_classstring

Return only bounces of this class.

hardsoftundetermined

recipientstring

Return only events for this recipient email address.

Example: "[email protected]"

recipient_domainstring

Return only events for recipients at this domain.

Example: "example.org"

sending_domainstring

Return only data for messages sent from this domain.

Example: "mail.example.com"

fromstring

Return only events for messages sent from this email address.

Example: "[email protected]"

grant_idstring

Return only events for messages sent by this Agent Account grant.

Example: "0b7e5a6b-0cbd-4a39-b3ba-2b53b1b0a7d6"

message_idstring

Return only events for this message.

Example: "5a8f7b2e-3c1d-4e9f-8a6b-2d4c6e8f0a1b"

thread_idstring

Return only events for messages in this Agent Account thread.

Example: "9c3e1f7a-6b2d-4a8e-b5c4-1e7d3a9f2b6c"

startinteger<int64>

Return events at or after this time, as a Unix timestamp in seconds. Defaults to midnight UTC six days ago, so the default window covers the last 7 days. Activity is kept for 90 days, so an earlier value returns events from the last 90 days only.

Example: 1792540800

endinteger<int64>

Return events at or before this time, as a Unix timestamp in seconds. Defaults to the time of the request. Must not be earlier than start.

Example: 1793145599

orderstring

The sort order of the results by event time. desc returns the newest events first.

descasc

Default: "desc"

limitinteger

The maximum number of objects to return. See Pagination for more information.

Default: 50

page_tokenstring

An identifier that specifies which page of data to return. You can get this value from the next_cursor response field. See Pagination for more information.

Responses

request_idstring

The request ID.

dataarray<object>

Array items:

idstring

The ID of the event.

Example: "1110f3b5fa7cc381421942082f1e8c8fe2b85f0072b6c67b123a2bf4d8286848"

event_typestring

What happened. accepted means Nylas accepted the message for delivery. delivered means the recipient's mail server accepted it. bounced means it wasn't delivered. complaint means the recipient marked it as spam. rejected means Nylas didn't send it because of bad content.

accepteddeliveredbouncedcomplaintrejected

Example: "bounced"

bounce_classstring

For a bounce, whether it's permanent (hard), temporary (soft), or unclassified (undetermined). Stop sending to addresses that hard-bounce.

hardsoftundetermined

Example: "hard"

timestampinteger<int64>

When the event happened, as a Unix timestamp in seconds.

Example: 1792785245

application_idstring

The ID of your Nylas application.

Example: "26302083-12ae-4f38-91fe-6cba93da03ee"

grant_idstring

The Agent Account grant that sent the message. Empty for a transactional send.

Example: "0b7e5a6b-0cbd-4a39-b3ba-2b53b1b0a7d6"

message_idstring

The ID of the message. For a transactional send, this is the message's Message-ID header.

Example: "5a8f7b2e-3c1d-4e9f-8a6b-2d4c6e8f0a1b"

thread_idstring

The Agent Account thread the message belongs to. Empty for a transactional send.

Example: "9c3e1f7a-6b2d-4a8e-b5c4-1e7d3a9f2b6c"

fromstring

The email address the message was sent from.

Example: "[email protected]"

sending_domainstring

The domain the message was sent from.

Example: "mail.example.com"

recipientstring

The recipient's email address.

Example: "[email protected]"

recipient_domainstring

The recipient's domain.

Example: "example.org"

subjectstring

The message subject.

Example: "Your order has shipped"

reasonstring

A short summary of why the event happened, such as the bounce subtype and status code, the SMTP response for a delivery, or the feedback type for a complaint. Empty for accepted.

Example: "General (5.1.1)"

detailobject

Delivery details reported by the recipient's mail server. Only the fields that apply to the event are included.

next_cursorstringnullable

A cursor pointing to the next page of results for the request.

curl --request GET \ --url "https://api.us.nylas.com/v3/activity/[email protected]&event_type=bounced&limit=50" \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>'