PosthasteDocsGet an API key

Getting started

API conventions

Everything the endpoints have in common: where to send a request, what an identifier looks like, and the four response shapes you will ever see.

Base URL

https://api.posthastemail.dev

HTTPS only. Every path in this reference is relative to it, and every path begins with /v1/. There is no other version; when there is, this one will keep working.

Request bodies are JSON and capped at 25 MB. Anything larger is refused before it is buffered. text and html are still each capped at 5,000,000 characters — see send an email — the rest of the ceiling is headroom for base64-encoded attachments, which run about a third larger than the raw bytes they carry. Send content-type: application/json on anything with a body.

Response shapes

# A single object
GET /v1/messages/msg_AZLm3kQ8T2Sf9pXbNc7HrQ
200 { "id": "msg_AZLm3kQ8T2Sf9pXbNc7HrQ", "status": "delivered", … }

# A short list — everything the account has, no cursor
GET /v1/domains
200 { "data": [ … ] }

# A paginated list — see /docs/conventions#pagination
GET /v1/messages?limit=25
200 { "data": [ … ], "hasMore": true, "nextCursor": "msg_…" }

# An error
POST /v1/emails
422 { "error": { "type": "domain_not_verified", "message": "…" } }

# Nothing to return
DELETE /v1/webhooks/whk_4Rm8Ub2Xc6Ye0Zf1Ag3Bhk
204

Every list is under data, without exception. That is worth relying on: it means one helper can read any list rather than one per endpoint. Lists that can grow without bound also carry hasMore and nextCursor — see pagination, and in particular which of the two to loop on.

Every error is under error, with a machine-readable type and a message written for a human reading a log at 2am. Some validation failures add a fields array; a few errors add their own numbers, such as limit and sentToday. See errors.

Identifiers

The API never exposes a bare UUID. Every id is a prefix, an underscore, and exactly 22 base64url characters — the raw 16 bytes of a UUIDv7, so ids also sort by creation time.

msg_AZLm3kQ8T2Sf9pXbNc7HrQ
└─┬┘ └──────────┬─────────┘
  │             └── 22 base64url characters: [A-Za-z0-9_-]
  └── what it is

Treat them as opaque strings of at most 30 characters and store them as text. An id of the wrong kind is rejected before any query runs, so passing a domain id where a message id belongs returns 404 not_found rather than reading the wrong row.

PrefixObject
acct_Account
usr_User
key_API key
dom_Sending domain — and inbound addresses, which have no prefix of their own
msg_Message, sent or received
evt_Message event, as delivered by a webhook
sup_Suppression list entry
whk_Webhook endpoint
dlv_Delivery job
sub_Subscription
pay_Payment
inv_Invoice

Inbound addresses carry a dom_ prefix, not one of their own. So DELETE /v1/inbound/addresses/dom_… is correct and not a typo. It is the one place the prefix does not name the thing, and passing an inbound address id to a domain endpoint will decode successfully and then find nothing.

Times, and the one time zone

Timestamps are ISO 8601 in UTC — 2026-08-18T06:40:11.902Z. Quotas and usage periods are also UTC: the daily sending cap resets at midnight UTC and the monthly allowance at the first of the month UTC, wherever you are.

The one exception is deliberate. GET /v1/stats/messages takes a tz parameter, because somebody in Sydney sending at 9am local is sending at 11pm UTC the previous day, and bucketing that under the wrong date makes every daily total wrong.

Methods and status codes

CodeMeaning here
200A read succeeded — or a send was a duplicate, which is also success.
201Something was created and is returned in the body.
202A message was accepted: durably stored and queued, not yet delivered.
204Deleted. No body.
400The request is malformed. Fix it; retrying will not help.
401 / 403Credential rejected, or the credential lacks the scope. See authentication.
404No such object — including one belonging to another account, which is invisible rather than forbidden.
409A conflict with something that already exists.
422The request is well-formed and we will not act on it. The distinction from 400 matters to a client deciding whether the fix is in the request or in the account.
429A limit. Read error.type to learn which — see rate limits and sending limits.
503/health/ready only, when the database is unreachable.

Calling it from a browser

You should not. An API key in a browser is a published API key. The dashboard reaches the same endpoints with a session cookie from an allowlisted origin; there is no wildcard CORS policy, and an origin that is not on the allowlist gets no access-control header at all.

Server-to-server callers are unaffected by any of this — CORS is a browser mechanism, and nothing else consults it.

Idempotency

A request whose response you never saw is the hardest case in any API: the message may have been accepted, or not, and there is no way to tell from the outside. An idempotency key makes retrying that request free.

It is a body field, not a header

The Idempotency-Key HTTP header is never read. It appears in our CORS allowlist, so a browser will happily send it and nothing will complain — and it has no effect whatsoever. A retry carrying only the header sends a second email.

This is worth stating plainly because Stripe, and much of the ecosystem trained on it, put idempotency in a header. Here it is idempotencyKey in the JSON body of POST /v1/emails, and nowhere else.

How it behaves

# First call
POST /v1/emails
{ "from": "…", "to": "…", "text": "…", "idempotencyKey": "invoice-2026-114" }

202 { "id": "msg_AZLm3kQ8T2Sf9pXbNc7HrQ", "status": "queued" }

# Same key again — no second message is sent
POST /v1/emails
{ "from": "…", "to": "…", "text": "…", "idempotencyKey": "invoice-2026-114" }

200 { "id": "msg_AZLm3kQ8T2Sf9pXbNc7HrQ", "status": "duplicate" }
PropertyValue
WhereidempotencyKey, a string in the request body. 1–255 characters.
Which endpointsPOST /v1/emails only. No other endpoint accepts one.
ScopePer account. Two accounts may use the same key without interfering; two keys within one account never collide.
First use202 · { id, status: "queued" }
Replay200 · { id, status: "duplicate" } — the id of the original message.
LifetimeAs long as the message record it belongs to. There is no short expiry window to race against, and equally no point at which a key becomes safe to reuse for a different message.

200 and 202 are both success. A client that only accepts 202 will read its own successful retry as a failure and retry again — which is exactly the loop idempotency exists to break. Branch on res.ok, and use status only for logging.

The check runs before any other work: before the domain lookup, before suppression, before quota. A replay is therefore cheap, is not billed, does not consume any part of your daily cap or monthly allowance, and produces no second delivery record.

The key matches on the key alone

The message body is not part of the comparison. Reusing a key with different content returns 200 duplicate and the id of the original message — the new content is discarded silently, and there is no error to notice.

So a key must identify one specific message, not a customer, a template or a day. invoice-2026-114-reminder-2 is a good key. customer-8842 is a key that will one day swallow a password reset.

Derive keys from something in your own database that is already unique per message — a row id, or an entity id combined with a counter. Random keys generated per attempt are worse than none: they are unique per retry, so they guarantee duplicates rather than preventing them.

The retry pattern

Decide the key before the first attempt and reuse it for every retry of that message, including retries in a later process after a crash.

// A send that is safe to retry, because the key is decided BEFORE the
// first attempt and reused by every one of them.
async function sendInvoiceEmail(invoice) {
  const key = `invoice-${invoice.id}-reminder-${invoice.reminderCount}`

  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const res = await fetch('https://api.posthastemail.dev/v1/emails', {
        method: 'POST',
        headers: {
          authorization: `Bearer ${process.env.POSTHASTE_KEY}`,
          'content-type': 'application/json',
        },
        body: JSON.stringify({
          from: '[email protected]',
          to: invoice.customerEmail,
          subject: `Invoice ${invoice.number}`,
          text: renderInvoiceEmail(invoice),
          idempotencyKey: key,
        }),
      })

      // 202 queued and 200 duplicate are BOTH success. Treating 200 as a
      // failure and retrying is the loop this exists to break.
      if (res.ok) return res.json()

      // 4xx other than 429 will never succeed. Stop.
      if (res.status < 500 && res.status !== 429) {
        throw new Error(await res.text())
      }
    } catch (err) {
      if (attempt === 4) throw err
    }

    await sleep(2 ** attempt * 1000)
  }
}

Retry on a timeout, a connection error, any 5xx, and 429 after the interval the response asks for. Do not retry any other 4xx — those describe a request that will fail identically for ever. See errors.

The other direction

Webhook deliveries carry their own idempotency, from us to you: Posthaste-Delivery-Id is stable across every retry of the same event. Deduplicate on it, and your handler can be as safely retried as your sends are. See webhooks.

Pagination

Every list is paginated with a keyset cursor: ask for a page, get a cursor back, ask for the next page from that cursor. There are no page numbers and no offsets. Nothing on this API returns a list whole, so a response is never evidence that you have seen everything.

How it works

GET /v1/messages?limit=50

{
  "data": [ … 50 messages, newest first … ],
  "hasMore": true,
  "nextCursor": "msg_AZLm3kQ8T2Sf9pXbNc7HrQ"
}

GET /v1/messages?limit=50&before=msg_AZLm3kQ8T2Sf9pXbNc7HrQ
FieldNotes
limitRequest parameter. Bounds and defaults are per-endpoint and are given in the table below — they are not uniform, and the default is never the maximum except on /v1/domains.
beforeRequest parameter. The nextCursor from the previous page. It is the id of the last row you received, so the next page resumes at the row immediately after it. An id of the wrong kind returns 400 invalid_request. /v1/billing/history uses after instead — see below.
dataThe rows, newest first — except on /v1/billing/history, which is oldest first.
hasMoreWhether another page exists. Sent by three endpoints, not by all of them. Where it is present it is authoritative; where it is absent, reading it gives you undefined rather than an error.
nextCursorThe cursor to pass as before next time. Sent by every list. null means there is no next page on every endpoint except /v1/inbound/messages — see below.

Keyset rather than OFFSET for two reasons. Offset gets slower the deeper you page, and on a table that grows by every send it also skips and repeats rows when new messages arrive mid-scan — quiet duplicates that nothing about the result would reveal. The cursor compares the (created_at, id) pair, so a hundred messages written in the same millisecond page correctly rather than all but one being skipped at the boundary.

Check both signals, and neither on its own

Two endpoints break the obvious loop, in opposite directions. Whichever single field you pick as your stopping rule, one of them defeats it — so the correct loop reads both, and the two paragraphs below are why.

while (cursor != null) never terminates on GET /v1/inbound/messages. Any page with at least one row gets a cursor there, whether or not there is anything after it — so the loop asks for the page after the last one, receives an empty page carrying the same cursor, and spins. It terminates fine everywhere else, which is what makes it the kind of bug that passes every test written against the other endpoints.

if (!page.hasMore) return stops after ONE page on six of the nine lists. /v1/domains, /v1/webhooks, /v1/api-keys, /v1/inbound/addresses, /v1/billing/invoices and /v1/billing/history send no hasMore at all. Reading it yields undefined, which is falsy, which is indistinguishable from that was everything. Nothing errors and nothing is logged; you simply get the first page and believe it is the whole list. Compare with === false, not for truthiness.

import { Posthaste } from '@posthaste/sdk'

const posthaste = new Posthaste({ apiKey: process.env.POSTHASTE_KEY })

// One page, exactly as the endpoint returns it.
const page = await posthaste.messages.list({ limit: 50, status: 'bounced' })
page.data        // MessageSummary[]
page.hasMore     // sent by this endpoint; authoritative where it is sent
page.nextCursor  // pass as `before` on the next request

// Every page. autoPaginate consults both signals for you, so both traps below
// are closed by construction — it also stops on an empty page and on a cursor
// that fails to advance.
for await (const message of posthaste.messages.autoPaginate({ status: 'bounced' })) {
  await suppress(message.to)
}

// Or collect, with a ceiling you choose rather than an unbounded drain.
const recent = await posthaste.messages.listAll({ status: 'bounced' }, 500)

// Every list has the same three methods, including the ones that send no
// hasMore. This is all sixty invoices, not the first fifty.
const invoices = await posthaste.billing.listAllInvoices()

for await (const key of posthaste.apiKeys.autoPaginate()) {
  await audit(key)
}

// Billing history pages by `after` and reads oldest first. The helper knows.
for await (const event of posthaste.billing.autoPaginateHistory()) {
  await record(event.seq, event.type)
}

Checking both — stop when hasMore is explicitly false, or when the cursor is null — costs nothing and is correct against every endpoint, present and future. Each check is the only correct stop on some endpoint, and each is wrong on its own somewhere else. The TypeScript SDK does exactly that inside autoPaginate, so there is no loop to get wrong.

Every list paginates

There is no longer any endpoint that returns a list whole. What differs between them is the page size, whether hasMore is sent, and — on one endpoint — the name and meaning of the cursor.

EndpointlimitCursorhasMoreNotes
/v1/messages1–100, default 25beforeYesnextCursor is null on the last page.
/v1/suppressions1–200, default 50beforeYesnextCursor is null on the last page.
/v1/inbound/messages1–100, default 25beforeYesCursor is non-null on the last page. Stop on hasMore here.
/v1/domains1–100, default 100beforeNoThe only endpoint whose default is its maximum, so the first page is every domain on all but the largest accounts. Past a hundred, follow the cursor.
/v1/webhooks1–100, default 50beforeNoStop when the cursor is null.
/v1/api-keys1–100, default 50beforeNoRevoked keys are listed too and count towards the limit.
/v1/inbound/addresses1–100, default 50beforeNoStop when the cursor is null.
/v1/billing/invoices1–100, default 50beforeNoStop when the cursor is null.
/v1/billing/history1–200, default 100afterNoOldest first, and the cursor is a sequence number. See below.

The six lists without hasMore truncate silently if you ignore the cursor. There is nothing in the response that says a page is partial — no flag, no count, no header. An account with sixty invoices that reads only data gets fifty of them and no indication that ten are missing, and the same is true of the fifty-first API key, webhook or inbound address. Read nextCursor on every one of them, even when you expect the list to be short.

/v1/billing/history is the exception

It is the one list on the API that reads forward, and it does not use before at all. Both differences follow from what it is: the billing history is a hash chain, a chain is verified from its start, and a record that renders in a different order than it verifies in is a record people stop trusting. So the events come back oldest first, and you resume with after.

Every other list/v1/billing/history
OrderNewest firstOldest first
Cursor parameterbeforeafter
What the cursor isA prefixed row id, e.g. inv_…A sequence number — the seq of an event
MeaningRows sorting after the named rowEvents whose seq is strictly greater
limitCaps at 100, or 200 for suppressions1–200, default 100
GET /v1/billing/history?limit=100

{
  "chain": { "valid": true, "brokenAt": null, "reason": null },
  "nextCursor": "100",
  "data": [ … 100 events, OLDEST first, seq 1 … 100 … ]
}

# "100" is a sequence number, not an id. Read it forward:
GET /v1/billing/history?limit=100&after=100

nextCursor is that sequence number rendered as a string, so passing it straight back as after is correct — and it is null on the last page, which is the stopping condition since there is no hasMore here either. Passing an id rather than a number is refused with 400 invalid_request.

chain travels with every page and is the verification of the whole account history, not of the page you are holding — so it means the same thing on page four as on page one, and paging through the record does not weaken the guarantee it makes.

What a cursor guarantees

Rows are ordered newest first, and a cursor is a position in that order — so a page you fetch after new rows have arrived does not shift under you, because the new rows sort ahead of where you are reading. Walking a list to its end therefore gives you a consistent snapshot backwards in time, not a consistent snapshot of the whole list.

/v1/billing/history reads the other way, and gains something for it: because it walks forward from a sequence number, new events land ahead of your cursor rather than behind it. Resuming from the last seq you processed picks up everything since, which is what makes it the one list you can poll incrementally without re-reading what you already have.

Cursors are just ids — or, on the billing history, sequence numbers — and do not expire. Storing one to resume a sync later is a legitimate use: pass the newest id you have already processed as before when you resume, or filter on from if you would rather bound by time.

Rate limits

1,200 requests per 60 seconds, counted per API key, across every endpoint. This is not a billing control — it protects the service from a client stuck in a retry loop, and caps the damage a leaked key can do before anybody notices.

What it counts

PropertyValue
Limit1,200 requests
Window60 seconds, sliding
Counted againstThe API key id — the twelve characters after the prefix. Not your IP, and not your account: two keys on one account get 1,200 each.
ScopeEvery /v1/ endpoint together, reads and writes alike. There is no per-endpoint budget.
Unauthenticated requestsCounted against the source IP instead, since that is the only identity such a request has. This is what bounds brute force against key ids.
Exempt/health, /health/ready and /status. Limiting a health check turns a traffic spike into a container restart loop; limiting the status feed would start refusing people at the exact moment they came to find out what was wrong.

Keying on the API key rather than the IP is deliberate: customers are servers, so an IP is frequently shared by everyone behind one NAT and is meaningless as an identity — while a stolen key should be bounded on its own regardless of where it is used from.

What a 429 looks like

HTTP/1.1 429 Too Many Requests
retry-after: 37
x-ratelimit-limit: 1200
x-ratelimit-remaining: 0
x-ratelimit-reset: 37

{
  "error": {
    "type": "rate_limited",
    "message": "Too many requests. The limit is 1200 per 60 seconds for this API key.",
    "retryAfterSeconds": 37
  }
}
HeaderMeaning
retry-afterSeconds until the window frees up. Present only on a 429.
x-ratelimit-limitThe ceiling for this window. Sent on successful responses too.
x-ratelimit-remainingHow many requests are left. Watch this and slow down before you hit zero, rather than discovering the limit from an error.
x-ratelimit-resetSeconds until the counter resets.

The body carries error.retryAfterSeconds, the same number as the header, so a client that only parses JSON does not have to reach for headers.

It is not a sending quota

Three different limits return 429. Read error.type before deciding what to do, because the right response to each is completely different.

TypeMeansDo
rate_limitedToo many HTTP requests in the last minute.Wait the stated seconds and retry in process.
daily_limit_reachedYour account’s daily sending cap.Stop sending today. Retry-After points at midnight UTC.
monthly_limit_reachedYour plan’s monthly allowance.Upgrade, or wait for the 1st. Do not hold a connection open for that.

Handling it

// Honour retry-after rather than guessing. Retrying sooner is counted
// against the same window and simply extends it.
async function request(path, init, attempt = 0) {
  const res = await fetch(`https://api.posthastemail.dev${path}`, init)

  if (res.status !== 429 || attempt >= 3) return res

  const type = (await res.clone().json().catch(() => null))?.error?.type

  // Only the request limit is worth retrying in-process. A daily or monthly
  // sending cap means waiting hours or weeks — that belongs in a queue,
  // not in a loop holding a connection open.
  if (type !== 'rate_limited') return res

  const wait = Number(res.headers.get('retry-after') ?? 1)
  await sleep(wait * 1000 + Math.random() * 250) // jitter
  return request(path, init, attempt + 1)
}

Add jitter. A fleet of workers that all retry after exactly the stated interval arrives together and trips the limit again in lockstep, which is how a brief throttle becomes a sustained one.

If 1,200 a minute is genuinely not enough for what you are doing, the usual answer is fewer, larger requests — a list with limit=100 rather than a hundred single-object fetches — or a second key for the workload that needs its own budget. Talk to us if neither fits.

When the limiter is unavailable

The counter is shared across API containers through Redis, so the limit is a single budget rather than one per running process. If Redis is unreachable the limiter is skipped rather than failing requests: an outage in a protective layer must not take down the thing it protects.

Which means an absent x-ratelimit-remaining header is not a promise that nothing is being counted. Do not build a client that depends on the header being there.

Sending limits

Three ceilings govern how much mail you can send, and they are independent. Your plan sets a monthly allowance. Your account’s sending history sets a daily cap. Underneath both, the platform itself has a daily ceiling on everything it sends from its shared IP. All three return 429, and the error.type tells you which one you hit.

Your monthly allowance

Each plan includes a number of messages per calendar month, counted in UTC. It counts accepted messages only: a send we refuse was never attempted, so it is never billed and never counted.

PlanMessages a monthRecord retention
Free75030 days
Starter100,00090 days
Growth300,000365 days
Scale1,000,000730 days

Exceeding it returns 429 with "type": "monthly_limit_reached" and a Retry-After pointing at the start of next month rather than at midnight. Moving to a larger plan lifts the ceiling immediately — there is nothing to wait for.

What else your plan caps

Volume is the limit most people meet, and it is not the only one. Everything the account can hold is capped too — templates, message streams, inbound addresses, seats, sub-accounts — along with how far back delivery analytics may look. Each is refused with 403 and its own error.type, carrying limit and used so a client can show “8 of 10” without parsing a sentence.

LimitFreeStarterGrowthScaleEnterprise
Emails a month750100,000300,0001,000,0001,000,000
Sending domains1UnlimitedUnlimitedUnlimitedUnlimited
Record history30 days90 days1 year2 years2 years
Schedule ahead1 day3 days7 days14 days21 days
Templates325100UnlimitedUnlimited
Message streams (incl. transactional)131025Unlimited
Inbound addressesNot included10502502,000
Emails received a monthNot included50,000200,000750,000Unlimited
Verification codes a month1005,00025,000100,000100,000
Address checks a month25010,00050,000250,000250,000
Webhook endpoints131025Unlimited
API keys51540150Unlimited
Contacts5005,00050,000250,000Unlimited
Contact lists21050UnlimitedUnlimited
Team seats1310UnlimitedUnlimited
Sub-accountsNoneNone525Unlimited
Delivery analytics window7 days30 days90 days90 days90 days

The message-stream figure includes the stream you already have. Every account is created with a transactional stream, and it counts against the allowance — so a plan listing one stream is a plan on which POST /v1/streams refuses, by design. A stream is a suppression boundary, and an extra one is an extra way to keep mailing somebody who complained.

Enterprise figures are a floor. A negotiated agreement is stored per account and can raise any of them; it can never lower one below the published tier.

Your account’s daily cap

A new sending account has no history, and volume that appears out of nothing looks exactly like a compromised host to a receiving provider. So capacity is earned rather than granted. Every account starts at 50 messages a day and climbs one rung at a time, roughly doubling, over 10 rungs to a ceiling of 100,000 a day. Roughly doubling is the shape receivers are used to seeing from a business growing into its volume; a jump is the shape they filter.

RungDaily cap
050
1200
2500
31,000
42,500
55,000
610,000
725,000
850,000
9100,000

How the cap moves

The review runs once a day, on your first send after midnight UTC, and looks only at the day before. It moves the cap by at most one rung in either direction.

  • Up a rung after a day where you used at least 80% of your current cap, with a complaint rate at or under 0.1% and a bounce rate at or under 5%.
  • Down a rung after a day where complaints passed 0.3% or bounces passed 10%.
  • Held otherwise — including every idle day. Capacity is earned with real volume, not with time, or an account sending five messages a day would reach the top of the ladder in a fortnight with no reputation at all.

The complaint rate is the governor, not the calendar. The 0.3% figure is Gmail’s threshold, not ours — we stop growing and start shrinking well before a receiver would act on it. The step-up bar is deliberately stricter than the step-down bar: earning more volume should require a clean day, losing it should not require a disastrous one.

The review is hung off the send path rather than a scheduler on purpose. A cap that only moves when a cron job happens to be alive is a cap that silently stops adapting the first time that job dies.

The platform’s own daily ceiling

The ladder above is per account, and it cannot see the number a receiver actually forms an opinion about. Everyone’s mail leaves from one IP and one sending domain, so what Gmail and Microsoft judge is the total — not any one tenant’s share of it. Ten new accounts each entitled to a full first rung is ten times the first-day volume the warmup schedule promises, from an address with no history to spend.

So there is a second ceiling underneath yours: a cap on what the platform as a whole accepts in a UTC day, checked on every send after your own two limits. When it is reached, sends are refused with 429 and "type": "platform_paused" until the day rolls over or we raise the number.

platform_paused is not about your account, and it carries no account numbers — none of them are the reason. Nothing is wrong, nothing is lost, and no plan change affects it. Its Retry-After is short — 300 seconds — rather than a calendar boundary, because capacity frees up as the day’s total drains and as we lift the ceiling by hand; neither is a clock you could compute. Treat it as throttling to come back from, not as quota to alert on.

The number is raised deliberately, by us, as the IP earns reputation — not automatically on a timer. It is conservative on purpose: it is the one limit protecting the asset every account on the platform depends on.

What a 429 looks like

# 429
{
  "error": {
    "type": "daily_limit_reached",
    "message": "This account has sent its daily limit of 1000 messages. …",
    "limit": 1000,
    "sentToday": 1000
  }
}
# retry-after: 32219   (seconds until midnight UTC)

# 429
{
  "error": {
    "type": "monthly_limit_reached",
    "message": "This account has used its monthly allowance of 750 messages …",
    "limit": 750,
    "sentThisMonth": 750
  }
}
# retry-after: 1039821   (seconds until the 1st, UTC)

# 429 — ours, not yours. Carries no account numbers, because none of them
# are the reason.
{
  "error": {
    "type": "platform_paused",
    "message": "We are holding sending briefly while this platform warms up …"
  }
}
# retry-after: 300   (a few minutes, not a calendar boundary)

Nothing over a cap is queued and delivered later. A refused message was never accepted, so it does not appear in your usage figures and is not billed.

A fourth kind of 429 exists and is unrelated to volume entirely: the request rate limit, type rate_limited. Branch on error.type, never on the status code alone — the four need four different responses.

Checking before you hit it

You do not have to wait for a 429 to find out where you stand. GET /v1/me returns sending.dailyLimit, sending.sentToday, sending.remainingToday, sending.warmupTier, sending.sentThisMonth and sending.remainingThisMonth.

GET /v1/usage returns the current period’s totals with the daily series behind them, so you can see which days produced a number rather than taking it on trust. Those counters are derived from the delivery record itself, not tallied separately, which is why they cannot drift from what actually happened.

The shared sending IP

Everything above is per account. Underneath it, the IP your mail leaves from is shared, and it is young — inbox placement is still being established. That is why the ladder is deliberately conservative and why bulk marketing mail is refused outright: on shared infrastructure one bad list damages placement for everybody on it. A broadcast to your own users is sent one message per recipient, and every one of those messages spends the same daily cap and monthly allowance as a single send.

See deliverability for what we can and cannot promise about placement.

NextSending domains →Publish one DKIM record, verify it, and read the per-record check results.