Mail API reference

Mail API · Metrics

get/v1/workspaces/{workspace_id}/emails/metricsAuth

Email metrics for a workspace

Outbound email counts and rates over a range of up to 30 days, in hourly or daily buckets in your time zone, optionally per sending domain, filtered by domain, API key or source. Read-only. - **Emails** (`sent`): messages that left the queue. - **Deliverability rate**: delivered / emails sent with delivery tracking. Emails sent before delivery tracking started, or through a custom SMTP relay, are confirmed at hand-off only, so for them `delivered` is not measured and the rate is `null` (`measured.delivery = false`), never 0. - **Bounce rate**: bounced / emails. Suppressed recipients never count. - **Complaint rate**: complained / delivered, from mailbox providers' feedback loops. Rates are numbers from 0 to 1, or `null` when unmeasured or when the denominator is zero. Template test sends are excluded. Cached for up to 60 seconds.

Path parameters

workspace_id*string · uuid

Workspace id.

Query parameters

start_datestring

Start of the range, inclusive. ISO 8601. A bare date (`2026-10-12`) is that calendar day in `timezone`; a date-time without an offset is a wall time in `timezone`; one with `Z` or an offset is that instant. Default: midnight six days before today, so the default range is the last 7 days including today. Must be within the 30-day message retention.

end_datestring

End of the range, exclusive. ISO 8601. A bare date (`2026-10-12`) is that calendar day in `timezone`; a date-time without an offset is a wall time in `timezone`; one with `Z` or an offset is that instant. A bare date includes that whole day. Default: now. At most 30 days after `start_date`.

timezonestring

IANA time zone the buckets and bare dates follow (DST-aware). Default `UTC`.

granularityenum (2)

Bucket width. Default `hourly` when the range is 2 days or less, otherwise `daily`. `hourly` is limited to ranges of 7 days or less.

domain_idarray

Only mail sent from these domains (`domain.id`). Repeat the parameter (with or without `[]`) or comma-separate the values; at most 100.

api_key_idstring · uuid

Only mail sent with this Platform API Key. Keys are recorded from 2026-10-12; older mail has none.

sourceenum (3)

Only mail sent this way: `api_key` (a Platform API Key), `dashboard` (a signed-in person, in the console or through MCP), `platform` (in-cluster product mail, and every message sent before 2026-10-12). Template test sends are never counted.

dimensionsarray

How `data` is broken down. `period`: one item per bucket (dense, zero-filled). `domain`: one item per sending domain. Both: one item per bucket and domain. Default `period`. Repeat the parameter (with or without `[]`) or comma-separate the values.

Response · 200 Email metrics.

object*object

Object type.

Example: "metrics"

start_date*string · date-time

Resolved start of the range (inclusive), in `timezone`’s offset.

Example: "2026-10-06T00:00:00+01:00"

end_date*string · date-time

Resolved end of the range (exclusive), in `timezone`’s offset.

Example: "2026-10-12T15:00:00+01:00"

timezone*string

IANA time zone of the buckets.

Example: "Europe/Lisbon"

granularity*object

Bucket width used.

Example: "daily"

measured*object

Which rates this range can measure at all.

bounce_source*object

How bounces were captured for the sent mail: `ses` (delivery tracking; bounces matched by message id), `relay` (emails sent before delivery tracking started, or through a custom SMTP relay; partial capture), `mixed`, or `none` (nothing sent).

Example: "ses"

totals*object

Counts and rates over the whole range.

data*array

The breakdown `dimensions` asks for, oldest bucket first, then by domain name. With `period`, every bucket is present (zero-filled).

Example

Request

GET https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/emails/metrics
Authorization: Bearer YOUR_TOKEN

Response

{
  "object": "metrics",
  "start_date": "2026-10-06T00:00:00+01:00",
  "end_date": "2026-10-12T15:00:00+01:00",
  "timezone": "Europe/Lisbon",
  "granularity": "daily",
  "measured": {},
  "bounce_source": "ses",
  "totals": {},
  "data": [
    {
      "sent": 29037,
      "delivered": 1240,
      "deferred": 3,
      "bounced": 12,
      "complained": 1,
      "failed": 0,
      "suppressed": 5,
      "unconfirmed": 60,
      "tracked": 1273,
      "delivery_rate": 0.974,
      "bounce_rate": 0.0185,
      "complaint_rate": 0.0001,
      "period": "2026-10-12T00:00:00+01:00",
      "domain_id": "3f6b2a1e-8c4d-4e5f-9a0b-1c2d3e4f5a6b",
      "domain_name": "mail.example.com"
    }
  ]
}