---
title: "Statistics API"
description: "Statistics in the OneSend API: 2 endpoints. Delivery and engagement statistics with filters."
url: https://onesend.email/docs/api-reference/statistics/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Statistics

Delivery and engagement statistics with filters.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## Email statistics with filters and previous-period comparison

GET `/v1/statistics/overview`

Defaults to the last 30 days. `previous` holds the same rates for the period of equal length just before `from`. `provider` accepts provider ids (e.g. `resend`) or connection ids, comma separated.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `from` | query | `string` |  |
| `until` | query | `string` |  |
| `type` | query | `"all" \| "transactional" \| "marketing"` | Default "all". |
| `campaignId` | query | `string` |  |
| `provider` | query | `string` |  |
| `domain` | query | `string` |  |
| `recipientDomain` | query | `string` |  |
| `tag` | query | `string` |  |
| `templateId` | query | `string` |  |
| `interval` | query | `"hour" \| "day" \| "week"` | Bucket size. Days and weeks start at midnight in the workspace time zone. Ranges: hour ≤ 31 days, day ≤ 2 years, week ≤ 10 years. Default "day". |

### Responses

`200` Success

```
{
  "totals": {
    "recipients": number,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "opens": number,
    "uniqueClicks": number,
    "clicks": number,
    "hardBounces": number,
    "softBounces": number,
    "unsubscribes": number,
    "complaints": number,
    "conversions": number,
    "revenue": number
  },
  "rates": {
    "delivery": number,
    "open": number,
    "click": number,
    "clickToOpen": number,
    "bounce": number,
    "unsubscribe": number,
    "complaint": number,
    "conversion": number
  },
  "previous": {
    "delivery": number,
    "open": number,
    "click": number,
    "clickToOpen": number,
    "bounce": number,
    "unsubscribe": number,
    "complaint": number,
    "conversion": number
  },
  "series": [{
    "t": string,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "bounces": number,
    "unsubscribes": number,
    "conversions": number,
    "complaints": number
  }],
  "topCampaigns": [{
    "id": string,
    "name": string,
    "sentAt": string or null,
    "recipients": number,
    "openRate": number,
    "clickRate": number,
    "bounceRate": number,
    "conversionRate": number
  }],
  "byRecipientDomain": [{
    "domain": string,
    "sent": number,
  …
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Email by mailbox provider and by category

GET `/v1/statistics/breakdown`

Same filters as the overview (default last 30 days). `byMailboxProvider` groups recipients by their mailbox provider from the recipient domain (gmail.com and googlemail.com → google; outlook, hotmail, live and msn → outlook; yahoo, ymail and aol → yahoo; icloud, me and mac → apple; proton → proton; everything else → other). `byCategory` lists transactional email, each campaign and automation email.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `from` | query | `string` |  |
| `until` | query | `string` |  |
| `type` | query | `"all" \| "transactional" \| "marketing"` | Default "all". |
| `campaignId` | query | `string` |  |
| `provider` | query | `string` |  |
| `domain` | query | `string` |  |
| `recipientDomain` | query | `string` |  |
| `tag` | query | `string` |  |
| `templateId` | query | `string` |  |

### Responses

`200` Success

```
{
  "byMailboxProvider": [{
    "provider": "google" | "outlook" | "yahoo" | "apple" | "proton" | "other",
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "bounced": number,
    "complaints": number,
    "rates": {
      "delivery": number,
      "open": number,
      "click": number,
      "bounce": number,
      "complaint": number
    }
  }],
  "byCategory": [{
    "kind": "transactional" | "campaign" | "automation",
    "campaignId": string or null,
    "name": string or null,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "bounced": number,
    "complaints": number,
    "rates": {
      "delivery": number,
      "open": number,
      "click": number,
      "bounce": number,
      "complaint": number
    }
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
