Rate limits and quotas

How request limits work#

Each rate-limited endpoint keeps a counter per credential, per method and exact path, over a fixed window:

• Per credential. Requests are counted against the API key (or OAuth token) that made them — not your IP address, and not your team. Two keys each get their own allowance.
• Per exact path. The path includes IDs, so POST /domains/dom_a…/verify and POST /domains/dom_b…/verify are counted separately, and so are POST /emails and its alias POST /emails/send.
• Fixed window. The window starts with the first request and resets completely when it ends; it doesn't slide. Most windows are one minute.
• Free plan runs at half rate. Teams on the Free plan (or with no subscription) get half of each limit, rounded down. Upgrading raises the limit within five minutes. If you need more than your plan gives, contact support — limits can be raised per team.

GET requests (lists and lookups) have no per-endpoint limit, except GET /contacts/export. Everything, reads included, is still subject to the edge limits.

Limits by endpoint#

Paths are relative to https://api.poststack.dev. Anything not listed has no per-endpoint limit.

Sending and content

Account, audience and configuration

POST /signup-forms/:id/submit is the public endpoint your website's form posts to, so it is counted per visitor IP address and is the same on every plan. /mcp is one counter for every MCP tool call made with that key.

Rate-limit headers#

Every response from a rate-limited endpoint carries three headers, whether or not the limit was hit:

HTTP/1.1 202 Accepted
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790676120

X-RateLimit-Limitinteger

Requests allowed in the current window for this key and endpoint — already halved on the Free plan.

X-RateLimit-Remaininginteger

Requests left in the window. 0 means the next one will be refused.

X-RateLimit-Resetinteger

When the window ends, as Unix time in seconds.

Retry-Afterinteger

Sent only on a rate-limit 429: seconds until the window ends.

Endpoints with no per-endpoint limit (most GETs) don't send these headers.

The 429 response#

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790676120
Retry-After: 38

{
  "error": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded"
}

The request was not processed — nothing was sent or changed — so it is always safe to repeat it after Retry-After seconds. Requests refused this way still count toward the window, so retrying in a tight loop keeps you limited until the window ends.

A 429 can also mean a sending quota was reached. Each has its own code and no Retry-After, and retrying it soon won't help. Branch on code, not on the error text:

In a POST /emails/batch response, an element refused by a quota carries the same code next to its error.

Over SMTP the same conditions come back as 451 (temporary), so a mail client or MTA retries on its own schedule.

Retrying#

• Honour Retry-After. Wait that many seconds, then send again. Add a little random jitter if many workers share a key so they don't all return in the same second.
• Pace instead of bursting. Spreading 60 sends across the minute never trips the limit; sending 60 in the first second and then waiting works too, but only if you actually wait.
• Tell a rate limit from a quota. Only rate_limit_exceeded has Retry-After. For the quota codes above, stop and alert a person.
• Make sends retry-safe. Put an idempotency_key on every send so a retry can never deliver twice — see Idempotency.

The TypeScript, Python and Go SDKs retry 408, 429 and 5xx responses up to 3 times by default, with full-jitter backoff starting at 250 ms. A rate-limit 429 waits its Retry-After instead (up to 60 seconds; longer is raised to your code with the wait on the error). A quota 429 — any of the codes above — is raised at once, never retried:

# -D - prints the response headers; read Retry-After from a 429
curl -sS -D - -o /dev/null -X POST https://api.poststack.dev/emails \
  -H "Authorization: Bearer $POSTSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d @email.json

import { PostStack, PostStackError } from '@poststack.dev/sdk';

// The SDK already waits out Retry-After (up to 60 s) on a rate-limit 429
// and throws quota 429s at once. This adds a longer, bounded retry on top.
const poststack = new PostStack(process.env.POSTSTACK_API_KEY!);

async function sendWithBackoff(input: Parameters<typeof poststack.emails.send>[0]) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await poststack.emails.send(input);
    } catch (err) {
      // Only a rate limit clears by waiting. monthly_limit_exceeded,
      // daily_limit_exceeded and send_limit_exceeded never do.
      const retryable =
        err instanceof PostStackError && err.code === 'rate_limit_exceeded';
      if (!retryable || attempt >= 5) throw err;
      await new Promise((r) => setTimeout(r, (err.retryAfter ?? 15) * 1000));
    }
  }
}

Edge limits#

In front of the API, the load balancer limits each client IP address, whatever credential it uses:

A request refused here gets a 429 with a small HTML body instead of JSON, and no rate-limit headers. Back off for a second or two. You are only likely to see this from many parallel workers behind one IP.

Request bodies over 36 MB are refused at the edge with 413. That ceiling sits above the attachment limits below so that a message within them is never cut off by it.

Sending quotas#

Monthly emails

Every accepted message counts once toward the calendar month (UTC), however many recipients it has. A batch of 100 counts 100. Test-mode sends and idempotent replays don't count.

Current usage is on the Settings → Billing page.

New-account external-recipient cap

To protect the shared sending IPs, a send with at least one recipient outside the domains your team has added counts against a daily cap. One send is one unit, no matter how many external recipients it has; it applies per team across all keys and SMTP, and test-mode sends are exempt.

The 24-hour window is fixed: it starts at the first counted send and the whole count resets when it ends.

Past the cap the 429 carries code: "daily_limit_exceeded" and its message states the cap that fired (10 in the first hour, 50 after).

SMTP mailboxes

Mail submitted over SMTP with a mailbox login (not an API key) is limited to 60 messages per hour per mailbox; past that the relay answers Rate limit exceeded. Try again later. Ten failed SMTP logins from one IP address or for one username within 15 minutes block further attempts for the rest of that window. SMTP sends authenticated with an API key have no per-message rate limit but count toward the same quotas as the API.

Account limits#

Per-request limits#

Limits on the size of a single send. Schema limits answer 400; the checks that run after validation answer 422. Both name the limit in error.

Troubleshooting#

Next steps