---
title: Analytics
description: Delivery statistics a few seconds after each event, in the dashboard and through GET /emails/metrics.
---

Every outcome (delivered, bounced, complained, opened, clicked, unsubscribed) is counted a few seconds after it happens. The dashboard's **Analytics** page and `GET /emails/metrics` read the same numbers.

In the dashboard, Analytics shows delivery, open, click, bounce and complaint rates and an events-by-hour chart. You can filter by time range (7, 15 or 30 days), time zone, brand (sending domain), broadcast and recipient domain.

Statistics are kept per hour for 13 months. A broadcast's own history is not cut off at 13 months. If the statistics service does not answer, the endpoint returns `503 service_unavailable` and sending is not affected. Email lists, exports and one email's events are not statistics; see [Logs](/docs/concepts/logs).

## Ask for numbers

`GET /emails/metrics` needs a full-access [API key](/docs/api-reference/basics). The SDKs call it as `emails.metrics()`.

```sh
curl "https://api.billionsend.com/emails/metrics?start_date=2026-11-01&end_date=2026-11-14&granularity=daily&metrics=sent&metrics=delivered&metrics=open_rate&dimensions=period" \
  -H "Authorization: Bearer bs_..."
```

| Parameter | What it does |
| --- | --- |
| `start_date`, `end_date` | The range. Statistics are read in whole UTC hours, and the answer shows the start it used. |
| `timezone` | An IANA zone name such as `Europe/Berlin` (a UTC offset such as `+05:00` is not accepted). Periods are cut in this zone. |
| `granularity` | `hourly`, `daily`, `weekly` or `monthly`: the size of a period when `dimensions` includes `period`. A range can span at most 10,000 periods. |
| `metrics` | Repeat it for each metric you want (see below). |
| `dimensions` | Repeat it for each breakdown: `period`, `domain`, `email` or `broadcast`. `email` and `broadcast` cannot be combined. |
| `domain_id`, `email_id`, `broadcast_id` | Filters. Repeat each up to 100 times. |

The response has `totals` for the whole range and, when you ask for dimensions, one row per combination in `data`.

## Metrics

| Metric | Counts |
| --- | --- |
| `received` | Recipients accepted for sending. It belongs to no domain, broadcast or email, so an answer filtered or broken down by one leaves it out. |
| `sent`, `delivered`, `delivery_delayed`, `failed`, `suppressed` | Recipients, by outcome of the send. |
| `bounced`, `bounced_permanent`, `bounced_transient`, `bounced_undetermined` | Bounces, and the three classes of bounce. |
| `complained`, `unsubscribed` | Spam complaints, and recipients who left through the unsubscribe link. |
| `opened`, `clicked` | Every open and click. |
| `unique_opened`, `unique_clicked` | Emails opened or clicked at least once. |
| `delivery_rate` | `delivered` ÷ `sent` |
| `bounce_rate` | `bounced` ÷ `sent` |
| `open_rate`, `click_rate` | `unique_opened` or `unique_clicked` ÷ `delivered` |
| `complaint_rate`, `unsubscribe_rate` | `complained` or `unsubscribed` ÷ `delivered` |

Rates are percentages with one decimal, and `0` when there is nothing to divide by. Opens and clicks made by machines, such as privacy proxies and security scanners, are not counted as opens or clicks.

With the `email` dimension and no `email_id`, the answer lists up to 1,000 emails created in the range.

## Clicks by link

`GET /emails/metrics/links` (a BillionSend extension, full-access key) lists the links people clicked in a range, most clicked first:

```sh
curl "https://api.billionsend.com/emails/metrics/links?start_date=2026-11-01&end_date=2026-11-14&limit=10" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "object": "list",
  "start_date": "2026-11-01T00:00:00.000Z",
  "end_date": "2026-11-14T23:59:59.999Z",
  "has_more": false,
  "data": [
    { "link": "https://shop.example.com/sale", "clicked": 412, "bot_clicked": 37 }
  ]
}
```

- A link is counted as its scheme, host and path. The query string and the fragment are left out, so a link personalised for each recipient is one row and no recipient's details are stored.
- `clicked` counts people; `bot_clicked` counts fetches by machines such as security scanners and link previews.
- It takes `start_date`, `end_date`, `domain_id`, `broadcast_id` (comma-separated) and `limit` (1 to 100, default 20), and covers whole UTC hours like `GET /emails/metrics`. Clicks are counted by link from November 16, 2026.

## Opens and clicks by country and mail client

`GET /emails/metrics/countries` lists people's opens and clicks by the country they came from, and `GET /emails/metrics/clients` lists opens by the mail client that loaded the images (both BillionSend extensions, full-access key), most engaged first:

```sh
curl "https://api.billionsend.com/emails/metrics/countries?start_date=2026-11-16&end_date=2026-11-30" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "object": "list",
  "start_date": "2026-11-16T00:00:00.000Z",
  "end_date": "2026-11-30T23:59:59.999Z",
  "has_more": false,
  "data": [
    { "country": "BR", "opened": 1840, "unique_opened": 1203, "bot_opened": 95, "clicked": 311, "unique_clicked": 240, "bot_clicked": 22 },
    { "country": "unknown", "opened": 960, "unique_opened": 702, "bot_opened": 410, "clicked": 12, "unique_clicked": 9, "bot_clicked": 3 }
  ]
}
```

- `country` is the ISO 3166-1 alpha-2 code of the country the reader's address is registered in. It is `unknown` when the address cannot be placed, and for opens through Gmail's and Yahoo's image proxies or Apple Mail Privacy Protection: those come from the provider's address, not the reader's.
- `client` is one of `gmail`, `apple_mail`, `outlook`, `yahoo`, `thunderbird`, `other` (a web browser: webmail and clients that do not name themselves look the same) or `unknown` (no user agent). Clicks are not counted by client, because a click arrives from the browser the mail client hands the link to.
- Only the country and the client are kept for statistics, never the address or the user agent.
- `unique_opened` and `unique_clicked` count emails whose first open or click came from that country or client. People and machines are counted apart, as in `GET /emails/metrics`.
- Both take `start_date`, `end_date`, `domain_id` and `broadcast_id` (comma-separated), cover whole UTC hours, and return every row (there are only so many countries and clients). Opens and clicks are counted by country and client from November 16, 2026.
- IP geolocation by [DB-IP](https://db-ip.com), licensed under CC BY 4.0.

## Related

[Deliverability Insights](/docs/concepts/deliverability-insights) scores each email and your account. To react to an outcome as it happens instead of counting it later, use [webhooks](/docs/concepts/webhooks).
