feat: add emails.metrics() for account-level email metrics

Merged
DI
2mo ago
+380-0

Adds Emails#metrics() for the beta GET /emails/metrics endpoint.

  • period / domain / email / broadcast dimensions
  • domain_id / email_id / broadcast_id filters (broadcast and email are mutually exclusive)
  • hourly / daily / weekly / monthly granularity

Pulled out of the preview-headless-dashboard branch (#1042, #1050, #1052, plus the broadcast-dimension addition) onto a clean branch off main, since this feature is ready to ship independently of the rest of that stack. Also drops sort_by/sort_order, which existed transiently in an earlier iteration of the public-api implementation and were removed before ship (resend/resend-monorepo#9f2428848f) — the option/response fields for it were never actually live in production, so they're left out here.

Mirrors resend/resend-openapi#96. Part of the emails/metrics rollout tracked in DEV-1771.

Summary by cubic

Adds Emails#metrics() to fetch account-level email metrics from the beta GET /emails/metrics endpoint. Previously there was no metrics API; now clients can query totals and breakdowns by period, domain, email, or broadcast.

  • Supports startDate, endDate, timezone, and granularity (hourly | daily | weekly | monthly), plus selecting metrics and dimensions (period | domain | email | broadcast).
  • Flat filters: domainId, emailId, broadcastId. email and broadcast are mutually exclusive and enforced at the type level via a discriminated union.
  • Builds the query with URLSearchParams, omitting unset fields and encoding comma-separated lists; returns totals and optional data rows keyed by selected dimensions.
  • Adds and exports types in src/emails/interfaces/get-metrics.interface.ts; tests cover default, domain/email/broadcast flows, and 422 error handling.
  • No breaking changes; part of DEV-1771 emails/metrics rollout.