client.Traffic

Every method in this namespace: its signature, its parameters, what it returns and an example.

Methods

What happened to every message at the edge of the workspace: where the mail that arrived for your addresses went, and what the receiving server said about the mail you sent.

`Traffic.ListAsync`

List one page of the traffic log

emails:readPages through results

Signature

Task<Page> ListAsync(    string? domainId = null,    string? direction = null,    IEnumerable<string>? outcomes = null,    string? address = null,    string? recipient = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns 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. ListAllAsync collects every page and IterateAsync walks them lazily.

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.

Parameters

domainIdstring?: Keeps one domain, by the id Domains.ListAsync returns. A domain the key does not reach is a 404.
directionstring?: inbound for mail that arrived, outbound for mail the workspace sent or forwarded. Left out, both, as far as the key's scopes reach. Nextmail.Constants.TrafficDirections holds the values.
outcomesIEnumerable<string>?: Keeps these outcomes, such as bounced and deferred. Nextmail.Constants.TrafficOutcomes holds the values.
addressstring?: Keeps one of your addresses: the one the mail arrived for, or the one it was sent from.
recipientstring?: Keeps one recipient, matched whole: the person you wrote to on an outbound entry, the address in the envelope on an inbound one.
sinceDateTimeOffset?: Keeps entries at or after this instant.
untilDateTimeOffset?: Keeps entries before this instant. It has to be later than since.
limitint?: Page size, from 1 to 100. The server defaults to 25.
cursorstring?: The nextCursor of the previous page. Leave it out for the first page.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A Page with items, hasMore and nextCursor. Each item has direction, outcome, reason, status, detail, sender, recipient, address, domain, the ids of the email and thread it belongs to, the servers on each side, verdicts, size and createdAt.

Example

using Nextmail.Constants; var page = await client.Traffic.ListAsync(    direction: TrafficDirections.Outbound,    outcomes: [TrafficOutcomes.Bounced, TrafficOutcomes.Deferred],    since: DateTimeOffset.UtcNow.AddDays(-1)); foreach (var entry in page){    Console.WriteLine($"{entry["createdAt"]} {entry["recipient"]} {entry["outcome"]} {entry["detail"]}");}

Notes

Outbound entries need emails:read and inbound ones threads:read. A key with only one of them sees that direction alone, and asking for the other direction is a 403 insufficient_scope.
A key or an app narrowed to particular addresses or domains sees the entries of the addresses it reaches and, for a whole domain it holds, every entry of that domain, including mail for addresses that do not exist.
The sender and the reply are stored encrypted, so they cannot be searched. Filter by address, recipient, outcomes, direction, domainId and the time.
The cursor is opaque and holds where the last row sat. A cursor this list did not hand out is a 400 invalid_cursor.

Also available in

API: GET /traffic
TypeScript: traffic.list()
Python: traffic.list()
Ruby: traffic.list
PHP: traffic->list
Go: Traffic.List
Java: traffic().list
CLI: nextmail traffic list

`Traffic.ListAllAsync`

Collect the traffic log into one list

emails:readPages through results

Signature

Task<IReadOnlyList<JsonObject>> ListAllAsync(    string? domainId = null,    string? direction = null,    IEnumerable<string>? outcomes = null,    string? address = null,    string? recipient = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Walks every page of ListAsync and returns every entry that matches in one list, newest first. One request per page, with the same filters on each, so narrow it with since, domainId or outcomes before collecting a busy workspace.

Parameters

domainIdstring?: Keeps one domain, by the id Domains.ListAsync returns. A domain the key does not reach is a 404.
directionstring?: inbound for mail that arrived, outbound for mail the workspace sent or forwarded. Left out, both, as far as the key's scopes reach. Nextmail.Constants.TrafficDirections holds the values.
outcomesIEnumerable<string>?: Keeps these outcomes, such as bounced and deferred. Nextmail.Constants.TrafficOutcomes holds the values.
addressstring?: Keeps one of your addresses: the one the mail arrived for, or the one it was sent from.
recipientstring?: Keeps one recipient, matched whole: the person you wrote to on an outbound entry, the address in the envelope on an inbound one.
sinceDateTimeOffset?: Keeps entries at or after this instant.
untilDateTimeOffset?: Keeps entries before this instant. It has to be later than since.
limitint?: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

Returns

An IReadOnlyList<JsonObject> holding every matching entry.

Example

using Nextmail.Constants; var bounced = await client.Traffic.ListAllAsync(    outcomes: [TrafficOutcomes.Bounced],    since: new DateTimeOffset(2026, 10, 1, 0, 0, 0, TimeSpan.Zero),    limit: 100); Console.WriteLine(bounced.Select(entry => entry["recipient"]?.ToString()).Distinct().Count());

Notes

If any page fails, the exception is thrown and the entries already fetched are discarded.
Outbound entries need emails:read and inbound ones threads:read, as on ListAsync.

Also available in

API: GET /traffic
TypeScript: traffic.listAll()
Python: traffic.list_all()
Ruby: traffic.list_all
PHP: traffic->listAll
Go: Traffic.ListAll
Java: traffic().listAll

`Traffic.IterateAsync`

Stream the traffic log one entry at a time

emails:readPages through results

Signature

IAsyncEnumerable<JsonObject> IterateAsync(    string? domainId = null,    string? direction = null,    IEnumerable<string>? outcomes = null,    string? address = null,    string? recipient = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an async stream that yields one entry at a time, newest first, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.

Parameters

domainIdstring?: Keeps one domain, by the id Domains.ListAsync returns. A domain the key does not reach is a 404.
directionstring?: inbound for mail that arrived, outbound for mail the workspace sent or forwarded. Left out, both, as far as the key's scopes reach. Nextmail.Constants.TrafficDirections holds the values.
outcomesIEnumerable<string>?: Keeps these outcomes, such as bounced and deferred. Nextmail.Constants.TrafficOutcomes holds the values.
addressstring?: Keeps one of your addresses: the one the mail arrived for, or the one it was sent from.
recipientstring?: Keeps one recipient, matched whole: the person you wrote to on an outbound entry, the address in the envelope on an inbound one.
sinceDateTimeOffset?: Keeps entries at or after this instant.
untilDateTimeOffset?: Keeps entries before this instant. It has to be later than since.
limitint?: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

Returns

An IAsyncEnumerable<JsonObject> yielding one entry per step.

Example

using Nextmail.Constants; await foreach (var entry in client.Traffic.IterateAsync(direction: TrafficDirections.Inbound, outcomes: [TrafficOutcomes.Refused, TrafficOutcomes.Dropped])){    Console.WriteLine($"{entry["recipient"]} {entry["reason"]} {entry["detail"]}");}

Notes

The stream is lazy, so an abandoned loop costs only the pages you consumed.
Outbound entries need emails:read and inbound ones threads:read, as on ListAsync.

Also available in

API: GET /traffic
TypeScript: traffic.iterate()
Python: traffic.iterate()
Ruby: traffic.iterate
PHP: traffic->iterate
Go: Traffic.Iterate
Java: traffic().iterate

client.Traffic

Methods

Parameters

Returns

Example

Notes

Also available in

Parameters

Returns

Example

Notes

Also available in

Parameters

Returns

Example

Notes

Also available in

Talk it through,then decide.

Talk it through,
then decide.