---
title: "Analytics"
description: "How mail arrives, and what became of the mail sent."
url: "https://nextmail.sh/docs/mcp/tools/analytics"
area: "MCP server"
category: "Tools"
---

# Analytics

How mail arrives, and what became of the mail sent.

## Analytics tools

| Tool | What it does |
| --- | --- |
| getMailboxInsights | How mail arrives over a window, as the Analytics page shows it: per day and per hour, by address and by sender, what waits on a reply, and the folders. |
| getSendingAnalytics | What became of the mail the workspace sent over a window, as the Analytics page shows it: delivered, failed, bounced and complained about, per day, for one sender, recipient or tag if you like. |
| getSendingStreams | The two lanes mail travels in, app mail and broadcasts, each with its state and its bounce and complaint numbers for the last 7 days. |
| resumeSendingStream | Resume the broadcast lane after it paused itself for too many bounces or complaints. Only the workspace owner can, and in the app’s chat it always asks first. |
| listDedicatedIps | The dedicated sending IPs of the workspace, with how far each one has warmed up. |
| getDedicatedIp | One dedicated IP of the workspace, with its status and warm-up. |

> Reading how mail arrives needs “Read threads and messages” (`threads:read`), and reading what became of sent mail needs “Read sent messages and their delivery status” (`emails:read`). A client limited to some addresses counts only the mail that arrived at them or was sent from them, and `address` narrows either to one address.

## Reference

### `getMailboxInsights`

How mail arrives, as the Analytics page shows it: how many conversations came in over a window and on which days, the busiest hours, the addresses they arrived at, the senders who wrote most, how many wait on a reply, and the folders. from and to are ISO 8601 instants and default to the last 30 days. offsetMinutes is the reader’s minutes east of UTC, so days break where theirs do. address narrows it to one address.

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

**Inputs**

- `from` (`string`, format `date-time`)
- `to` (`string`, format `date-time`)
- `grain` (`string`, one of `"minute"`, `"hour"`, `"day"`)
- `offsetMinutes` (`integer`, at least -840, at most 840)
- `address` (`string`, 3 to 320 characters)

Also available in: API [`GET /analytics/mailbox`](https://nextmail.sh/docs/api/reference/analytics#get-analytics-mailbox); TypeScript [`nextmail.analytics.mailbox()`](https://nextmail.sh/docs/sdk/reference/analytics#mailbox); Python [`analytics.mailbox()`](https://nextmail.sh/docs/python/reference/analytics#mailbox); Ruby [`analytics.mailbox`](https://nextmail.sh/docs/ruby/reference/analytics#mailbox); PHP [`analytics->mailbox`](https://nextmail.sh/docs/php/reference/analytics#mailbox); Go [`Analytics.Mailbox`](https://nextmail.sh/docs/go/reference/analytics#mailbox); Java [`analytics().mailbox`](https://nextmail.sh/docs/java/reference/analytics#mailbox); C# [`Analytics.MailboxAsync`](https://nextmail.sh/docs/csharp/reference/analytics#mailbox).

### `getSendingAnalytics`

What became of the mail this workspace sent, as the Analytics page shows it: how many went out over a window and how many were delivered, failed, bounced or complained about, per day, with the statuses, where they came from, the addresses they went out as and the addresses suppressed. days defaults to 30, minutes wins over days, and since and until, ISO 8601 instants at most 365 days apart, set the window outright. address narrows it to the mail sent from one address, recipient to the mail that went to one address, counting only its delivery there, and tag to the mail sent with a tag: name for any value, name:value for one.

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

**Inputs**

- `days` (`integer`, at least 1, at most 365)
- `minutes` (`integer`, at least 1, at most 525600)
- `since` (`string`, format `date-time`)
- `until` (`string`, format `date-time`)
- `grain` (`string`, one of `"minute"`, `"hour"`, `"day"`)
- `offsetMinutes` (`integer`, at least -840, at most 840)
- `address` (`string`, 3 to 320 characters)
- `recipient` (`string`, up to 320 characters, format `email`)
- `tag` (`string`, 1 to 330 characters)

Also available in: API [`GET /analytics/sending`](https://nextmail.sh/docs/api/reference/analytics#get-analytics-sending); TypeScript [`nextmail.analytics.sending()`](https://nextmail.sh/docs/sdk/reference/analytics#sending); Python [`analytics.sending()`](https://nextmail.sh/docs/python/reference/analytics#sending); Ruby [`analytics.sending`](https://nextmail.sh/docs/ruby/reference/analytics#sending); PHP [`analytics->sending`](https://nextmail.sh/docs/php/reference/analytics#sending); Go [`Analytics.Sending`](https://nextmail.sh/docs/go/reference/analytics#sending); Java [`analytics().sending`](https://nextmail.sh/docs/java/reference/analytics#sending); C# [`Analytics.SendingAsync`](https://nextmail.sh/docs/csharp/reference/analytics#sending).

### `getSendingStreams`

The two sending lanes of this workspace, transactional for app mail and broadcast for newsletters, with whether each is active or paused, and the recipients, bounces and complaints of the last 7 days against the limits. The broadcast lane pauses itself when bounces pass 4% or complaints pass 0.2%, and app mail keeps going out.

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

**Inputs**

Takes no input.

Also available in: API [`GET /sending/streams`](https://nextmail.sh/docs/api/reference/sending#get-sending-streams); TypeScript [`nextmail.sending.listStreams()`](https://nextmail.sh/docs/sdk/reference/sending#listStreams); Python [`sending.list_streams()`](https://nextmail.sh/docs/python/reference/sending#listStreams); Ruby [`sending.list_streams`](https://nextmail.sh/docs/ruby/reference/sending#listStreams); PHP [`sending->listStreams`](https://nextmail.sh/docs/php/reference/sending#listStreams); Go [`Sending.ListStreams`](https://nextmail.sh/docs/go/reference/sending#listStreams); Java [`sending().listStreams`](https://nextmail.sh/docs/java/reference/sending#listStreams); C# [`Sending.ListStreamsAsync`](https://nextmail.sh/docs/csharp/reference/sending#listStreams).

### `resumeSendingStream`

Resume the broadcast lane after it was paused for too many bounces or complaints. Broadcasts that were on hold continue at once, and the 7 day count starts again from now, so clean the audience first. Only the workspace owner can do it. It asks for a verification code, and in the app's chat it always asks first.

- Scopes: `domains:write`.
- The app's assistant always asks first.
- Asks for a verification code, the same as [`POST /sending/streams/{stream}/resume`](https://nextmail.sh/docs/api/reference/sending#post-sending-streams-stream-resume).
- Toolkit: `insights`.

**Inputs**

- `stream` (`string`, required, one of `"transactional"`, `"broadcast"`)

Also available in: API [`POST /sending/streams/{stream}/resume`](https://nextmail.sh/docs/api/reference/sending#post-sending-streams-stream-resume); TypeScript [`nextmail.sending.resumeStream()`](https://nextmail.sh/docs/sdk/reference/sending#resumeStream); Python [`sending.resume_stream()`](https://nextmail.sh/docs/python/reference/sending#resumeStream); Ruby [`sending.resume_stream`](https://nextmail.sh/docs/ruby/reference/sending#resumeStream); PHP [`sending->resumeStream`](https://nextmail.sh/docs/php/reference/sending#resumeStream); Go [`Sending.ResumeStream`](https://nextmail.sh/docs/go/reference/sending#resumeStream); Java [`sending().resumeStream`](https://nextmail.sh/docs/java/reference/sending#resumeStream); C# [`Sending.ResumeStreamAsync`](https://nextmail.sh/docs/csharp/reference/sending#resumeStream).

### `listDedicatedIps`

The dedicated sending IPs of this workspace, each with its status, how far its warm-up has come as a percentage, and the pool it sends through. A workspace without the dedicated IP add-on has none and sends through the shared IPs.

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

**Inputs**

Takes no input.

Also available in: API [`GET /sending/dedicated-ips`](https://nextmail.sh/docs/api/reference/sending#get-sending-dedicated-ips); TypeScript [`nextmail.sending.listDedicatedIps()`](https://nextmail.sh/docs/sdk/reference/sending#listDedicatedIps); Python [`sending.list_dedicated_ips()`](https://nextmail.sh/docs/python/reference/sending#listDedicatedIps); Ruby [`sending.list_dedicated_ips`](https://nextmail.sh/docs/ruby/reference/sending#listDedicatedIps); PHP [`sending->listDedicatedIps`](https://nextmail.sh/docs/php/reference/sending#listDedicatedIps); Go [`Sending.ListDedicatedIPs`](https://nextmail.sh/docs/go/reference/sending#listDedicatedIps); Java [`sending().listDedicatedIps`](https://nextmail.sh/docs/java/reference/sending#listDedicatedIps); C# [`Sending.ListDedicatedIpsAsync`](https://nextmail.sh/docs/csharp/reference/sending#listDedicatedIps).

### `getDedicatedIp`

One dedicated sending IP of this workspace by its address: its status, warm-up percentage, pool, and when it was assigned and became ready.

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

**Inputs**

- `ip` (`string`, required, 3 to 64 characters)