Track email messages in Nylas v2
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:
- Someone clicks a link in the email message .
- Someone opens the email message.
- 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 webhook triggers for each of the available tracking options to be notified when a webhook is generated.
When a user acts on an email message that you enabled tracking for (for example, opening the message), Nylas sends a POST to your webhook endpoint 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 webhook schemas.
Scopes for message tracking
Before you start using message tracking, you must request the email.metadata 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 the tracking JSON object in your Send Message or Create Draft request.
...
"tracking": {
"opens": true, // Enable message open tracking.
"links": true, // Enable link clicked tracking.
"thread_replies": true, // Enable thread replied tracking.
"payload": "Use this string to describe the message you're enabling tracking for. It's included in webhook notifications about tracked events."
}
... 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 webhook 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:
httpsmailtotel
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 code samples show how to enable link clicked tracking for an email message, and the type of JSON notification you can expect.
...
"to": [{
"email": "test@example.com",
"name": "Reine Abadie"
}],
"tracking": {
"links": true,
"opens": false,
"thread_replies": false,
"payload": "Link tracking enabled."
},
"subject": "Email Index"
... "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": "example1.com", "count": 2},
{"url": "example1.com", "count": 0},
{"url": "example2.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
}
...]
}
}
}] For more information about metadata in link clicked tracking responses, see the Link Clicked webhook 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 an 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 particular recents array, and each message/trigger pair has its own recents array.
The message.link_clicked webhook 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 webhook 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 prevents 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 webhook 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.
...
"to": [{
"email": "test@example.com",
"name": "Laura Mooney"
}],
"tracking": {
"links": false,
"opens": true,
"thread_replies": false,
"payload": "Open tracking enabled"
},
"subject": "Email Index"
... {
"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"
}
...]
}
}
}]
} The Recents array in message open tracking
Like link clicked tracking, the webhook 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 webhook notification. Each entry includes an id 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.
...
"to": [{
"email": "test@example.com",
"name": "Matt Clarkson"
}],
"tracking": {
"links": false,
"opens": false,
"thread_replies": true,
"payload": "Reply tracking enabled"
},
"subject": "Email Index"
... {
"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,
}
}
}]
} 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.