Usage
The workspace's plan, how many emails it has sent this period, what it costs so far, and why a send would be refused right now.
GET /v1/usage reports what the workspace is on, how much it has used, and — the field worth branching on — whether outbound sending is locked and why. Call it before a large batch or a campaign rather than discovering a limit halfway through, and read it when a send is refused so an agent can say what has to happen instead of surfacing a 402 as an unexplained failure. See Errors and the Campaigns guide.
The pricing model in one paragraph
One meter: outbound emails sent. Contacts are not metered, inbound replies are not metered, and transactional and marketing mail count the same. Free includes 3,000 outbound emails a month and stops there — nothing is charged and nothing is upgraded automatically. Standard has a $19 monthly minimum covering the first 50,000, then one graduated curve: $35 at 100,000, $109 at 250,000, $199 at 500,000, $379 at 1,000,000, $699 at 2,000,000, $999 at 3,000,000, and $0.50 per 1,000 between and beyond those points. There is no tier to choose: the rate that applies is whatever the curve says at the volume actually sent.
A verified payment method is required before any outbound email, including on Free and including a test send. It is never charged on Free.
The usage object
| Field | Type | Description |
|---|---|---|
object | "usage" | |
plan | "free" | "standard" | "enterprise" | "pro" | "scale" | The plan's id. A workspace with no subscription is on "free". pro and scale are the retired v1 plans, still reported for the workspaces on them. |
plan_name | string | Free, Standard or Enterprise. |
pricing_version | "v1" | "v2" | Which pricing generation this workspace is billed on. New workspaces are v2. |
unlimited | boolean | true for a staff-owned workspace, whose limits are lifted. included_emails and emails_remaining are then null, and sending_locked is always false. |
included_emails | integer | null | Free's monthly allowance, or the emails Standard's monthly minimum covers. On Standard it is not a ceiling: sending past it is priced, never refused. null when unlimited. |
emails_used | integer | Recipients sent in the current billing period. |
emails_remaining | integer | null | included_emails less emails_used. Goes negative on a metered plan, where it means nothing is blocked; it is not clamped. null when unlimited. |
period_start, period_end | date-time | The window the figures cover: the calendar month on Free, the Stripe subscription period on a paid plan, or the moment of the upgrade for the period it started. |
estimated_cents | integer | What this period costs so far, in US cents, on exactly the curve Stripe bills. Not projected to the end of the period. |
estimated | string | estimated_cents as dollars, for example $48.71. |
next_price_point | object | null | { emails, cents }: the next published volume and what the period costs there. null past the last one. |
payment_method | object | { present, required, brand, last4, verified_at }. |
budget | object | null | { cents, action, reached } when the workspace has set a monthly spend ceiling. action is pause_marketing (the default) or pause_all. |
sending_locked | boolean | true when every outbound send is refused for a billing reason. It stays false while a reached budget pauses marketing only: lock_reason is then budget_exceeded, a marketing send answers 402, and transactional mail still goes. Inbound mail is never affected. |
lock_reason | string | null | Why, named as the error type a send would answer with: payment_method_required, plan_limit_reached, billing_past_due or budget_exceeded. null when sending works. |
enterprise_suggested | boolean | true from the volume where a negotiated rate usually beats self-service (a million outbound emails a period). |
enterprise_from_emails | integer | That volume. Not a sending wall and not a plan change: the published curve keeps applying above it. |
estimated_at_period_end_cents | integer | This period's volume priced on the public self-service curve, for comparison with a quote. |
lock_reason uses the same vocabulary as the errors a send answers with, on purpose: a caller that branches on this field and a caller that branches on the 402 it received are handling the same condition. payment_method_required is the one no API caller can resolve — a person has to add a payment method in the dashboard.
Retrieve usage
GET /v1/usage · requires emails:read
Returns the usage object for the workspace the key belongs to. It takes no parameters.
emails_used counts each message the provider accepted, once per recipient across its to, cc and bcc (after any suppressed, opted-out or undeliverable addresses are dropped), from period_start. A message with one to address and a bcc of fifty counts as 51. Received mail counts zero, and a retry never counts twice. The count is folded in by a background job once a minute, which folds in at most 500 sent messages per pass, counted across all workspaces. A send made in the last minute may not be reflected yet, and during a large campaign or batch the figure can trail by much longer. Leave headroom rather than sending exactly emails_remaining.
For a staff-owned workspace, estimated_cents is still calculated from the normal curve, even though its limits are lifted and nothing is billed.
Example
Response
200 OK
A Standard workspace mid-period:
A Free workspace that has never had a payment method verified, so nothing can be sent at all: