---
title: "Mail metrics"
method: GET
path: "/v1/metrics"
tags: ["Metrics"]
---

# Mail metrics

`GET /v1/metrics`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/metrics`
- Auth: HTTP bearer

**Requires scope:** `read`. Counts of sent, delivered, bounced, complained, received and reply messages per day or hour (UTC). Defaults to the last 30 days by day, or the last 48 hours by hour; at most 366 days or 744 hours per call. A test key counts test mail only and a live key live mail only.

## Query parameters

- `from` string
- `to` string
- `agent_id` string
- `interval` 'day' | 'hour'

## Response `200`

Buckets for the range, oldest first.

- Metrics
  - `interval` 'day' | 'hour', required: Bucket size, in UTC: `day` or `hour`, as requested; `day` when the request names none.
  - `from` string, date-time, required: Start of the range, inclusive: the requested `from` moved back to the start of its UTC day or hour. Left out, 30 days before `to` by day or 48 hours by hour, rounded the same way.
  - `to` string, date-time, required: End of the range, exclusive, as requested and not rounded, so the last bucket can be partial. Left out, the time of the request.
  - `agent_id` string: The agent the counts are limited to, as its id even when the request gave its name. Absent when they cover every agent; a key tied to one agent always gets its own.
  - `test_mode` boolean, required: A test key counts test mail only; a live key, live mail only.
  - `data` MetricsBucket[], required: Every bucket in the range, oldest first, zeros included.
    - `start` string, date-time, required: Start of the bucket (UTC).
    - `sent` integer, required: Messages sent in this bucket, one per message whatever its recipient count. A scheduled message counts when it goes out; a send the mail provider refused does not.
    - `delivered` integer, required: Messages confirmed delivered in this bucket, counted by delivery time, not send time. Always 0 for a test key: test sends are never transmitted.
    - `bounced` integer, required: Messages that bounced in this bucket, counted by bounce time. A soft bounce, which marks a message `delayed`, is not counted; always 0 for a test key.
    - `complained` integer, required: Messages a recipient reported as spam in this bucket, counted by complaint time. Always 0 for a test key.
    - `received` integer, required: Messages received in this bucket, counted by arrival time. Quarantined mail and mail received over a limit count too.
    - `replies` integer, required: Received messages that answered a thread.
  - `totals` object, required: Each count summed over every bucket in the range.
    - `sent` integer, required: Messages sent in the range, counted by send time.
    - `delivered` integer, required: Messages confirmed delivered in the range, counted by delivery time.
    - `bounced` integer, required: Messages that bounced in the range, counted by bounce time.
    - `complained` integer, required: Messages reported as spam in the range, counted by complaint time.
    - `received` integer, required: Messages received in the range, counted by arrival time.
    - `replies` integer, required: Received messages in the range that answered a thread.

## Other responses

- `400`: Invalid request — malformed JSON or a field failed validation. Also `feature_not_enabled` when this server has a feature switched off (custom domains before they are available).
- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `404`: Resource not found in this workspace, or the agent a send names is archived (`agent_archived`).
- `409`: Conflict — duplicate resource, an in-progress idempotent request, a draft or scheduled message that started sending while it was being changed, or a thread deleted for good while one of its messages is being sent (`duplicate_resource`); or an agent name more than one agent has (`agent_name_conflict`: use the agent's id); or a status change on an archived agent, since archiving cannot be undone (`agent_archived`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)