/v1/workspaces/{workspace_id}/emails/metricsAuthEmail 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 · uuidWorkspace id.
Query parameters
start_datestringStart 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_datestringEnd 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`.
timezonestringIANA 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_idarrayOnly mail sent from these domains (`domain.id`). Repeat the parameter (with or without `[]`) or comma-separate the values; at most 100.
api_key_idstring · uuidOnly 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.
dimensionsarrayHow `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*objectObject type.
Example: "metrics"
start_date*string · date-timeResolved start of the range (inclusive), in `timezone`’s offset.
Example: "2026-10-06T00:00:00+01:00"
end_date*string · date-timeResolved end of the range (exclusive), in `timezone`’s offset.
Example: "2026-10-12T15:00:00+01:00"
timezone*stringIANA time zone of the buckets.
Example: "Europe/Lisbon"
granularity*objectBucket width used.
Example: "daily"
measured*objectWhich rates this range can measure at all.
bounce_source*objectHow 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*objectCounts and rates over the whole range.
data*arrayThe 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_TOKENResponse
{
"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"
}
]
}