---
title: "nextmail traffic"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://nextmail.sh/docs/cli/reference/traffic"
area: "CLI"
category: "Reference"
---

# nextmail traffic

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `nextmail traffic list`

List one page of the traffic log

```bash
nextmail traffic list [flags]
```

Resolves one page of the traffic log, newest first: one entry for each message and recipient at each step it took in or out of the workspace.

Inbound, each recipient of a message that arrived gets an entry saying where it went: `filed` in the inbox, `spam`, `routed` to a webhook, `forwarded` without a copy kept, `refused` with a bounce back to the sender, or `dropped` without one, and `reason` says why mail was refused or dropped. Outbound, each recipient of a message you sent or forwarded gets an entry for each answer from the receiving server: `delivered`, `deferred` while it keeps trying, `bounced`, `complained`, `suppressed` when it was never tried, `rejected` when it was refused before it left, and `failed` for a forward that could not be relayed.

An entry never changes once it is written, and the same step keeps the same id. Entries are kept for 30 days. `detail` holds the reply of the receiving server and `remoteMta`, `reportingMta` and `sendingIp` the servers on each side, and inbound entries carry the SPF, DKIM, DMARC, spam and virus `verdicts` the message arrived with.

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 <n>` stops after that many items.

- Scopes: `emails:read`.
- Needs a sign-in.
- Aliases: `ls`.

**Flags**

- `--domain-id <value>`: Keeps one domain, by the id `domains.list` returns. A domain the key does not reach is a 404.
- `--direction <value>`: `inbound` for mail that arrived, `outbound` for mail the workspace sent or forwarded. Left out, both, as far as the key's scopes reach.
- `--outcomes <a,b>` (repeatable): Keeps these outcomes, such as `['bounced', 'deferred']`.
- `--address <value>`: Keeps one of your addresses: the one the mail arrived for, or the one it was sent from.
- `--recipient <value>`: Keeps one recipient, matched whole: the person you wrote to on an outbound entry, the address in the envelope on an inbound one.
- `--since <when>`: Keeps entries at or after this instant: a `Date` or an ISO 8601 string.
- `--until <when>`: Keeps entries before this instant. It must be later than `since`.
- `--limit <n>` (default `25`): Page size, from 1 to 100. The server defaults to 25.
- `--cursor <value>`: The `nextCursor` of the previous page. Leave it out for the first page.
- `--all`: Fetch every page and stream the items as they arrive.
- `--max <n>`: Stop after this many items. Implies `--all`.
- `--ndjson`: Print every item as one JSON object per line. Implies `--all`

**Examples**

```bash
nextmail traffic list
```

With optional flags

```bash
nextmail traffic list --direction outbound --outcomes bounced,deferred
```

Walk every page and stop after 100 items

```bash
nextmail traffic list --all --max 100
```

One JSON object per line when piped

```bash
nextmail traffic list --all > traffic.ndjson
```

Also available in: API [`GET /traffic`](https://nextmail.sh/docs/api/reference/traffic#get-traffic); TypeScript [`traffic.list()`](https://nextmail.sh/docs/sdk/reference/traffic#list); Python [`traffic.list()`](https://nextmail.sh/docs/python/reference/traffic#list); Ruby [`traffic.list`](https://nextmail.sh/docs/ruby/reference/traffic#list); PHP [`traffic->list`](https://nextmail.sh/docs/php/reference/traffic#list); Go [`Traffic.List`](https://nextmail.sh/docs/go/reference/traffic#list); Java [`traffic().list`](https://nextmail.sh/docs/java/reference/traffic#list); C# [`Traffic.ListAsync`](https://nextmail.sh/docs/csharp/reference/traffic#list).