Message Tracking
The Nylas API offers several ways of tracking different types of actions that may happen to a message or thread. You can track:
- Links clicked
- Message opened
- Thread replied
We'll notify you when these actions occur by sending a webhook notification to your server. If you haven't set up webhooks yet, review our webhooks documentation. Ensure that you've enabled all the appropriate triggers you'd like to be notified about in your developer dashboard before sending a message with tracking enabled.
Nylas detects an email has been read by embedding an image pixel into the message HTML. The image pixel needs to be downloaded for Nylas to detect that the message was opened. Only the initial download is tracked.
There are three different ways you can track a message or thread, and you can use any combination of these tracking features. All you have to do is include a tracking attribute when you send a message through the /send endpoint.
How Message Tracking Works
Once a user acts on a message that you've enabled tracking for (e.g., opening the message), Nylas will make a POST request to your webhook endpoint, with delta information about the action that occurred.
The object_data will contain a metadata sub-attribute that has information about the action. To see the more general structure of the webhook notification, see Webhooks
Enabling Tracking
To enable tracking for a message, include a tracking attribute with the other attributes when sending a message. You can include the tracking object when sending a draft or when sending a message directly. .
The Tracking Object
| Attribute | Type | Description |
|---|---|---|
| links | boolean | True enables link tracking. |
| opens | boolean | True enables message open tracking. |
| thread_replies | boolean | True enables thread reply tracking. |
| payload | string | An optional string that allows you to keep track of additional information. This string will be included in the webhook notification. |
curl -X POST -H "Authorization: Basic <access_token>" -d '{
"reply_to_message_id": "84umizq7c4jtrew491brpa6iu",
"body" : "Please click this: <a href='https://nylas.com/'>click</a>",
"subject": "New Site",
"to": [
{
"name": "Nylas",
"email": "[email protected]"
}
],
"tracking": {
"links": true,
"opens": true,
"thread_replies": false,
"payload": "Any string you want!!"
}
}' "https://api.nylas.com/send" from nylas import APIClient
# Initialize and connect to the Nylas client
nylas = APIClient(
CLIENT_ID,
CLIENT_SECRET,
ACCESS_TOKEN
)
# If the draft has not been created
# Create a draft with a tracking object
draft = nylas.drafts.create()
draft.subject = "With Love, from Nylas"
draft.body = "This email was sent using the Nylas Email API. Visit https://nylas.com for details."
draft.to = [{'name': 'Me', 'email': '[email protected]'}]
draft.tracking = {"links": 'true', "opens": 'true', "thread_replies": 'true', "payload": "payload"}
# Send the draft
draft.send()
# Or, if the draft already exists
# Just add the tracking object to the existing draft object
draft = nylas.drafts.get(draft.id)
draft.tracking = {"links": 'true', "opens": 'true', "thread_replies": 'true', "payload": "payload"}
# Send the draft
draft.send() import com.nylas.NylasClient;
import com.nylas.NylasAccount;
import com.nylas.Tracking;
import com.nylas.Draft;
import com.nylas.NameEmail;
import java.util.Arrays;
public class NylasExamples {
public static void messageTrackingExample() throws Exception {
// Initialize and connect to the Nylas client
NylasClient nylas = new NylasClient();
NylasAccount account = nylas.account("ACCESS_TOKEN");
// If the draft has not been created
Draft draft = new Draft();
draft.setSubject("With Love, From Nylas");
draft.setTo(Arrays.asList(new NameEmail("Nylas", "[email protected]")));
draft.setBody("This email was sent using the Nylas email API. Visit https://nylas.com for details.");
// Create the tracking object and add it to the draft
Tracking tracking = new Tracking();
tracking.setOpens(true);
tracking.setLinks(true);
tracking.setThreadReplies(true);
tracking.setPayload("payload");
draft.setTracking(tracking);
// Send the draft
account.drafts().send(draft);
// Or, if the draft already exists
// Just add the tracking object to the existing draft object
Draft draft = account.drafts().get("draft-id");
draft.setTracking(tracking);
// Send the draft
account.drafts().send(draft);
}
} const Nylas = require('nylas');
const { default: Draft } = require('nylas/lib/models/draft');
// Initialize and connect to the Nylas client
Nylas.config({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET
});
const nylas = Nylas.with(ACCESS_TOKEN);
// If the draft has not been created
let draft = new Draft(nylas, {
subject: 'With Love, from Nylas',
to: [{ name: 'Nylas', email: '[email protected]' }],
body: 'This email was sent using the Nylas email API. Visit https://nylas.com for details.'
});
// Create the tracking object
const tracking = { "links": true, "opens": true, "thread_replies": true, "payload": "payload" };
// Send the new draft with the tracking object passed in as an argument
draft.send(tracking).then(message => {
console.log(`${message.id} was sent`);
});
// Or, if the draft already exists
draft = nylas.drafts.find('draft-id');
// Send the existing draft with the tracking object passed in as an argument
draft.send(tracking).then(message => {
console.log(`${message.id} was sent`);
});
#!/usr/bin/env ruby
require 'nylas'
# Initialize and connect to the Nylas client
nylas = Nylas::API.new(
app_id: CLIENT_ID,
app_secret: CLIENT_SECRET,
access_token: ACCESS_TOKEN
)
# If the draft has not been created
# Create a draft with a tracking object
draft = nylas.drafts.create(
to: [{ email: '[email protected]', name: "Nylas" }],
subject: 'With Love, from Nylas',
body: 'This email was sent using the Nylas email API. Visit https://nylas.com for details.',
tracking: { "links": true, "opens": true, "thread_replies": true }
)
# Send the draft
draft.send!
# Or, if the draft already exists
# Just add the tracking object to the existing draft object
draft = nylas.drafts.find('draft-id')
draft.tracking = { "links": true, "opens": true, "thread_replies": true, "payload": "payload" }
# Send the draft
draft.send! Link Clicked
When you send a message with link tracking enabled, you will be notified whenever any of the recipients click on tracked links in that message.
To enable link tracking for a message, set links to true in the tracking attribute, when sending the message through the /send endpoint.
Link Tracking Best Practices
Behind the scenes, Nylas rewrites all HTML links with a new URL to support tracking link clicks. This action is not compatible for links with embedded login credential as Nylas manipulates the URL directly. The servers receiving this new URL don't recognize the modified link credentials.
For example, private Google Form URLs contain login credentials and are not accepted as valid links when enabling link tracking in Nylas.
Wrap <a></a> Tags
You must wrap links with <a></a> tags for them to be tracked. Most email clients automatically update items that look like links, such as 10.0.0.1, tel:5402502334, or apple.com. For links to be tracked properly, you must use HTML <a></a> tags on the content before making a request to /send.
Link Clicked Send Example
...
"to": [
{
"email": "[email protected]",
"name": "Nylas personal"
}
],
"tracking": {
"links": true,
"opens": true,
"thread_replies": true,
"payload": "Tracking enabled"
},
"subject": "email index"
... Link Clicked Response Example
{
"deltas": [
{
"date": 1471630848,
"type": "message.link_clicked",
"object": "metadata",
"object_data": {
"object": "metadata",
"id": "NYLAS_METADATA_ID",
"account_id": "EMAIL_ACCOUNT_ID",
"metadata": {
"sender_app_id": "SENDER_APP_ID",
"link_data": [
{"url": "apple.com", "count": 2},
{"url": "apple.com", "count": 0},
{"url": "nylas.com", "count": 10},
],
"payload": "hello world",
"message_id": "NYLAS_MESSAGE_ID",
"recents": [{
"id:" 0,
"ip": "0.0.0.0",
"user_agent": "chrome",
"link_index": 2
}, ...]
}
}
}
]
} Learn More
Link tracking metadata.
Recents Array
The recents field contains the last 50 events. These have IDs in order to help parse which events have already been processed. The IDs are only unique within a particular recents array, and there is a separate recents array for each message/trigger pair. For example, opening message A, clicking on a link in message A, and opening message B will all have an id of 0. Opening message A again will have an id of 1.
Errors in Message Tracking
A message with link tracking enabled that has too many links tracked in it may fail to send. If this occurs, disable link tracking to send the message.
The error message returned is:
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.
If a message with either Open or Reply tracking cannot handle the metadata object's size in the message, for example, the payload value is too big. If this occurs, disable tracking to send the message. One of the following error messages will be returned:
The message has not been sent. Please try resending with open tracking disabled.The message has not been sent. Please try resending with reply tracking disabled.
Open Tracking
When you send a message with open tracking enabled, you will be notified whenever any of the recipients open that message. Opened messages are tracked by embedding 1x1 pixel image in the email. The message.opened webhook is triggered when the image is loaded.
To enable open tracking for a message, set opens to true in the tracking attribute when sending the message through the /send endpoint.
Open Tracking Send Example
...
"to": [
{
"email": "[email protected]",
"name": "Nylas personal"
}
],
"tracking": {
"links": true,
"opens": true,
"thread_replies": true,
"payload": "Tracking enabled"
},
"subject": "email index"
... Open Tracking Response Example
{
"deltas": [
{
"date": 1471630848,
"type": "message.opened",
"object": "metadata",
"object_data": {
"object": "metadata",
"id": "NYLAS_METADATA_ID",
"account_id": "EMAIL_ACCOUNT_ID",
"metadata": {
"sender_app_id": "SENDER_APP_ID",
"count": "OPEN_COUNT",
"payload": "{myCustom: 'data'}",
"message_id": "NYLAS_MESSAGE_ID",
"recents": [{
"id:" 0,
"ip": "0.0.0.0",
"user_agent": "chrome"
}, ...]
},
}
}
]
} Learn More
Thread Replied
When you send a message with reply tracking enabled, you will be notified whenever any corresponding thread participant responds to that thread. To enable reply tracking for a thread, set thread_replies to true in the tracking attribute when sending the message through the /send endpoint.
Thread Replied Send Example
...
"to": [
{
"email": "[email protected]",
"name": "Nylas personal"
}
],
"tracking": {
"links": true,
"opens": true,
"thread_replies": true,
"payload": "Tracking enabled"
},
"subject": "email index"
... Thread Replied Response Example
{
"deltas": [
{
"date": 1471630848,
"type": "thread.replied",
"object": "metadata",
"object_data": {
"object": "metadata",
"id": "NYLAS_METADATA_ID",
"account_id": "EMAIL_ACCOUNT_ID",
"metadata": {
"sender_app_id": "SENDER_APP_ID",
"payload": "{myCustom: 'data'}",
"message_id": "NYLAS_MESSAGE_ID",
"reply_to_message_id": "NYLAS_REPLY_TO_MESSAGE_ID",
"thread_id": "NYLAS_THREAD_ID",
"from_self": true,
"timestamp": 1471630848,
},
}
}
]
} Scopes
You need to enable the email.metadata, as it relies on tracking new messages coming in. Reply tracking cannot be implemented with send-only scope.
View the Nylas Scopes for the complete collection and the Authentication Scopes section for specific dependencies.
Learn More