API reference

Get usage

GET/v1/usage

Read your account's plan and how much of it you've used — sends this month and today, plus your domain and webhook allowances.

Why use this

Without this, the first your application learns about its own monthly cap is a 429 partway through a run it has already started — half the batch delivered, half refused, and no clean way to resume. Reading the allowance beforehand turns that into a decision you get to make.

For example

Before a nightly digest run to 8,000 users, you check the remaining monthly allowance and either send, or alert your team that the plan needs raising first.

Example

import { YourMail } from "yourmail";

const yourmail = new YourMail(process.env.YOURMAIL_API_KEY!);

const usage = await yourmail.usage();

// A null limit means unlimited on this plan.
const remaining =
  usage.month.limit === null
    ? Infinity
    : usage.month.limit - usage.month.count;

if (remaining < recipients.length) {
  throw new Error(`Only ${remaining} sends left this month`);
}

const res = await fetch("https://api.yourmail.dev/v1/usage", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});

const usage = await res.json();

curl "https://api.yourmail.dev/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

// 200 OK
{
  "plan": "pro",
  "month": { "count": 12480, "limit": 50000 },
  "day": { "count": 913, "limit": 5000 },
  "domains": { "count": 3, "limit": 10, "suspended": 0 },
  "webhooks": { "count": 2, "limit": 10, "suspended": 0 }
}

These are the same figures the dashboard shows on Billing and in the sidebar plan chip — they come from one query, so the two can never disagree.

planstring: The account's current plan.
monthobject: Sends this calendar month, against the plan's monthly allowance.
dayobject: Sends today, against the plan's daily allowance.
domainsobject: Custom sending domains in use, against the plan's allowance.
webhooksobject: Webhook endpoints in use, against the plan's allowance.
*.countnumber: How much of the allowance is currently used.
*.limitnumber | null: The ceiling for this plan. null means unlimited — check for it before subtracting.
*.suspendednumber: Domains or webhooks parked by a downgrade. They still occupy a slot but cannot be used until the plan is raised again, or until you swap one for an active row. Non-zero means part of your setup is not currently working.

Errors

Reading account usage requires a full-access key. A send-only key is issued so it can be handed to something that only sends, and your billing posture isn't that — see Errors for the full error shape.

401authentication_error

API key missing, malformed, or not recognised

403authentication_error

The key is send-only; reading account usage requires a full-access key