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

# $client->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

```php
mailbox(
    DateTimeInterface|string|null $from = null,
    DateTimeInterface|string|null $to = null,
    ?int $offsetMinutes = null,
    ?string $grain = null,
    ?string $address = null,
    ?string $apiKey = null,
): array
```

Returns 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**

- `from` (`string|DateTimeInterface`): The start of the window. Defaults to 30 days before `to:`.
- `to` (`string|DateTimeInterface`): The end of the window. Defaults to now.
- `offsetMinutes` (`int`): Minutes east of UTC, from -840 to 840, defaulting to 0. Pass `intdiv((new DateTimeImmutable())->getOffset(), 60)` for the local zone.
- `grain` (`string`): Bucket width: `minute`, `hour` or `day`, defaulting to `day`.
- `address` (`string`): Count only the mail delivered to this address.
- `apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

An array with `object` set to `mailbox_insights`, `from`, `to`, `grain`, `offsetMinutes`, `scanned`, `days`, `hours`, `addresses`, `senders`, `senderCount`, `waiting`, `unattributed`, `folders` and `series`.

**Example**

```php
$insights = $client->analytics->mailbox(
    from: new \DateTimeImmutable('-7 days'),
    offsetMinutes: intdiv((new \DateTimeImmutable())->getOffset(), 60),
);

echo $insights['scanned'], ' conversations from ', $insights['senderCount'], ' senders', PHP_EOL;

foreach ($insights['senders'] as $sender) {
    echo $sender['email'], ' ', $sender['count'], PHP_EOL;
}
```

**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); 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); 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).

### `analytics->sending`

Read what became of sent mail

```php
sending(
    ?int $days = null,
    ?int $minutes = null,
    ?int $offsetMinutes = null,
    ?string $grain = null,
    ?string $address = null,
    DateTimeInterface|string|null $since = null,
    DateTimeInterface|string|null $until = null,
    ?string $recipient = null,
    ?string $tag = null,
    ?string $apiKey = null,
): array
```

Returns 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**

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

**Returns**

An array with `object` set to `sending_analytics`, `since`, `until`, `grain`, `offsetMinutes`, `totals`, `days`, `statuses`, `sources`, `streams`, `senders` and `suppressed`.

**Example**

```php
$analytics = $client->analytics->sending(days: 7, grain: 'day');

$totals = $analytics['totals'];

echo $totals['delivered'], ' of ', $totals['sends'], ' delivered, ', $totals['bounced'], ' bounced', PHP_EOL;

foreach ($analytics['days'] as $day) {
    echo $day['day'], ': ', $day['sent'], ' sent', PHP_EOL;
}
```

**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); 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); 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).