v49

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-02-185890337.1 KB
Usage

Export tenant usage data

Export email usage data for all tenants in CSV or JSON Lines format. Designed for billing system integration, data warehousing, and analytics.

Jobs to be done:

  • Import usage data into billing systems (Stripe, Chargebee, etc.)
  • Load into data warehouses (Snowflake, BigQuery, etc.)
  • Process in spreadsheets (Excel, Google Sheets)
  • Feed into BI tools (Looker, Metabase, etc.)

Export formats:

  • csv - UTF-8 with BOM for Excel compatibility (default)
  • jsonl - JSON Lines (one JSON object per line, streamable)

CSV columns: tenant_id, tenant_name, external_id, status, sent, delivered, soft_failed, hard_failed, bounced, held, delivery_rate, bounce_rate, period_start, period_end

Response headers:

  • Content-Disposition - Filename for download
  • Content-Type - text/csv or application/x-ndjson
get/usage/export

Query parameters

periodstring

Time period for export.

Shortcuts: this_month, last_month, last_30_days, etc.

Month format: 2024-01 (YYYY-MM)

Custom range: 2024-01-01..2024-01-15

format'csv' | 'jsonl'

Export format

status'active' | 'suspended' | 'archived'

Filter by tenant status

minSentinteger

Only include tenants with at least this many emails sent

timezonestring

Timezone for period calculations (IANA format)

Response

Usage export data

tenant_idstring required

Unique tenant identifier

tenant_namestring required

Tenant display name

external_idstring nullable

Your external ID for this tenant

status'active' | 'suspended' | 'archived' required

Current tenant status

sentinteger required

Total emails sent

deliveredinteger required

Emails successfully delivered

soft_failedinteger required

Emails that soft-failed

hard_failedinteger required

Emails that hard-failed

bouncedinteger required

Emails that bounced

heldinteger required

Emails currently held

delivery_ratenumber float required

Delivery rate (0-1)

bounce_ratenumber float required

Bounce rate (0-1)

Example response

[
  {
    "tenant_id": "cm6abc123def456",
    "tenant_name": "Acme Corp",
    "external_id": "acme_123",
    "status": "active",
    "sent": 10000,
    "delivered": 9700,
    "soft_failed": 100,
    "hard_failed": 50,
    "bounced": 100,
    "held": 50,
    "delivery_rate": 0.97,
    "bounce_rate": 0.015
  }
]