Track email messages
The Nylas Email API offers several tracking options that allow you to monitor engagement with the email messages you send. You can monitor the following interactions:
- A link in the email message has been clicked.
- The email message has been opened.
- Someone replied to the thread.
How message tracking works
When you enable a tracking flag, Nylas modifies the content of the email message so it can be tracked. You can subscribe to the notification triggers for each of the available tracking options to be notified when an event occurs.
When a user acts on an email message that you enabled tracking for (for example, opening the message), Nylas sends a POST
to your notification endpoint (webhook listener or Pub/Sub topic) with information about the action. This includes important information that you can use to track or respond to the event.
To learn more about the general structure of message tracking notifications, see the list of notification schemas.
Changes to message tracking in v3
Nylas v3 includes several small changes to message tracking to improve the clarity of tracking parameters and responses:
- The
tracking
sub-object that you include in Send Message and Create Draft requests is now calledtracking_options
. - The
tracking_options
sub-object'spayload
field is now calledlabel
to better reflect its purpose.- Notifications now also reference the
label
field.
- Notifications now also reference the
- The
recents
array'sid
field is now calledclick_id
for link clicked tracking, andopened_id
for message open tracking. - You can use one of the following tracking URLs, depending on your region:
- U.S. (Oregon):
https://tracking.us.nylas.com
- Europe:
https://tracking.eu.nylas.com
- U.S. (Oregon):
For migration purposes, you can subscribe to the following .legacy
triggers to receive tracking data initiated by the v2 Email API:
The deltas
array in the .legacy
notifications contains v2 schema tracking data.
Nylas sends .legacy
notifications only if the user's v2 account and webhook endpoint are active. You should use v3 message tracking after you finish migrating your application.
Scopes for message tracking
Before you start using message tracking, you must request the email.send
scope.
ℹ️ Because thread.replied
tracking relies on tracking new messages coming into an email inbox, you cannot implement it with the send-only
scope.
For a list of scopes that Nylas uses, see the Authentication scopes documentation.
Enable message tracking
To enable tracking for an email message, include one of the tracking_options
JSON object in your Send Message or Create Draft request.
...
"tracking_options": {
"opens": true, // Enable message open tracking.
"links": true, // Enable link clicked tracking.
"thread_replies": true, // Enable thread replied tracking.
"label": "Use this string to describe the message you're enabling tracking for. It's included in notifications about tracked events."
}
...
You can also enable message tracking using the Nylas SDKs, as in the code samples below.
from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client
nylas = Client(
os.environ.get('NYLAS_API_KEY'),
os.environ.get('NYLAS_API_URI')
)
grant_id = os.environ.get("NYLAS_GRANT_ID")
email = os.environ.get("EMAIL")
message = nylas.messages.send(
grant_id,
request_body={
"to": [{ "name": "Name", "email": email }],
"reply_to": [{ "name": "Name", "email": email }],
"reply_to_message_id": "<MESSAGE_ID>",
"subject": "Your Subject Here",
"body": "Your email body here.",
"tracking_options": {
"opens": True,
"links": True,
"thread_replies": True,
}
}
)
print(message)
require 'nylas'
nylas = Nylas::Client.new(api_key: '<NYLAS_API_KEY>')
request_body = {
subject: "With Love, from Nylas",
body: "This email was sent using the <b>Ruby SDK</b> for the Nylas Email API.
Visit <a href='https://nylas.com'>Nylas.com</a> for details.",
to: [{name: "Nylas", email: "ireadthedocs@nylas.com"}],
tracking_options: {label: "Track this message",
opens: true,
links: true,
thread_replies: true}
}
email, _ = nylas.messages.send(identifier: '<NYLAS_GRANT_ID>', request_body: request_body)
puts "Message \"#{email[:subject]}\" was sent with ID #{email[:id]}"
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class EmailTracking {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<EmailName> emailNames = new ArrayList<>();
emailNames.add(new EmailName("swag@example.com", "Nylas"));
TrackingOptions options = new TrackingOptions("Track this message",true, true, true);
SendMessageRequest requestBody = new SendMessageRequest.Builder(emailNames).
subject("With Love, from Nylas").
body("This email was sent using the <b>Java SDK</b> for the Nylas Email API. " +
"Visit <a href='https://nylas.com'>Nylas.com</a> for details.").
trackingOptions(options).build();
Response<Message> email = nylas.messages().send("<NYLAS_GRANT_ID>", requestBody);
System.out.println("Message " + email.getData().getSubject() + " was sent with ID " + email.getData().getId());
}
}
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val emailNames : List<EmailName> = listOf(EmailName("swag@example.com", "Nylas"))
val options : TrackingOptions = TrackingOptions("Track this message", true, true, true)
val requestBody : SendMessageRequest = SendMessageRequest.
Builder(emailNames).
subject("With Love, from Nylas").
body("This email was sent using the <b>Kotlin SDK</b> for the Nylas Email API. " +
"See the <a href='https://developer.nylas.com/docs/sdks/'>Nylas documentation</a> for details.").
trackingOptions(options).
build()
val email = nylas.messages().send("<NYLAS_GRANT_ID>", requestBody)
print("Message " + email.data.subject + " was sent with ID " + email.data.id)
}
Link clicked tracking
When you enable link clicked tracking for an email message, Nylas replaces the links in the message with tracking links. When an end user clicks one of the links, Nylas logs the click, forwards the user to the original link address, and sends you a notification.
📝 Link clicked tracking applies to all links in an email message, with some exceptions for security purposes. It cannot be enabled for only some links.
Nylas ignores any links that contain credentials, so you don't have to worry about rewriting sensitive URLs. For more information, see the Best practices for link clicked tracking section.
Formatting links for tracking
For link clicked tracking to work correctly, you must use a valid URI format and enclose the link in HTML anchor tags (for example, <a href="https://www.example.com">link</a>
). Nylas supports the following URI schemes:
https
mailto
tel
Nylas can detect and track links like the following examples:
<a href="https://www.google.com">google.com</a>
<a href="mailto:nyla@example.com">Mailto Nyla!</a>
<a href="tel:+1-201-555-0123">Call now to make your reservation.</a>
The links below are invalid and cannot be tracked:
<a>www.google.com</a>
: Improperly formatted HTML.<a href="zoommtg://zoom.us/join?confno=12345">Join a zoom conference</a>
: Unsupported URI scheme (zoommtg:
).
⚠️ Nylas does not replace invalid links with a tracking link. They are left as-written and are not tracked. Be sure to double-check your links before sending an email message!
Link clicked tracking examples
The following example shows the type of JSON notification you can expect.
{
"specversion": "1.0",
"type": "message.link_clicked",
"source": "/com/nylas/tracking",
"id": "4eabe42e-50e4-42ce-9014-0d602ed8e2ba",
"time": 1695480423,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"link_data": [{
"count": 1,
"url": "https://www.example.com"
}],
"message_id": "18ac281f237c934b",
"label": "Hey, just testing",
"recents": [
{
"click_id": "0",
"ip": "<IP ADDR>",
"link_index": "0",
"timestamp": 1695480422,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
},
{
"click_id": "1",
"ip": "<IP ADDR>",
"link_index": "0",
"timestamp": 1695480422,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
},
{
"click_id": "2",
"ip": "<IP ADDR>",
"link_index": "0",
"timestamp": 1695480422,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
}
],
"sender_app_id": "<app id>",
"timestamp": 1695480422
}
}
}
For more information about metadata in link clicked tracking responses, see the Link Clicked notification schema.
The Recents array in link clicked tracking
The recents
array in a message.link_clicked
notification contains entries for the last 50 link tracking events for a specific link, in a specific email message. Each entry includes a link_index
, which identifies the link that was clicked, and a click_id
, which identifies the specific event. The end user's IP address and user agent are also logged.
Event IDs are unique only within a specific recents
array, and each message/trigger pair has its own recents
array.
The message.link_clicked
notification payload also includes the link_data
dictionary, which contains the links from the message and a count
representing how many times each link has been clicked at the time that the notification was generated.
📝 Note: While the count
of events starts at 1
, the click_id
and opened_id
indices start at 0
.
Best practices for link clicked tracking
When you enable link clicked tracking, Nylas rewrites all valid HTML links with a new URL that allows tracking. This process omits and does not rewrite tracking links with embedded login credentials, because the destination servers don't recognize the rewritten credentials. For this reason, Nylas ignores links that contain credentials. The links still work when clicked, but Nylas does not track end user interactions with them. For example, private Google Form URLs contain login credentials, so Nylas ignores those links and they cannot be tracked.
Message open tracking
When you enable message open tracking for an email message, Nylas inserts a transparent one-pixel image into the message's HTML. When a recipient opens the email message, their email client makes a request to Nylas to download the file. Nylas records that request as a message.open
event, and sends you a notification.
Because this method relies on the email client requesting the file from Nylas' servers, ad blockers and content delivery networks (CDNs) can interfere with message open tracking. It's best to use message open tracking along with link clicked tracking and other methods. For more information, see Troubleshooting immediate webhook notifications.
Message open tracking examples
The following code samples show how to enable message open tracking for an email message, and the type of JSON notification you can expect.
curl --request POST \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"subject": "Hey Reaching Out with Nylas",
"body": "Hey I would like to track this link <a href='https://espn.com'>My Example Link</a>",
"to": [
{
"name": "John Doe",
"email": "john.doe@example.com"
}
],
"tracking_options": {
"opens": true
}
}'
{
"specversion": "1.0",
"type": "message.opened",
"source": "/com/nylas/tracking",
"id": "b1e59587-0f85-4dd6-9ab9-d174b97bbdc9",
"time": 1695480567,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"message_data": {
"count": 1,
"timestamp": 1695480410
},
"message_id": "18ac281f237c934b",
"label": "Testing Nylas Messaged Opened Tracking",
"recents": [
{
"ip": "<IP ADDR>",
"opened_id": 0,
"timestamp": 1695480567,
"user_agent": "Mozilla/5.0"
},
{
"ip": "<IP ADDR>",
"opened_id": 1,
"timestamp": 1695480567,
"user_agent": "Mozilla/5.0"
},
{
"ip": "<IP ADDR>",
"opened_id": 2,
"timestamp": 1695480567,
"user_agent": "Mozilla/5.0"
}
],
"sender_app_id": "<app id>",
"timestamp": 1695480410
}
}
}
You can also enable message open tracking using the Nylas SDKs, as in the code samples below.
import 'dotenv/config'
import Nylas from 'nylas'
const NylasConfig = {
apiKey: process.env.NYLAS_API_KEY,
apiUri: process.env.NYLAS_API_URI,
}
const nylas = new Nylas(NylasConfig)
async function sendEmail() {
try {
const sentMessage = await nylas.messages.send({
identifier: process.env.NYLAS_GRANT_ID,
requestBody: {
to: [{ name: "Name", email: process.env.EMAIL}],
replyTo: [{ name: "Name", email: process.env.EMAIL}],
replyToMessageId: "<MESSAGE_ID>",
subject: "Your Subject Here",
body: "Your email body here.",
trackingOptions: {
opens: true,
},
}
})
console.log('Email sent:', sentMessage)
} catch (error) {
console.error('Error sending email:', error)
}
}
sendEmail()
from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client
nylas = Client(
os.environ.get('NYLAS_API_KEY'),
os.environ.get('NYLAS_API_URI')
)
grant_id = os.environ.get("NYLAS_GRANT_ID")
email = os.environ.get("EMAIL")
message = nylas.messages.send(
grant_id,
request_body={
"to": [{ "name": "Name", "email": email }],
"reply_to": [{ "name": "Name", "email": email }],
"reply_to_message_id": "<MESSAGE_ID>",
"subject": "Your Subject Here",
"body": "Your email body here.",
"tracking_options": {
"opens": True,
"links": False,
"thread_replies": False,
}
}
)
print(message)
require 'nylas'
nylas = Nylas::Client.new(api_key: '<NYLAS_API_KEY>')
request_body = {
subject: "With Love, from Nylas",
body: "This email was sent using the <b>Ruby SDK</b> for the Nylas Email API.
Visit <a href='https://nylas.com'>Nylas.com</a> for details.",
to: [{name: "Nylas", email: "swag@example.com"}],
tracking_options: {label: "Track when the message gets opened",
opens: true,
links: false,
thread_replies: false}
}
email, _ = nylas.messages.send(identifier: '<NYLAS_GRANT_ID>', request_body: request_body)
puts "Message \"#{email[:subject]}\" was sent with ID #{email[:id]}"
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class EmailTracking {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<EmailName> emailNames = new ArrayList<>();
emailNames.add(new EmailName("swag@example.com", "Nylas"));
TrackingOptions options = new TrackingOptions("Track when the message gets opened", true, false, false);
SendMessageRequest requestBody = new SendMessageRequest.Builder(emailNames).
subject("With Love, from Nylas").
body("This email was sent using the <b>Java SDK</b> for the Nylas Email API. " +
"Visit <a href='https://nylas.com'>Nylas.com</a> for details.").
trackingOptions(options).build();
Response<Message> email = nylas.messages().send("<NYLAS_GRANT_ID>", requestBody);
System.out.println("Message " + email.getData().getSubject() + " was sent with ID " + email.getData().getId());
}
}
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val emailNames : List<EmailName> = listOf(EmailName("swag@example.com", "Nylas"))
val options : TrackingOptions = TrackingOptions("Track when the message gets opened", true, false, false)
val requestBody : SendMessageRequest = SendMessageRequest.
Builder(emailNames).
subject("With Love, from Nylas").
body("This email was sent using the <b>Kotlin SDK</b> for the Nylas Email API. " +
"Visit <a href='https://nylas.com'>Nylas.com</a> for details.").
trackingOptions(options).
build()
val email = nylas.messages().send("<NYLAS_GRANT_ID>", requestBody)
print("Message " + email.data.subject + " was sent with ID " + email.data.id)
}
The Recents array in message open tracking
Like link clicked tracking, the notification for message.opened
events contains a recents
array. This array contains entries for the last 50 events for the email message that generated the notification. Each entry includes an opened_id
in API v3 which identifies the specific event, the timestamp for the message.opened
event, and the end user's IP address and user agent.
Thread replied tracking
When you send an email message with thread replied tracking enabled, Nylas notifies you when there are new responses to the thread.
Thread replied tracking examples
The following code samples show how to enable thread replied tracking for an email message, and the kind of JSON notification you can expect.
curl --request POST \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"subject": "Hey Reaching Out with Nylas",
"body": "Hey I would like to track this link <a href='https://espn.com'>My Example Link</a>",
"to": [
{
"name": "John Doe",
"email": "john.doe@example.com"
}
],
"tracking_options": {
"thread_replies": true
}
}'
{
"specversion": "1.0",
"type": "thread.replied",
"source": "/com/nylas/tracking",
"id": "d67b0806-b263-4fca-b297-c62478a66e01",
"time": 1696007157,
"data": {
"application_id": "NYLAS_APPLICATION_ID",
"grant_id": "NYLAS_GRANT_ID",
"object": {
"message_id": "<message-id-of-reply>",
"root_message_id": "<message-id-of-original-tracked-message>",
"label": "some-client-label",
"reply_data": {
"count": 1
},
"sender_app_id": "<app-id>",
"thread_id": "<thread-id-of-sent-message>",
"timestamp": 1696007157
}
}
}
You can also enable thread replied tracking using the Nylas SDKs, as in the code samples below.
import 'dotenv/config'
import Nylas from 'nylas'
const NylasConfig = {
apiKey: process.env.NYLAS_API_KEY,
apiUri: process.env.NYLAS_API_URI,
}
const nylas = new Nylas(NylasConfig)
async function sendEmail() {
try {
const sentMessage = await nylas.messages.send({
identifier: process.env.NYLAS_GRANT_ID,
requestBody: {
to: [{ name: "Name", email: process.env.EMAIL}],
replyTo: [{ name: "Name", email: process.env.EMAIL}],
replyToMessageId: "<MESSAGE_ID>",
subject: "Your Subject Here",
body: "Your email body here.",
trackingOptions: {
threadReplies: true,
},
}
})
console.log('Email sent:', sentMessage)
} catch (error) {
console.error('Error sending email:', error)
}
}
sendEmail()
from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client
nylas = Client(
os.environ.get('NYLAS_API_KEY'),
os.environ.get('NYLAS_API_URI')
)
grant_id = os.environ.get("NYLAS_GRANT_ID")
email = os.environ.get("EMAIL")
message = nylas.messages.send(
grant_id,
request_body={
"to": [{ "name": "Name", "email": email }],
"reply_to": [{ "name": "Name", "email": email }],
"reply_to_message_id": "<MESSAGE_ID>",
"subject": "Your Subject Here",
"body": "Your email body here.",
"tracking_options": {
"opens": False,
"links": False,
"thread_replies": True,
}
}
)
print(message)
require 'nylas'
nylas = Nylas::Client.new(api_key: '<NYLAS_API_KEY>')
request_body = {
subject: "With Love, from Nylas",
body: "This email was sent using the <b>Ruby SDK</b> for the Nylas Email API.
Visit <a href='https://nylas.com'>Nylas.com</a> for details.",
to: [{name: "Nylas", email: "swag@example.com"}],
tracking_options: {label: "Track message replies",
opens: false,
links: false,
thread_replies: true}
}
email, _ = nylas.messages.send(identifier: '<NYLAS_GRANT_ID>', request_body: request_body)
puts "Message \"#{email[:subject]}\" was sent with ID #{email[:id]}"
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class EmailTracking {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<EmailName> emailNames = new ArrayList<>();
emailNames.add(new EmailName("swag@example.com", "Nylas"));
TrackingOptions options = new TrackingOptions("Track message replies",false, false, true);
SendMessageRequest requestBody = new SendMessageRequest.Builder(emailNames).
subject("With Love, from Nylas").
body("This email was sent using the <b>Java SDK</b> for the Nylas Email API. " +
"Visit <a href='https://nylas.com'>Nylas.com</a> for details.").
trackingOptions(options).build();
Response<Message> email = nylas.messages().send("<NYLAS_GRANT_ID>", requestBody);
System.out.println("Message " + email.getData().getSubject() + " was sent with ID " + email.getData().getId());
}
}
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val emailNames : List<EmailName> = listOf(EmailName("swag@example.com", "Nylas"))
val options : TrackingOptions = TrackingOptions("Track message replies", false, false, true)
val requestBody : SendMessageRequest = SendMessageRequest.
Builder(emailNames).
subject("With Love, from Nylas").
body("This email was sent using the <b>Kotlin SDK</b> for the Nylas Email API. " +
"Visit <a href='https://nylas.com'>Nylas.com</a> for details.").
trackingOptions(options).
build()
val email = nylas.messages().send("<NYLAS_GRANT_ID>", requestBody)
print("Message " + email.data.subject + " was sent with ID " + email.data.id)
}
Message tracking errors
The following sections describe errors that you may encounter when using message tracking.
Link clicked tracking errors
Link clicked tracking is limited to 20 tracked links per email message. An email message that contains more than 20 links and has link clicked tracking enabled may fail to send. In this case, you might see the following error message:
The message has not been sent. Link tracking cannot be supported for this number of links and/or size of payload. Please try resending with link tracking disabled.
Disable link clicked tracking or reduce the number of links in the email message to send it.
Message open tracking errors
If an email message with message open tracking enabled cannot handle the metadata object's size (for example, the payload
is too large), you might receive the following error message:
The message has not been sent. Please try resending with open tracking disabled.
Disable message open tracking to send the email message.
Thread replied tracking errors
If an email message with thread replied tracking enabled cannot handle the metadata object's size (for example, the payload
is too large), you might receive the following error message:
The message has not been sent. Please try resending with reply tracking disabled.
Disable thread replied tracking to send the email message.