> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API

> List delivery records, filter by status and date, export CSV files, and manage account tracking.

Use the Analytics API to retrieve sending history and delivery outcomes.

## Authentication

**Base URL:** `https://pro.api.serversmtp.com/api/v2`

Send `consumerKey` and `consumerSecret` headers with a key that has **Statistics & Management APIs** (`APIS`) permission. Its IP restrictions must allow your server. See [authentication](/docs/api-reference/authentication.md).

## List delivery records

`GET /analytics` returns a paginated object with `count` and `results`.

```bash Terminal theme={"system"}
curl --get 'https://pro.api.serversmtp.com/api/v2/analytics' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  --data-urlencode 'from=2026-10-01' \
  --data-urlencode 'to=2026-10-27' \
  --data-urlencode 'status[]=SUCCESS' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10'
```

| Query parameter | Description |
| - | - |
| `from`, `to` | Required dates in `YYYY-MM-DD` format. `from` must be on or before `to`. Do not include a time. |
| `page`, `limit` | Positive integers. Defaults: page `1`, limit `10`. |
| `status[]` or `status` | Statuses to include. Repeat `status[]` for each value, or pass one `status` value or a comma-separated list such as `status=FAIL,DEFER`. Omit to include all [statuses](#status-values). |
| `filter` | Text to search. Supply `filter_by` when using a filter. |
| `filter_by` | Fields to search: `subject`, `sender`, `recipient`, `domain`, `x_campaign_id`, `consumer_key`. Repeat the parameter for multiple fields. |
| `smart_search` | Boolean search option. |
| `orderby` | `subject`, `sender`, `recipient`, or `send_time` (default). |
| `ordertype` | `asc` or `desc`. |
| `tz` | Timezone offset, such as `+01:00`. URL-encode the plus sign. |

Example response:

```json theme={"system"}
{
  "count": 1,
  "results": [
    {
      "id": 1800872493473407000,
      "subject": "Order update",
      "sender": "orders@example.com",
      "recipient": "customer@example.net",
      "send_time": "2026-10-20 10:30:00",
      "status": "SUCCESS",
      "domain": "example.com",
      "recipient_domain": "example.net",
      "error": "",
      "consumer_key": "YOUR_CONSUMER_KEY"
    }
  ]
}
```

Treat message IDs as 64-bit identifiers. JavaScript's `JSON.parse` can round large numeric IDs; use a parser that preserves large integers when you need the exact value.

## Get one record

`GET /analytics/{Id}` returns one delivery record with the same fields as an item in `results`, except that the recipient domain is named `contact_domain` instead of `recipient_domain`. Use the message ID as `{Id}`. A missing record returns `404` with `message: "email_not_found"`.

## Export CSV

`GET /analytics/csv` accepts the same date, status, search, sorting, and timezone parameters as the list endpoint, without `page` or `limit`. Both `status[]` and comma-separated `status` work, and `orderby` and `ordertype` take the same values as the list.

```bash Terminal theme={"system"}
curl --get 'https://pro.api.serversmtp.com/api/v2/analytics/csv' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  --data-urlencode 'from=2026-10-01' \
  --data-urlencode 'to=2026-10-27' \
  --output analytics.csv
```

CSV columns are **Message Id**, **Status**, **Subject**, **From**, **To**, **Date**, **Reason**, and **Consumer Key**. In the dashboard, use **Analytics → Export**.

## Status values

Status values are case-sensitive. Send them in uppercase exactly as listed.

| Value | Meaning |
| - | - |
| `NEW` | Queued for delivery |
| `DEFER` | Delivery deferred; still queued |
| `SUCCESS` | Delivered |
| `OPEN` | An open was recorded |
| `CLICK` | A tracked link click was recorded |
| `REPORT` | Reported as spam |
| `FAIL` | Bounced |
| `SYSFAIL` | Dropped |
| `UNSUB` | Unsubscribed |

For delivered totals, include `SUCCESS`, `OPEN`, `CLICK`, `UNSUB`, and `REPORT`. For opens, include `OPEN`, `CLICK`, `UNSUB`, and `REPORT`. Queued totals combine `NEW` and `DEFER`; bounces use `FAIL` and drops use `SYSFAIL`. These are groups of status values, not additional API status strings.

## Tracking tools

`GET /tools` returns an array of tool objects containing only `id` and `enabled`.

```bash Terminal theme={"system"}
curl 'https://pro.api.serversmtp.com/api/v2/tools' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET'
```

Change account tracking settings with these bodyless requests:

| Method | Path | Effect |
| - | - | - |
| `PUT` | `/tools/clickTracking/enable` | Enable click tracking |
| `PUT` | `/tools/clickTracking/disable` | Disable click tracking |
| `PUT` | `/tools/openingTracking/enable` | Enable open tracking |
| `PUT` | `/tools/openingTracking/disable` | Disable open tracking |

```bash Terminal theme={"system"}
curl -X PUT 'https://pro.api.serversmtp.com/api/v2/tools/clickTracking/enable' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET'
```

In the dashboard, **Settings → Tracking** also includes Google Analytics and Custom Tracking Domains.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.