Charchy Senddocs

Test mode

Test keys and the @sim.charchy.krd magic addresses — build, test and run CI without sending a real email or spending a credit.

Test mode is free and is the real API — same validation, answers and webhooks — except nothing reaches a real inbox.

Test keys

Test keys start with chy_test_. Your welcome screen has one ready; make more under API keys. Use them in development, staging and CI. A test key:

  • goes through the same authentication, validation, idempotency and rate limit as a live key, with the same codes;
  • may use any domain in from, and skips the checks that only matter for real mail: domain verification, approval, pauses and your balance — so it keeps working while live sending is paused;
  • never sends. The email turns sent, and a second later every recipient that isn't a magic address gets a simulated delivered. Its timeline events carry "simulated": true, and your webhooks fire for real — one per recipient event, the same payload as live mail — so you can test your endpoint end to end;
  • still skips addresses on your suppression list;
  • shows its emails in Emails, marked as test ("test": true in the API and in every webhook's data);
  • is free: it never touches your plan's emails, credits or daily cap. Test sends have their own allowance of 1,000 recipients in a rolling 24 hours per workspace, shared with magic addresses; past it, 429 daily_limit_reached. GET /v1/usage shows how many you've used.

Magic addresses

Send to these for a known outcome. They work with test and live keys, never reach a real mail server, and are free: even with a live key they never count against your daily cap or balance — only against the 1,000-a-day test allowance.

AddressWhat happensWebhooks
delivered@sim.charchy.krdDeliveredemail.sent, email.delivered
bounced@sim.charchy.krdHard bounce (permanent)email.sent, email.bounced
complained@sim.charchy.krdDelivered, then marked as spamemail.sent, email.delivered, email.complained
suppressed@sim.charchy.krdSkipped as suppressed when the request is acceptedemail.suppressed
delayed@sim.charchy.krdDelivery delayed, then delivered about 10 seconds lateremail.sent, email.delivery_delayed, email.delivered
  • Events arrive about a second after the email turns sent.
  • Add a +label to tell tests apart: delivered+signup@sim.charchy.krd, bounced+invoice-test@sim.charchy.krd.
  • With a live key, the rest of the request is still checked as live: from must be on a verified domain, and a paused workspace answers sending_paused.
  • sim.charchy.krd has no mail server, so nothing sent to it can be accepted by anyone, even by mistake.

Bounces on magic addresses don't count against you

A simulated bounce or complaint never touches your real suppression list, bounce rate or usage, and never pauses your sending.

A CI check in one request

Fails the build if the email is refused. Testing in CI goes further.

curl --fail-with-body https://api.charchy.krd/v1/emails \
  -H "Authorization: Bearer $CHARCHY_SEND_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-$GITHUB_RUN_ID" \
  -d '{
    "from": "CI <ci@example.com>",
    "to": ["delivered+ci@sim.charchy.krd"],
    "subject": "CI smoke test",
    "text": "ok"
  }'

Before you are approved: your own inbox

Until your workspace is approved for sending, a live key sends real email only to your team's own addresses (the people in your workspace), up to 50 recipients in a rolling 24 hours, free. Any other recipient answers 403 not_approved. Magic addresses work throughout.

On this page