---
title: "Tracking"
description: "What became of the mail this mailbox sent."
url: "https://nextmail.sh/docs/mcp/tools/tracking"
area: "MCP server"
category: "Tools"
---

# Tracking

What became of the mail this mailbox sent.

## Tracking tools

| Tool | What it does |
| --- | --- |
| getEmailTracking | Whether one message was opened, by whom, how often, and which links were followed. Takes a thread id, an RFC Message-ID or a tracking id. |
| getFileDownloads | The files sent as download links on a thread: filename, size, how many times each was downloaded, when the last download was, and whether the link is still live. Takes a thread id. |
| listTrackedEmails | Messages sent with tracking on, newest first, a page at a time, filtered by whether they were opened or clicked. |
| getEngagementStats | Open and click rates over a window, with the top links, the clients, and how many fetches were filtered out. |

> These see only mail sent with tracking on, which is off unless it was turned on for the address the mail was sent from, for the catch-all that caught that address, or for that one message. `getEmailTracking` says "nothing tracked for that message" rather than reporting zero opens. The phrases "nobody opened it" and "we were not recording" are different answers, and a tool that gives the first for the second lies about the recipient.

> `getFileDownloads` counts people, not scanners or link previewers, and it never names who downloaded a file, because a download link is one URL for every recipient of the message. Files attached inside a message are not listed, since nothing is recorded when those are opened, so an empty answer means "no download links on this thread" and not "nobody opened the attachment".

> Every rate is over TRACKED messages, never over all sent mail. A mailbox that tracks one message in ten has an open rate for those ten; dividing by everything it ever sent produces a number that falls each time somebody sends an untracked reply, which is not a fact about how their mail is read.

> The counts leave out scanners and privacy proxies, and each report states how many were excluded. Opens seen through Gmail’s image proxy do count, because a person displayed the message, but the proxy caches, so a count through Gmail is a floor rather than a total.

## Reference

### `getEmailTracking`

Whether a message this mailbox sent has been opened, by whom, how many times, and which links were followed. Give it a thread id, an RFC Message-ID, or a tracking id. Returns nothing for a message that was sent without tracking on.

- Scopes: `emails:read`.
- The app's assistant runs it without asking.
- Toolkit: `tracking`.

**Inputs**

- `threadId` (`string`)
- `messageId` (`string`)
- `trackingId` (`string`)

Also available in: API [`GET /emails/{id}/tracking`](https://nextmail.sh/docs/api/reference/tracking#get-emails-id-tracking), [`GET /tracking/{id}/clicks`](https://nextmail.sh/docs/api/reference/tracking#get-tracking-id-clicks), [`GET /tracking/{id}/opens`](https://nextmail.sh/docs/api/reference/tracking#get-tracking-id-opens); TypeScript [`nextmail.emails.getTracking()`](https://nextmail.sh/docs/sdk/reference/emails#getTracking), [`nextmail.tracking.listClicks()`](https://nextmail.sh/docs/sdk/reference/tracking#listClicks), [`nextmail.tracking.listAllClicks()`](https://nextmail.sh/docs/sdk/reference/tracking#listAllClicks), [`nextmail.tracking.iterateClicks()`](https://nextmail.sh/docs/sdk/reference/tracking#iterateClicks), [`nextmail.tracking.listOpens()`](https://nextmail.sh/docs/sdk/reference/tracking#listOpens), [`nextmail.tracking.listAllOpens()`](https://nextmail.sh/docs/sdk/reference/tracking#listAllOpens), [`nextmail.tracking.iterateOpens()`](https://nextmail.sh/docs/sdk/reference/tracking#iterateOpens); Python [`emails.get_tracking()`](https://nextmail.sh/docs/python/reference/emails#getTracking), [`tracking.list_clicks()`](https://nextmail.sh/docs/python/reference/tracking#listClicks), [`tracking.list_all_clicks()`](https://nextmail.sh/docs/python/reference/tracking#listAllClicks), [`tracking.iterate_clicks()`](https://nextmail.sh/docs/python/reference/tracking#iterateClicks), [`tracking.list_opens()`](https://nextmail.sh/docs/python/reference/tracking#listOpens), [`tracking.list_all_opens()`](https://nextmail.sh/docs/python/reference/tracking#listAllOpens), [`tracking.iterate_opens()`](https://nextmail.sh/docs/python/reference/tracking#iterateOpens); Ruby [`emails.get_tracking`](https://nextmail.sh/docs/ruby/reference/emails#getTracking), [`tracking.list_clicks`](https://nextmail.sh/docs/ruby/reference/tracking#listClicks), [`tracking.list_all_clicks`](https://nextmail.sh/docs/ruby/reference/tracking#listAllClicks), [`tracking.iterate_clicks`](https://nextmail.sh/docs/ruby/reference/tracking#iterateClicks), [`tracking.list_opens`](https://nextmail.sh/docs/ruby/reference/tracking#listOpens), [`tracking.list_all_opens`](https://nextmail.sh/docs/ruby/reference/tracking#listAllOpens), [`tracking.iterate_opens`](https://nextmail.sh/docs/ruby/reference/tracking#iterateOpens); PHP [`emails->getTracking`](https://nextmail.sh/docs/php/reference/emails#getTracking), [`tracking->listClicks`](https://nextmail.sh/docs/php/reference/tracking#listClicks), [`tracking->listAllClicks`](https://nextmail.sh/docs/php/reference/tracking#listAllClicks), [`tracking->iterateClicks`](https://nextmail.sh/docs/php/reference/tracking#iterateClicks), [`tracking->listOpens`](https://nextmail.sh/docs/php/reference/tracking#listOpens), [`tracking->listAllOpens`](https://nextmail.sh/docs/php/reference/tracking#listAllOpens), [`tracking->iterateOpens`](https://nextmail.sh/docs/php/reference/tracking#iterateOpens); Go [`Emails.GetTracking`](https://nextmail.sh/docs/go/reference/emails#getTracking), [`Tracking.ListClicks`](https://nextmail.sh/docs/go/reference/tracking#listClicks), [`Tracking.ListAllClicks`](https://nextmail.sh/docs/go/reference/tracking#listAllClicks), [`Tracking.IterateClicks`](https://nextmail.sh/docs/go/reference/tracking#iterateClicks), [`Tracking.ListOpens`](https://nextmail.sh/docs/go/reference/tracking#listOpens), [`Tracking.ListAllOpens`](https://nextmail.sh/docs/go/reference/tracking#listAllOpens), [`Tracking.IterateOpens`](https://nextmail.sh/docs/go/reference/tracking#iterateOpens); Java [`emails().getTracking`](https://nextmail.sh/docs/java/reference/emails#getTracking), [`tracking().listClicks`](https://nextmail.sh/docs/java/reference/tracking#listClicks), [`tracking().listAllClicks`](https://nextmail.sh/docs/java/reference/tracking#listAllClicks), [`tracking().iterateClicks`](https://nextmail.sh/docs/java/reference/tracking#iterateClicks), [`tracking().listOpens`](https://nextmail.sh/docs/java/reference/tracking#listOpens), [`tracking().listAllOpens`](https://nextmail.sh/docs/java/reference/tracking#listAllOpens), [`tracking().iterateOpens`](https://nextmail.sh/docs/java/reference/tracking#iterateOpens); C# [`Emails.GetTrackingAsync`](https://nextmail.sh/docs/csharp/reference/emails#getTracking), [`Tracking.ListClicksAsync`](https://nextmail.sh/docs/csharp/reference/tracking#listClicks), [`Tracking.ListAllClicksAsync`](https://nextmail.sh/docs/csharp/reference/tracking#listAllClicks), [`Tracking.IterateClicksAsync`](https://nextmail.sh/docs/csharp/reference/tracking#iterateClicks), [`Tracking.ListOpensAsync`](https://nextmail.sh/docs/csharp/reference/tracking#listOpens), [`Tracking.ListAllOpensAsync`](https://nextmail.sh/docs/csharp/reference/tracking#listAllOpens), [`Tracking.IterateOpensAsync`](https://nextmail.sh/docs/csharp/reference/tracking#iterateOpens).

### `getFileDownloads`

Which files this mailbox sent as download links on a thread, and whether anyone has fetched them: filename, size, download count, when the last download was, and whether the link is still live or revoked. Give it a thread id. Downloads count people, not scanners or link previewers, and a download cannot be tied to one recipient because every recipient gets the same link. Files sent inside the message rather than as links are not listed, because nothing is recorded when those are opened.

- Scopes: `emails:read`.
- The app's assistant runs it without asking.
- Toolkit: `tracking`.

**Inputs**

- `threadId` (`string`, required)

Also available in: API [`GET /files/{id}/links`](https://nextmail.sh/docs/api/reference/files#get-files-id-links); TypeScript [`nextmail.files.listLinks()`](https://nextmail.sh/docs/sdk/reference/files#listLinks), [`nextmail.files.listAllLinks()`](https://nextmail.sh/docs/sdk/reference/files#listAllLinks), [`nextmail.files.iterateLinks()`](https://nextmail.sh/docs/sdk/reference/files#iterateLinks); Python [`files.list_links()`](https://nextmail.sh/docs/python/reference/files#listLinks), [`files.list_all_links()`](https://nextmail.sh/docs/python/reference/files#listAllLinks), [`files.iterate_links()`](https://nextmail.sh/docs/python/reference/files#iterateLinks); Ruby [`files.list_links`](https://nextmail.sh/docs/ruby/reference/files#listLinks), [`files.list_all_links`](https://nextmail.sh/docs/ruby/reference/files#listAllLinks), [`files.iterate_links`](https://nextmail.sh/docs/ruby/reference/files#iterateLinks); PHP [`files->listLinks`](https://nextmail.sh/docs/php/reference/files#listLinks), [`files->listAllLinks`](https://nextmail.sh/docs/php/reference/files#listAllLinks), [`files->iterateLinks`](https://nextmail.sh/docs/php/reference/files#iterateLinks); Go [`Files.ListLinks`](https://nextmail.sh/docs/go/reference/files#listLinks), [`Files.ListAllLinks`](https://nextmail.sh/docs/go/reference/files#listAllLinks), [`Files.IterateLinks`](https://nextmail.sh/docs/go/reference/files#iterateLinks); Java [`files().listLinks`](https://nextmail.sh/docs/java/reference/files#listLinks), [`files().listAllLinks`](https://nextmail.sh/docs/java/reference/files#listAllLinks), [`files().iterateLinks`](https://nextmail.sh/docs/java/reference/files#iterateLinks); C# [`Files.ListLinksAsync`](https://nextmail.sh/docs/csharp/reference/files#listLinks), [`Files.ListAllLinksAsync`](https://nextmail.sh/docs/csharp/reference/files#listAllLinks), [`Files.IterateLinksAsync`](https://nextmail.sh/docs/csharp/reference/files#iterateLinks).

### `listTrackedEmails`

Messages this mailbox sent with tracking on, newest first, one page at a time. Filter by whether they were opened or clicked to answer questions like "what have I sent that nobody has read". address keeps only what one address sent. When more follow, the last line gives a cursor: call again with it, and the same filters, for the next page, until no cursor is given.

- Scopes: `emails:read`.
- The app's assistant runs it without asking.
- Toolkit: `tracking`.

**Inputs**

- `days` (`integer`, at least 1, at most 365, default `30`)
- `opened` (`boolean`)
- `clicked` (`boolean`)
- `address` (`string`, 3 to 320 characters)
- `limit` (`integer`, at least 1, at most 200, default `20`)
- `cursor` (`string`)

Also available in: API [`GET /tracking`](https://nextmail.sh/docs/api/reference/tracking#get-tracking), [`GET /tracking/{id}`](https://nextmail.sh/docs/api/reference/tracking#get-tracking-id); TypeScript [`nextmail.tracking.list()`](https://nextmail.sh/docs/sdk/reference/tracking#list), [`nextmail.tracking.listAll()`](https://nextmail.sh/docs/sdk/reference/tracking#listAll), [`nextmail.tracking.iterate()`](https://nextmail.sh/docs/sdk/reference/tracking#iterate), [`nextmail.tracking.get()`](https://nextmail.sh/docs/sdk/reference/tracking#get); Python [`tracking.list()`](https://nextmail.sh/docs/python/reference/tracking#list), [`tracking.list_all()`](https://nextmail.sh/docs/python/reference/tracking#listAll), [`tracking.iterate()`](https://nextmail.sh/docs/python/reference/tracking#iterate), [`tracking.get()`](https://nextmail.sh/docs/python/reference/tracking#get); Ruby [`tracking.list`](https://nextmail.sh/docs/ruby/reference/tracking#list), [`tracking.list_all`](https://nextmail.sh/docs/ruby/reference/tracking#listAll), [`tracking.iterate`](https://nextmail.sh/docs/ruby/reference/tracking#iterate), [`tracking.get`](https://nextmail.sh/docs/ruby/reference/tracking#get); PHP [`tracking->list`](https://nextmail.sh/docs/php/reference/tracking#list), [`tracking->listAll`](https://nextmail.sh/docs/php/reference/tracking#listAll), [`tracking->iterate`](https://nextmail.sh/docs/php/reference/tracking#iterate), [`tracking->get`](https://nextmail.sh/docs/php/reference/tracking#get); Go [`Tracking.List`](https://nextmail.sh/docs/go/reference/tracking#list), [`Tracking.ListAll`](https://nextmail.sh/docs/go/reference/tracking#listAll), [`Tracking.Iterate`](https://nextmail.sh/docs/go/reference/tracking#iterate), [`Tracking.Get`](https://nextmail.sh/docs/go/reference/tracking#get); Java [`tracking().list`](https://nextmail.sh/docs/java/reference/tracking#list), [`tracking().listAll`](https://nextmail.sh/docs/java/reference/tracking#listAll), [`tracking().iterate`](https://nextmail.sh/docs/java/reference/tracking#iterate), [`tracking().get`](https://nextmail.sh/docs/java/reference/tracking#get); C# [`Tracking.ListAsync`](https://nextmail.sh/docs/csharp/reference/tracking#list), [`Tracking.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/tracking#listAll), [`Tracking.IterateAsync`](https://nextmail.sh/docs/csharp/reference/tracking#iterate), [`Tracking.GetAsync`](https://nextmail.sh/docs/csharp/reference/tracking#get).

### `getEngagementStats`

Open and click rates for mail this mailbox sent, over a window. Rates are over TRACKED messages only, never over all sent mail. address counts only what one address sent.

- Scopes: `emails:read`.
- The app's assistant runs it without asking.
- Toolkit: `tracking`.

**Inputs**

- `days` (`number`, default `30`)
- `address` (`string`, 3 to 320 characters)

Also available in: API [`GET /tracking/stats`](https://nextmail.sh/docs/api/reference/tracking#get-tracking-stats); TypeScript [`nextmail.tracking.getStats()`](https://nextmail.sh/docs/sdk/reference/tracking#getStats); Python [`tracking.get_stats()`](https://nextmail.sh/docs/python/reference/tracking#getStats); Ruby [`tracking.get_stats`](https://nextmail.sh/docs/ruby/reference/tracking#getStats); PHP [`tracking->getStats`](https://nextmail.sh/docs/php/reference/tracking#getStats); Go [`Tracking.GetStats`](https://nextmail.sh/docs/go/reference/tracking#getStats); Java [`tracking().getStats`](https://nextmail.sh/docs/java/reference/tracking#getStats); C# [`Tracking.GetStatsAsync`](https://nextmail.sh/docs/csharp/reference/tracking#getStats).