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 simulateddelivered. 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": truein the API and in every webhook'sdata); - 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/usageshows 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.
| Address | What happens | Webhooks |
|---|---|---|
delivered@sim.charchy.krd | Delivered | email.sent, email.delivered |
bounced@sim.charchy.krd | Hard bounce (permanent) | email.sent, email.bounced |
complained@sim.charchy.krd | Delivered, then marked as spam | email.sent, email.delivered, email.complained |
suppressed@sim.charchy.krd | Skipped as suppressed when the request is accepted | email.suppressed |
delayed@sim.charchy.krd | Delivery delayed, then delivered about 10 seconds later | email.sent, email.delivery_delayed, email.delivered |
- Events arrive about a second after the email turns
sent. - Add a
+labelto 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:
frommust be on a verified domain, and a paused workspace answerssending_paused. sim.charchy.krdhas 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.