---
title: "nextmail.analytics"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/sdk/reference/analytics"
area: "TypeScript"
category: "Reference"
---

# nextmail.analytics

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

## Methods

The numbers behind the Analytics page: how mail arrives in the mailbox, and what became of the mail the workspace sent.

### `nextmail.analytics.mailbox()`

Read how mail arrives

```ts
mailbox(options?: MailboxInsightsOptions): Promise<MailboxInsightsResource>
```

Resolves how mail arrives, as the Analytics page of the app shows it, for a window, the last 30 days unless `from` and `to` say otherwise: how many conversations arrived and when, per `grain` bucket in `days` and per hour of the day in `hours`, the addresses they arrived at, the senders who wrote most, how many conversations wait on a reply for 1, 3 or 7 days or more, and the folders.

`days` is sparse: a bucket in which nothing arrived has no entry, so a chart must fill the gaps. `offsetMinutes` shifts the boundaries so days and hours break where the reader's do, and `series` holds the per bucket counts of the top addresses and senders so each can be charted.

A key limited to particular addresses counts only the mail that arrived at them, and `address` narrows everything to one address. An address the key does not reach counts nothing rather than failing.

Scopes: `threads:read`.

**Parameters**

- `options.from` (`Date | string`): The start of the window. Defaults to 30 days before `to`.
- `options.to` (`Date | string`): The end of the window. Defaults to now.
- `options.offsetMinutes` (`number`): Minutes east of UTC, from -840 to 840, defaulting to 0. Pass `-new Date().getTimezoneOffset()` for the local zone.
- `options.grain` (`TrackingGrain`): Bucket width: `minute`, `hour` or `day`, defaulting to `day`.
- `options.address` (`string`): Count only the mail delivered to this address.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`MailboxInsightsResource`, `{ object: 'mailbox_insights', from, to, grain, offsetMinutes, scanned, days, hours, addresses, senders, senderCount, waiting, unattributed, folders, series }`.

**Example**

```ts
const insights = await nextmail.analytics.mailbox({
    offsetMinutes: -new Date().getTimezoneOffset()
})

console.log(`${insights.scanned} conversations from ${insights.senderCount} senders`)

for (const sender of insights.senders) console.log(sender.email, sender.count)
```

**Notes**

- Read only, so the SDK retries it after a network failure like any other read.
- `from` after `to` is a 422 `invalid_parameter`.

Also available in: API [`GET /analytics/mailbox`](https://nextmail.sh/docs/api/reference/analytics#get-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); CLI [`nextmail analytics mailbox`](https://nextmail.sh/docs/cli/reference/analytics#analytics-mailbox).

### `nextmail.analytics.sending()`

Read what became of sent mail

```ts
sending(options?: SendingAnalyticsOptions): Promise<SendingAnalyticsResource>
```

Resolves the numbers behind the Analytics page of the app: what the workspace sent inside a window and what became of it. `totals` adds up the sends, recipients and test sends and how many were delivered, failed, bounced, complained about, uncertain or still pending, `days` cuts sent, delivered, failed, bounced and complained to `grain` buckets, and `statuses`, `sources`, `streams`, `senders` and `suppressed` break the window down.

The window is `days`, 30 by default and at most 365, or `minutes`, which wins when both are sent. It ends at `until`, now by default, and starts at `since` when that is sent, or else at the beginning of its oldest bucket. Both come back as `since` and `until`. `offsetMinutes` shifts the bucket boundaries so days break where the reader's do.

A key limited to particular addresses counts only the mail sent from them, and `address` narrows everything to one address. `recipient` and `tag` narrow it further, to the mail that went to one address or carried one tag.

Scopes: `emails:read`.

**Parameters**

- `options.days` (`number`): Window length in days, from 1 to 365, defaulting to 30.
- `options.minutes` (`number`): Window length in minutes, which wins over `days`.
- `options.offsetMinutes` (`number`): Minutes east of UTC, from -840 to 840, defaulting to 0.
- `options.grain` (`TrackingGrain`): Bucket width: `minute`, `hour` or `day`, defaulting to `day`.
- `options.address` (`string`): Count only the mail sent from this address.
- `options.since` (`Date | string`): Start of the window, which wins over `days` and `minutes`. A window spans at most 365 days.
- `options.until` (`Date | string`): End of the window, not included, defaulting to now. `since` after `until` is a 422 `invalid_parameter`.
- `options.recipient` (`string`): Count only the mail that went to this address, and only its delivery to that address.
- `options.tag` (`string`): Count only the mail sent with this tag: `name` for any value, or `name:value` for one value.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`SendingAnalyticsResource`, `{ object: 'sending_analytics', since, until, grain, offsetMinutes, totals, days, statuses, sources, streams, senders, suppressed }`.

**Example**

```ts
const analytics = await nextmail.analytics.sending({ days: 7 })

const { sends, delivered, bounced } = analytics.totals

console.log(`${delivered} of ${sends} delivered, ${bounced} bounced`)
```

**Notes**

- Read only, so the SDK retries it after a network failure like any other read.

Also available in: API [`GET /analytics/sending`](https://nextmail.sh/docs/api/reference/analytics#get-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); CLI [`nextmail analytics sending`](https://nextmail.sh/docs/cli/reference/analytics#analytics-sending).