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

# openemail.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.

### `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 openemail.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://openemail.uk/docs/api/reference/analytics#get-analytics-mailbox); CLI [`openemail analytics mailbox`](https://openemail.uk/docs/cli/reference/analytics#analytics-mailbox).

### `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`, `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 now, reported as `until`, and starts at the beginning of its oldest bucket, reported as `since`. `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.

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.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, senders, suppressed }`.

**Example**

```ts
const analytics = await openemail.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://openemail.uk/docs/api/reference/analytics#get-analytics-sending); CLI [`openemail analytics sending`](https://openemail.uk/docs/cli/reference/analytics#analytics-sending).