Skip to content
Skip to main content
GET
https://api.us.nylas.com/v3/activity/tracking

List tracking events

Returns opens and link clicks on your tracked messages, newest first. Filter by message, sender, label, or event type to see who engaged with a campaign and which links they clicked.

Covers transactional and Agent Account sends that had open or link click tracking turned on. Events are kept for 90 days, and the default window is the last 7 days.

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

NYLAS API KEY

Parameters

Query parameters

event_typearray

Return only these event types. Repeat the parameter to include both.

Example: ["link_clicked"]
labelstring

Return only events for messages sent with this tracking_options.label.

Example: "october-newsletter"
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.

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>
next_cursorstringnullable

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

GEThttps://api.us.nylas.com/v3/activity/tracking?event_type=link_clicked&label=october-newsletter&sending_domain=mail.example.com&from=support%40example.com&grant_id=0b7e5a6b-0cbd-4a39-b3ba-2b53b1b0a7d6&message_id=5a8f7b2e-3c1d-4e9f-8a6b-2d4c6e8f0a1b&thread_id=9c3e1f7a-6b2d-4a8e-b5c4-1e7d3a9f2b6c&start=1792540800&end=1793145599&order=desc&limit=50

Find your API key in the Nylas Dashboard under API Keys in your application settings.