Charchy Senddocs

Rate limits and quotas

Requests per second, emails per day, and the headers that tell you where you stand.

Three limits, each with its own code:

LimitHow muchWhen you pass it
Requests10 a second per workspace, bursts of 20429 rate_limit_exceeded
Emails a dayYour workspace's daily cap429 daily_limit_reached
Emails you've paid forYour plan's emails, then your credits402 insufficient_balance

Headers

HeaderWhenMeaning
x-request-idEvery responseThis request's id. Quote it to support.
ratelimit-limitWhen the request counted against your rate limitThe burst size: 20.
ratelimit-remainingWhen the request counted against your rate limitRequests you can make right now.
ratelimit-resetWhen the request counted against your rate limitSeconds until the burst is full again.
x-charchy-emails-remainingSends, cancels and GET /v1/usageEmails left to spend: your plan's emails plus your credits.

429, 409 idempotency_in_flight and 503 sending_unavailable carry Retry-After, in seconds. Wait at least that long.

Check where you stand

GET /v1/usage returns all of this for your workspace. Any key may call it, including a sending-only key:

import { CharchySend } from "@charchy/send"

const send = new CharchySend() // reads CHARCHY_SEND_KEY

const { data, error } = await send.usage.get()
{
  "plan": {
    "key": "growth",
    "emails_included": 50000,
    "emails_used": 12840,
    "emails_left": 37160,
    "term_ends_at": "2026-12-14T09:00:00.000Z"
  },
  "credits": { "emails": 25000, "expires_at": "2027-02-10T00:00:00.000Z" },
  "daily": { "cap": 5000, "surge_cap": 10000, "used": 612, "resets_at": "2026-11-17T08:00:00.000Z" },
  "rate_limit": { "requests_per_second": 10, "burst": 20 },
  "test": { "daily_cap": 1000, "used": 37 }
}
  • plan is null without a plan term; credits is null with no credits.
  • daily.cap is the cap in force today, whichever rule below sets it.
  • daily.surge_cap is the most you can send today while healthy (surge allowance); the same as cap when there is none.
  • daily.resets_at is when your count next goes down (the day is a rolling 24 hours): at surge_cap, when there is room for one more; under it, when the oldest counted emails leave the 24 hours.

Call it from a daily health check to get alerted before daily_limit_reached or insufficient_balance happens.

Requests per second

10 requests a second per workspace, all keys together, bursts up to 20. A batch of 100 emails is one request.

Daily caps

A daily cap stops one mistake — a loop, a leaked key — from sending a flood. Caps count recipients over a rolling 24 hours, not a calendar day. A request that would pass the cap is refused whole, with Retry-After saying when there is room.

Emails a day
Before your workspace is approved (your team's addresses only)50
First 7 days after your first live email500
Starter plan2,500
Growth plan5,000
Pro plan10,000
Scale plan25,000
Credits only, no plan2,500
Test keys and magic addresses1,000 (free, counted separately)

Surge allowance. On a busy day — a launch, a sign-up rush — a plan or credits-only workspace can send up to twice its cap while its last 7 days stay healthy (hard bounces under 2%, spam complaints under 0.05%, or too little mail yet to judge), so your sign-in codes keep arriving. Not before approval or in the first 7 days. Every email is still paid for. daily_limit_reached comes at twice the cap, not at the cap.

Until a workspace on credits only has 30 days of live sending with no automatic pause, its cap and surge are also held to about 10% of the platform's daily volume. A plan's cap is never lowered by this. An automatic pause restarts those 30 days.

GET /v1/usage always shows the cap that applies (daily.cap) and the most a surge can reach (daily.surge_cap).

We raise caps by hand for workspaces with a clean sending history — write to support@charchy.krd.

Queued mail is never dropped

When many emails are queued, accepted ones wait their turn: bursts slow delivery a little but never lose mail. Emails with expires_at go first — soonest to expire first — so set it on sign-in codes and one-time links: they overtake your receipts, which still keep moving.

Automatic pauses

Sending pauses for a workspace when:

  • hard bounces reach 4%, or spam complaints reach 0.08%, of its last 500 recipients (once at least 100 have gone out).

Volume alone never pauses sending. When an hour jumps far above your usual, your owners and admins get an email and a notification, and for the next 24 hours the same rates are judged over your last 100 recipients (once 50 have gone out) — a leaked key mailing strangers is stopped within minutes, a sign-up rush is not.

Our delivery provider can also pause a workspace's sending on its own reputation checks.

Then:

  • new live requests answer 403 sending_paused;
  • an account.paused webhook fires and your workspace's owners and admins get an email;
  • test keys keep working;
  • live mail already accepted is held, not failed. It goes out when sending resumes, unless its expires_at passes first or it has waited 3 days past its due time — then it is expired and refunded (held mail).

A person resumes sending, after reviewing it with you; account.resumed fires then. The dashboard's Overview shows your bounce and complaint rates next to these limits.

On this page