Skip to main content
Get Started
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.billing.usage();
console.log(result);
{
  "workspace_id": "wsk_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "tier": "<tier>",
  "tier_status": "<tier_status>",
  "period_start": "2026-10-04T12:00:00.000Z",
  "period_end": "2026-10-04T12:00:00.000Z",
  "usage": {
    "sends": 0,
    "parses": 0,
    "inbound_skipped": 0,
    "webhook_deliveries": 0,
    "sends_cost_usd": 0,
    "parses_cost_usd": 0
  },
  "caps": {
    "monthly_sends": 0,
    "monthly_parses": 0,
    "agents": 0,
    "hourly": 0,
    "daily": 0,
    "hourly_inbound": 0,
    "daily_inbound": 0
  }
}

Get current usage

Returns metered usage for the current billing period plus the workspace's tier caps.
GET/v1/billing/usagescope · read
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.billing.usage();
console.log(result);
{
  "workspace_id": "wsk_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "tier": "<tier>",
  "tier_status": "<tier_status>",
  "period_start": "2026-10-04T12:00:00.000Z",
  "period_end": "2026-10-04T12:00:00.000Z",
  "usage": {
    "sends": 0,
    "parses": 0,
    "inbound_skipped": 0,
    "webhook_deliveries": 0,
    "sends_cost_usd": 0,
    "parses_cost_usd": 0
  },
  "caps": {
    "monthly_sends": 0,
    "monthly_parses": 0,
    "agents": 0,
    "hourly": 0,
    "daily": 0,
    "hourly_inbound": 0,
    "daily_inbound": 0
  }
}

A key tied to one agent cannot read it (403 insufficient_scope): usage and costs are counted for the whole workspace, and GET /v1/metrics counts that agent's mail.

Response

workspace_idstring

Your workspace id (wsk_…).

tierstring

Your plan: free, pro, scale or metered, or an older plan, outbound or outbound_pro. While a payment is past due, caps are Free's whatever this says.

tier_statusstring

active, or past_due after a failed renewal payment: the workspace then has Free plan limits until the payment goes through. canceled and paused refuse every send, with 402 subscription_canceled and payment_required.

period_startstring

Start of the usage period: the first day of this month, 00:00 UTC. The counts in usage start over each month.

period_endstring

End of the usage period, exclusive: the first day of next month, 00:00 UTC.

usageobject

This period's counts.

Show propertiesHide properties
sendsinteger

Recipients sent to this period: each live message counts once per to, cc and bcc address, and test sends do not count. caps.monthly_sends limits it.

parsesinteger

Received emails processed this period, which caps.monthly_parses limits. Mail kept or dropped over a limit counts in inbound_skipped instead.

inbound_skippedinteger

Received emails not processed this period: kept unclassified because the monthly allowance was used up or the subscription is inactive, or dropped unstored in a flood past hourly_inbound or daily_inbound.

webhook_deliveriesinteger

Webhook deliveries your endpoints accepted with a 2xx answer this period. Test deliveries are not counted.

sends_cost_usdnumber

Estimated cost of delivering this period's sends, at $0.0001 per recipient. It is not what your plan charges.

parses_cost_usdnumber

Estimated cost of classifying this period's received mail. Like sends_cost_usd, it is not what your plan charges.

capsobject

The limits of the plan the workspace is held to now: its own, or Free's while a payment is past due.

Show propertiesHide properties
monthly_sendsinteger | null

Recipients the workspace may send to in a month, each live message counted once per to, cc and bcc address; past it, a send gets 429 monthly_limit_exceeded (free_tier_exceeded on Free limits). Null when the plan has no monthly limit.

monthly_parsesinteger | null

Received emails processed in a month; past it, mail is still stored but not classified, and counts in inbound_skipped. Null when the plan has no monthly limit.

agentsinteger | string

How many agents the plan allows, or the string unlimited. Past it, POST /v1/agents gets 402 resource_cap_exceeded.

hourlyinteger

Recipients the workspace may send to in any rolling hour, counted like monthly_sends: once per to, cc and bcc address. Mail scheduled for later counts from when it was accepted; mail that was canceled or refused does not count. Past it, a send gets 429 hourly_limit_exceeded. Test sends do not count.

dailyinteger

Recipients the workspace may send to in any rolling 24 hours, counted as hourly is. Past it, a send gets 429 daily_limit_exceeded. Test sends do not count.

hourly_inboundinteger

Received emails stored in any rolling hour. Past it, more mail is dropped without being stored, and counts in inbound_skipped.

daily_inboundinteger

Received emails stored in any rolling 24 hours. Past it, more mail is dropped without being stored, and counts in inbound_skipped.

Was this page helpful?