API · Emails

Retrieve Metrics

Retrieve email metrics for your team or domains, with 15-minute precision and a maximum range of one year (requires full access). A request can cover up to 31 domain-period spans.

GET/emails/metricsFull access

Request parameters

Parameter	Type	Description
`start_date` query · optional	`string`	ISO 8601 start date or datetime, no later than end_date, defaulting to six days before end_date.
`end_date` query · optional	`string`	ISO 8601 end date or datetime, defaulting to now and clamped to now for future values.
`timezone` query · optional	`string` Default: UTC	The IANA timezone (e.g. `America/New_York`) used to bucket periods when `period` is in `dimensions`.
`granularity` query · optional	`"hourly" \| "daily" \| "weekly" \| "monthly"` Default: daily	Period size for the period dimension, limited to 10000 periods in a date range.
`metrics` query · optional	`("received" \| "delivered" \| "complained" \| "suppressed" \| "bounced" \| "bounced_transient" \| "bounced_permanent" \| "bounced_undetermined" \| "opened" \| "clicked" \| "unsubscribed" \| "delivery_delayed" \| "failed" \| "sent" \| "unique_opened" \| "unique_clicked" \| "delivery_rate" \| "open_rate" \| "click_rate" \| "bounce_rate" \| "complaint_rate" \| "unsubscribe_rate")[]`	Comma-separated or repeated metric names, defaulting to the 18 supported metrics; opened, clicked, unsubscribed, and unsubscribe_rate return 422.
`dimensions` query · optional	`("period" \| "domain" \| "email" \| "broadcast")[]`	Comma-separated or repeated period and domain dimensions; email and broadcast return 422, and omission returns only totals without data.
`domain_id` query · optional	`(string)[]`	Up to 100 sending domain IDs, supplied as comma-separated values or repeated parameters.
`email_id` query · optional	`(string)[]`	Email filters are unsupported and return 422.
`broadcast_id` query · optional	`(string)[]`	Broadcast filters are unsupported and return 422.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X GET "$OPENSEND_BASE_URL/emails/metrics?metrics=sent%2Cdelivered&dimensions=period" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

Response

200 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "object": "metrics",
  "start_date": "2026-07-01T00:00:00.000Z",
  "end_date": "2026-07-08T00:00:00.000Z",
  "metrics": [
    "example"
  ],
  "dimensions": [
    "period"
  ],
  "granularity": "hourly",
  "totals": {},
  "data": [
    {
      "period": "example",
      "domain_id": "YOUR_DOMAIN_ID",
      "domain_name": "example",
      "email_id": "YOUR_EMAIL_ID",
      "broadcast_id": "YOUR_BROADCAST_ID",
      "broadcast_name": "example"
    }
  ]
}

Behavior and errors

Metrics follow email creation cohorts at 15-minute precision. Only period and domain dimensions are supported, within 31 domain-period spans and one year. See email metrics.

Use a full-access credential. Unknown or foreign resources return 404. See authentication, errors, rate limits, and pagination.