diff --git a/resend.yaml b/resend.yaml index 1b75d78..8d4bda2 100644 --- a/resend.yaml +++ b/resend.yaml @@ -44,6 +44,8 @@ tags: description: Create and manage Events through the Resend API. - name: OAuth description: List and manage OAuth grants through the Resend API. + - name: Metrics + description: Retrieve account-level email metrics through the Resend API. paths: /emails: post: @@ -2055,6 +2057,146 @@ paths: application/json: schema: $ref: '#/components/schemas/RemoveSuppressionResponseSuccess' + /metrics/overview: + get: + tags: + - Metrics + summary: Retrieve account-level delivery metrics + description: >- + Volume and delivery counts for a date range. Per-period `timeseries` and + per-domain `domain_breakdown` are opt-in via `include`. + parameters: + - name: start_date + in: query + required: true + schema: + type: string + format: date-time + description: >- + Start of the range (ISO 8601). Must be on or before end_date and + within your plan's retention window. + - name: end_date + in: query + required: true + schema: + type: string + format: date-time + description: End of the range (ISO 8601). + - name: timezone + in: query + required: false + schema: + type: string + default: UTC + description: IANA timezone used to bucket the time series. Defaults to UTC. + - name: domain_id + in: query + required: false + schema: + type: string + format: uuid + description: Restrict metrics to a single domain. + - name: event_type + in: query + required: false + description: >- + Project the counts down to only the listed events. Repeat the + parameter to select multiple (e.g. + event_type=delivered&event_type=bounced). + schema: + type: array + items: + type: string + enum: + - received + - delivered + - bounced + - complained + - opened + - clicked + - delivery_delayed + - failed + - unsubscribed + - suppressed + - name: include + in: query + required: false + description: >- + Add breakdowns. Repeat the parameter to select multiple (e.g. + include=timeseries&include=domain_breakdown). Defaults to totals only. + schema: + type: array + items: + type: string + enum: + - timeseries + - domain_breakdown + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetMetricsOverviewResponseSuccess' + /metrics/engagement: + get: + tags: + - Metrics + summary: Retrieve account-level engagement metrics + description: >- + Unique open/click engagement with rates for a date range. Per-period + `timeseries` and per-domain `domain_breakdown` are opt-in via `include`. + parameters: + - name: start_date + in: query + required: true + schema: + type: string + format: date-time + description: >- + Start of the range (ISO 8601). Must be on or before end_date and + within your plan's retention window. + - name: end_date + in: query + required: true + schema: + type: string + format: date-time + description: End of the range (ISO 8601). + - name: timezone + in: query + required: false + schema: + type: string + default: UTC + description: IANA timezone used to bucket the time series. Defaults to UTC. + - name: domain_id + in: query + required: false + schema: + type: string + format: uuid + description: Restrict metrics to a single domain. + - name: include + in: query + required: false + description: >- + Add breakdowns. Repeat the parameter to select multiple (e.g. + include=timeseries&include=domain_breakdown). Defaults to totals only. + schema: + type: array + items: + type: string + enum: + - timeseries + - domain_breakdown + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetMetricsEngagementResponseSuccess' webhooks: email.sent: post: @@ -6489,3 +6631,187 @@ components: format: date-time description: Timestamp indicating when the suppression was created. example: "2023-10-06T23:47:56.678Z" + MetricCounts: + type: object + description: >- + Volume and delivery counts. When `event_type` is set, only the requested + event keys are present. + properties: + sent: + type: integer + description: Derived count (delivered + bounced + failed). + example: 12053 + delivered: + type: integer + example: 11800 + delivery_delayed: + type: integer + example: 40 + bounced: + type: integer + example: 210 + complained: + type: integer + example: 5 + opened: + type: integer + description: Total opens. See engagement.opens for unique opens. + example: 5400 + clicked: + type: integer + description: Total clicks. See engagement.clicks for unique clicks. + example: 1200 + unsubscribed: + type: integer + example: 30 + suppressed: + type: integer + example: 900 + received: + type: integer + example: 8300 + failed: + type: integer + example: 43 + MetricsTimeseriesPoint: + allOf: + - type: object + properties: + period: + type: string + description: ISO date (daily buckets) or datetime (hourly buckets). + example: '2026-07-08' + - $ref: '#/components/schemas/MetricCounts' + MetricsDomainBreakdown: + allOf: + - type: object + properties: + domain_id: + type: string + format: uuid + example: 067b3160-d611-491e-943e-c0c4cd497d2d + domain_name: + type: string + example: mail.acme.com + - $ref: '#/components/schemas/MetricCounts' + MetricsOverview: + allOf: + - $ref: '#/components/schemas/MetricCounts' + - type: object + properties: + timeseries: + type: array + description: Per-period counts. Included only when `include=timeseries`. + items: + $ref: '#/components/schemas/MetricsTimeseriesPoint' + domain_breakdown: + type: array + description: Per-domain counts. Included only when `include=domain_breakdown`. + items: + $ref: '#/components/schemas/MetricsDomainBreakdown' + EngagementMetric: + type: object + description: >- + A unique count over its tracking-eligible delivered denominator, with the + derived rate. + properties: + unique: + type: integer + description: Unique recipients (deduplicated). + example: 5400 + delivered: + type: integer + description: >- + Deliveries to tracking-enabled domains — the rate denominator. Not the + same as overview.delivered. + example: 11800 + rate: + type: number + description: >- + unique / delivered as a percentage, capped at 100. 0 when nothing was + trackable. + example: 45.76 + EngagementTimeseriesPoint: + type: object + properties: + period: + type: string + example: '2026-07-08' + opens: + $ref: '#/components/schemas/EngagementMetric' + clicks: + $ref: '#/components/schemas/EngagementMetric' + EngagementDomainBreakdown: + type: object + properties: + domain_id: + type: string + format: uuid + example: 067b3160-d611-491e-943e-c0c4cd497d2d + domain_name: + type: string + example: mail.acme.com + opens: + $ref: '#/components/schemas/EngagementMetric' + clicks: + $ref: '#/components/schemas/EngagementMetric' + MetricsEngagement: + type: object + description: >- + Unique open/click engagement with rates. Not affected by the event_type + filter. + properties: + open_tracking_enabled: + type: boolean + example: true + click_tracking_enabled: + type: boolean + example: true + opens: + $ref: '#/components/schemas/EngagementMetric' + clicks: + $ref: '#/components/schemas/EngagementMetric' + timeseries: + type: array + description: Per-period engagement. Included only when `include=timeseries`. + items: + $ref: '#/components/schemas/EngagementTimeseriesPoint' + domain_breakdown: + type: array + description: Per-domain engagement. Included only when `include=domain_breakdown`. + items: + $ref: '#/components/schemas/EngagementDomainBreakdown' + GetMetricsOverviewResponseSuccess: + allOf: + - type: object + properties: + object: + type: string + const: metrics_overview + description: The response object type. + start_date: + type: string + format: date-time + example: '2026-06-17T23:59:59.000Z' + end_date: + type: string + format: date-time + example: '2026-07-17T23:59:59.000Z' + - $ref: '#/components/schemas/MetricsOverview' + GetMetricsEngagementResponseSuccess: + allOf: + - type: object + properties: + object: + type: string + const: metrics_engagement + description: The response object type. + start_date: + type: string + format: date-time + example: '2026-06-17T23:59:59.000Z' + end_date: + type: string + format: date-time + example: '2026-07-17T23:59:59.000Z' + - $ref: '#/components/schemas/MetricsEngagement'