--- title: "openemail tracking" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/tracking" area: "CLI" category: "Reference" --- # openemail tracking Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail tracking list` List one page of tracked messages in a time window ```bash openemail tracking list [flags] ``` Returns one page of the messages the workspace tracked and sent in the window, newest first, each as a full engagement report with its `recipients` and `links`. It covers the whole mailbox, not only mail sent through this API: messages from the composer, the MCP tools and the assistant appear too, with `sendId` null where no send record exists. A report built off `emails.list` would describe the API rather than the mailbox. Messages that carried no pixel and no rewritten link are absent entirely and never appear as a zero. `opened: false` therefore means tracked and not opened, and `clicked` narrows the same way. Both filters work on counted opens and clicks, so a message fetched only by Apple Mail Privacy Protection or a link scanner still counts as unopened. The window defaults to 30 days. `minutes` wins over `days` when both are set, and the start of the window is floored to the `grain` in UTC, so `days: 7` covers today plus the six whole days before it. Paging is keyset: `nextCursor` is the `tmsg_` id of the last report on the page, and passing it back as `cursor` with the same filters continues strictly after it, so every tracked message in the window is reachable. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `emails:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--opened`: Omit for both. `true` keeps opened messages and `false` keeps tracked messages nobody opened. - `--clicked`: Omit for both. `true` keeps messages with a counted click and `false` keeps those without. - `--days ` (default `30`): Window length in days, a whole number from 1 to 365, defaulting to 30. - `--minutes `: Window length in minutes, from 1 to 527040. Takes precedence over `days`. - `--grain ` (default `"day"`): `minute`, `hour` or `day`, defaulting to `day`. It only floors the window start so this list matches `getStats` read at the same grain, and shapes nothing in the response. - `--limit ` (default `50`): Reports per page, from 1 to 200, defaulting to 50. - `--cursor `: The `nextCursor` from the previous page, a `tmsg_` id. One that names no tracked message in the workspace is a 400 `invalid_cursor`. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail tracking list ``` With optional flags ```bash openemail tracking list --no-opened --days 7 --limit 200 ``` Walk every page and stop after 100 items ```bash openemail tracking list --all --max 100 ``` One JSON object per line when piped ```bash openemail tracking list --all > tracking.ndjson ``` Also available in: API [`GET /tracking`](https://openemail.uk/docs/api/reference/tracking#get-tracking); SDK [`tracking.list()`](https://openemail.uk/docs/sdk/reference/tracking#list). ### `openemail tracking get-stats` Summarise engagement across a time window ```bash openemail tracking get-stats [flags] ``` Returns the numbers behind an engagement panel in one request: how many messages were tracked, opened and clicked, the open and click rates, hit totals, a time series, the top links, mail clients and countries. It covers every tracked message sent from the mailbox in the window, whichever surface sent it. Rates and totals count different things, and mixing them is how open rates above 100% get published. `opened` and `clicked` count distinct messages. `totalOpens` and `totalClicks` count hits. `openRate` is a percentage of `trackedForOpens`, the messages that actually carried a pixel, and `clickRate` is a percentage of `trackedForClicks`, the messages that had a link to rewrite, which is usually far fewer than `tracked` because most replies contain no links. `byDay` is sparse: a bucket in which nothing was sent has no entry, so a chart must fill the gaps. `grain` sets the bucket width and the key shape, `YYYY-MM-DD`, `YYYY-MM-DDTHH` or `YYYY-MM-DDTHH:MM`, and `--offset-minutes` shifts bucket boundaries so days break where the reader's day does. The window starts at the beginning of the oldest bucket, so that bucket is whole, and ends now, so the newest is partial. - Scopes: `emails:read`. - Needs a sign-in. **Flags** - `--days ` (default `30`): Window length in days, from 1 to 365, defaulting to 30. - `--minutes `: Window length in minutes, from 1 to 527040. Takes precedence over `days`, and only useful below a day with a finer `grain`. - `--grain ` (default `"day"`): Bucket width for `byDay`: `minute`, `hour` or `day`, defaulting to `day`. - `--offset-minutes ` (default `0`): Minutes east of UTC to bucket in, from -840 to 840, defaulting to 0. Pass `-new Date().getTimezoneOffset()` for the local zone. **Examples** ```bash openemail tracking get-stats ``` With optional flags ```bash openemail tracking get-stats --days 7 --grain day ``` Print the raw JSON ```bash openemail tracking get-stats --json ``` Also available in: API [`GET /tracking/stats`](https://openemail.uk/docs/api/reference/tracking#get-tracking-stats); SDK [`tracking.getStats()`](https://openemail.uk/docs/sdk/reference/tracking#getStats). ### `openemail tracking get` Read one message's engagement report ```bash openemail tracking get [flags] ``` Returns the whole report for one tracked message: totals, one entry per tracked copy under `recipients`, and every rewritten link with its clicks under `links`. It accepts either identifier a caller may hold. A `msg_` id is looked up as the send it went out as, and anything else is treated as a `tmsg_` tracking id, which is what `tracking.list` and webhook payloads carry for mail sent outside this API. `openCount` and `clickCount` are counted readings: opens that looked like a person, with repeat fetches within thirty seconds collapsed. `openCountRaw` and `clickCountRaw` include every hit, machine fetches such as Apple Mail Privacy Protection and corporate scanners among them. Gmail's image proxy is a real person displaying the message and is counted, but only once, because later views are served from its cache. `recipients` is one entry per tracked copy, which is not always one entry per person. When one body went to the whole list, or the bytes could not vary per recipient, the shared copy has `email` null and `attributed` false. Branch on `attributed` and on the message-level `attributable` before saying that a named person has or has not read anything. - Scopes: `emails:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): A `tmsg_` tracking id or the `msg_` send id the message went out as. **Examples** ```bash openemail tracking get tmsg_8b2e4d71c09f3a65e1d7b402 ``` Print the raw JSON ```bash openemail tracking get tmsg_8b2e4d71c09f3a65e1d7b402 --json ``` Also available in: API [`GET /tracking/{id}`](https://openemail.uk/docs/api/reference/tracking#get-tracking-id); SDK [`tracking.get()`](https://openemail.uk/docs/sdk/reference/tracking#get). ### `openemail tracking list-opens` List the individual opens behind a message's open count ```bash openemail tracking list-opens [flags] ``` Returns one page of the raw open hits for one tracked message, newest first. Each hit says which copy was fetched, how it was classified, whether it moved the numbers, and what the User-Agent and the edge could tell about the client, device and location. `kind` is `human` for something that looked like a person reading, `proxy` for an image proxy such as Gmail's, which is a genuine reading by a reader the tracker cannot see, and `machine` for a scanner or Apple Mail Privacy Protection, which fetches on delivery and only proves the message arrived. By default only counted hits come back. `includeMachine: true` adds the hits that did not count, which is every `machine` hit plus repeat fetches within thirty seconds of a counted one on the same copy, so it filters on `counted` rather than on `kind`. A `msg_` send id is resolved first, and one that names no tracked message is a 404 rather than an empty list, since an empty list reads as nobody having opened it. A `tmsg_` id is taken as given without a lookup, so one that never existed or belongs to another workspace comes back as an empty list. Only read an empty result as an answer about readers when the id came from this API. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `emails:read`. - Needs a sign-in. **Arguments** - `` (required): A `tmsg_` tracking id or the `msg_` send id the message went out as. **Flags** - `--include-machine` (default `false`): Defaults to false. True also returns hits with `counted` false, machine fetches and collapsed repeats alike. - `--limit ` (default `50`): Hits per page, from 1 to 200, defaulting to 50. - `--cursor `: The `nextCursor` from the previous page, an `opn_` id. Anything else, or one from another message's log, is a 400 `invalid_cursor`. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash openemail tracking list-opens msg_3f9a1c07d2b84e6a9c5b1f20 ``` With optional flags ```bash openemail tracking list-opens msg_3f9a1c07d2b84e6a9c5b1f20 --include-machine --limit 200 ``` Walk every page and stop after 100 items ```bash openemail tracking list-opens msg_3f9a1c07d2b84e6a9c5b1f20 --all --max 100 ``` One JSON object per line when piped ```bash openemail tracking list-opens msg_3f9a1c07d2b84e6a9c5b1f20 --all > tracking.ndjson ``` Also available in: API [`GET /tracking/{id}/opens`](https://openemail.uk/docs/api/reference/tracking#get-tracking-id-opens); SDK [`tracking.listOpens()`](https://openemail.uk/docs/sdk/reference/tracking#listOpens). ### `openemail tracking list-clicks` List the individual link clicks on a message ```bash openemail tracking list-clicks [flags] ``` Returns one page of the raw click hits for one tracked message, newest first. Each hit has the same classification and client detail as an open, plus `linkId` and `url` naming the link that was followed, where `url` is the original destination rather than the redirect. A click is stronger evidence of reading than an open. Mail clients block images far more often than readers leave links unfollowed, so a message with clicks and no opens was certainly read. Link scanners that follow every URL on delivery are classified as `machine` and excluded from the default result, and `includeMachine: true` brings them back along with repeat hits collapsed by the thirty second window. Only links in the new part of the body were rewritten, so nothing here can be a click on quoted history under a reply. The id rules match `listOpens`: a `msg_` id that names no tracked message is a 404, while a `tmsg_` id is used without a lookup and an unknown one returns an empty list. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `emails:read`. - Needs a sign-in. **Arguments** - `` (required): A `tmsg_` tracking id or the `msg_` send id the message went out as. **Flags** - `--include-machine` (default `false`): Defaults to false. True also returns hits with `counted` false, scanner clicks and collapsed repeats alike. - `--limit ` (default `50`): Hits per page, from 1 to 200, defaulting to 50. - `--cursor `: The `nextCursor` from the previous page, a `clk_` id. Anything else, or one from another message's log, is a 400 `invalid_cursor`. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash openemail tracking list-clicks tmsg_8b2e4d71c09f3a65e1d7b402 ``` With optional flags ```bash openemail tracking list-clicks tmsg_8b2e4d71c09f3a65e1d7b402 --limit 200 ``` Walk every page and stop after 100 items ```bash openemail tracking list-clicks tmsg_8b2e4d71c09f3a65e1d7b402 --all --max 100 ``` One JSON object per line when piped ```bash openemail tracking list-clicks tmsg_8b2e4d71c09f3a65e1d7b402 --all > tracking.ndjson ``` Also available in: API [`GET /tracking/{id}/clicks`](https://openemail.uk/docs/api/reference/tracking#get-tracking-id-clicks); SDK [`tracking.listClicks()`](https://openemail.uk/docs/sdk/reference/tracking#listClicks).