Emails

Email metrics

Query delivery counts and rates for your installation.

Retrieve metrics

Use retrieve metrics with a full-access credential. Select metric names and, optionally, a period or domain breakdown.

bash

curl --get "$OPENSEND_BASE_URL/emails/metrics" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  --data-urlencode 'metrics=sent,delivered,delivery_rate' \
  --data-urlencode 'dimensions=period' \
  --data-urlencode 'granularity=daily' \
  --data-urlencode 'timezone=UTC'

The response includes object: "metrics", the date range, selected metrics/dimensions, granularity, and totals. With dimensions it also includes data. Without dimensions it returns totals only.

Choose a range and breakdown

Use ISO start_date and end_date, an IANA timezone (default UTC), and hourly, daily, weekly, or monthly granularity (default daily). Without dates, the range covers today and the previous six days. Date-only end dates include that whole date; future ends are clamped to now.

Dimensions are period and domain, alone or together. Domain rows include domain_id and domain_name; period rows are chronological. domain_id accepts up to 100 owned domain IDs. Lists of metrics, dimensions, and domain IDs accept comma-separated or repeated query parameters.

Available metrics

Omitting metrics selects all 18 supported metrics:

Category	Metrics
Delivery	`received`, `sent`, `delivered`, `delivery_delayed`, `failed`, `suppressed`
Bounces and complaints	`bounced`, `bounced_transient`, `bounced_permanent`, `bounced_undetermined`, `complained`
Engagement	`unique_opened`, `unique_clicked`
Rates	`delivery_rate`, `open_rate`, `click_rate`, `bounce_rate`, `complaint_rate`

Rates are percentages computed from total counts, not averages of period rates. received counts retained email rows; other counts use retained unique milestones grouped by email creation time.

Precision and limits

Aggregates have 15-minute precision. Date-time boundaries round outward to those buckets. A query supports at most 31 domain-period spans and a one-year range. Use fewer domains, a coarser granularity, or a shorter range when a request exceeds these limits. Foreign domain IDs return 404.

Email/broadcast dimensions and filters, repeated opened/clicked counts, unsubscribed, and unsubscribe_rate return 422. Historical aggregates do not retain those dimensions and events. See compatibility before comparing provider metrics.