API keys and security
Test and live keys, full and sending-only permission, locking a key to a domain, keeping keys on the server — and what to do if one leaks.
Anyone holding a live key can send email as your domain and spend your balance.
Kinds of key
| Test key | Live key | |
|---|---|---|
| Starts with | chy_test_ | chy_live_ |
| Sends real email | Never — simulated events, real webhooks | Yes |
from | Any domain | Your verified domains only |
| Costs | Free, 1,000 recipients a day | Your plan and credits |
| Use it in | Development, staging, CI | Production |
Create keys under API keys in the dashboard. The full key is shown once; afterwards you see only its last four characters and when it was last used. Up to 20 active keys per workspace, live and test together; a revoked key frees its place. You accept the Charchy Send terms before your first live key.
Permission
- Full — send, read and list emails (
GET /v1/emails…), reschedule and cancel them, check usage, upload images. - Sending — send, and check usage (
GET /v1/usage, which holds no email data). Everything else answers403 restricted_api_key.
A checkout service that sends receipts needs a sending key; only admin tools need a full one.
Domain lock
A live key can be locked to one domain (test keys can't). It then sends
only from that domain; anything else answers 403 restricted_api_key. If the
domain is removed from the workspace, the key can't send at all — revoke it
and make a new one. Use one locked key per product or brand, so a leak in one
can't send as the others.
Keep keys on the server
- Read the key from an environment variable (e.g.
CHARCHY_SEND_KEY) or your host's secret manager. - Never put a key in browser JavaScript, a mobile app, a public repository, a
committed
.envfile, logs or error messages. - The API sends no CORS headers, on purpose: a request from browser code fails. Let your front end call your server.
- Never prefix the variable with
NEXT_PUBLIC_(Next.js) orVITE_(Vite) — those ship the value to every visitor. - One key per environment and per service, so you can revoke one without breaking the others.
If a key leaks
- Revoke the key under API keys. It stops working at once — the next
request answers
401 invalid_api_key. - Create a new key and put it in your server's environment.
- Check Emails for anything you didn't send, and your balance.
- If the key was in a Git repository, revoking is what matters: removing it from history doesn't un-leak it.
A sudden jump in volume pauses sending automatically (why), which limits a leaked key — but revoke it as soon as you know.
Webhook secrets
Keep your webhook signing secret (whsec_…) in CHARCHY_WEBHOOK_SECRET on
the server. If it leaks, Rotate secret in the dashboard; both secrets sign
events for 24 hours while you deploy the new one
(Webhooks).