Usage
List usage for all tenants
Returns email usage statistics for all tenants in your organization. Results are paginated with page-based navigation.
Jobs to be done:
- Generate monthly billing invoices per tenant
- Build admin dashboards showing all customer usage
- Identify high-volume or problematic tenants
- Track usage against plan limits
Sorting options:
- sent, -sent - Sort by emails sent (ascending/descending)
- delivered, -delivered - Sort by emails delivered
- bounce_rate, -bounce_rate - Sort by bounce rate
- tenant_name, -tenant_name - Sort alphabetically by tenant name
Filtering:
- status - Filter by tenant status (active, suspended, archived)
- minSent - Only include tenants with at least N emails sent
Auto-pagination: SDKs support iterating over all pages automatically.
get/usage/tenants
Query parameters
periodstring
Time period for usage data. Defaults to current month.
Shortcuts: today, yesterday, this_week, last_week, this_month, last_month, last_7_days, last_30_days, last_90_days
Month format: 2024-01 (YYYY-MM)
Custom range: 2024-01-01..2024-01-15
pageinteger
Page number (1-indexed)
perPageinteger
Results per page (max 100)
sort'sent' | '-sent' | 'delivered' | '-delivered' | 'bounce_rate' | '-bounce_rate' | 'delivery_rate' | '-delivery_rate' | 'tenant_name' | '-tenant_name'
Sort order for results. Prefix with - for descending order.
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). Defaults to UTC.
Response
Paginated tenant usage statistics
Example response
{
"data": [
{
"tenantId": "cm6abc123def456",
"tenantName": "Acme Corp",
"externalId": "acme_123",
"status": "active",
"emails": {
"sent": 10000,
"delivered": 9700,
"soft_failed": 100,
"hard_failed": 50,
"bounced": 100,
"held": 50
},
"rates": {
"delivery_rate": 0.97,
"bounce_rate": 0.015
}
}
],
"page": 1,
"perPage": 50,
"total": 150,
"totalPages": 3,
"period": {
"start": "2024-01-01T00:00:00.000Z",
"end": "2024-01-31T23:59:59.999Z"
},
"summary": {
"totalTenants": 150,
"totalSent": 500000,
"totalDelivered": 485000
},
"meta": {
"requestId": "req_V1StGXR8_Z5jdHi6"
}
}