Testing in CI
Run real end-to-end email tests in CI with a test key and the magic addresses — free, no inbox, no real email.
A test key runs every check a live key does, then
simulates delivery; the @sim.charchy.krd magic addresses pick the outcome.
CI can test the whole email path — request, error handling, webhook — for free.
1. A test key in CI
Create a test key (chy_test_…) for CI only and store it as a secret — in
GitHub, Settings → Secrets and variables → Actions, named
CHARCHY_SEND_TEST_KEY.
- name: Email tests
env:
CHARCHY_SEND_KEY: ${{ secrets.CHARCHY_SEND_TEST_KEY }}
run: npm test -- emails2. A test per outcome
Label each run with + so parallel runs don't mix, then poll
GET /v1/emails/{id} for the status:
import { expect, test } from "vitest"
const API = "https://api.charchy.krd/v1"
const headers = {
Authorization: `Bearer ${process.env.CHARCHY_SEND_KEY}`,
"Content-Type": "application/json",
}
const run = process.env.GITHUB_RUN_ID ?? "local"
async function send(to: string) {
const response = await fetch(`${API}/emails`, {
method: "POST",
headers: { ...headers, "Idempotency-Key": `ci/${run}/${to}` },
body: JSON.stringify({ from: "CI <ci@example.com>", to, subject: "CI", text: "ok" }),
})
expect(response.status).toBe(200)
return (await response.json()).id as string
}
async function waitForStatus(id: string, wanted: string) {
for (let attempt = 0; attempt < 20; attempt++) {
const email = await (await fetch(`${API}/emails/${id}`, { headers })).json()
if (email.status === wanted) return
await new Promise((resolve) => setTimeout(resolve, 500))
}
throw new Error(`${id} never reached ${wanted}`)
}
test("a delivered email", async () => {
await waitForStatus(await send(`delivered+${run}@sim.charchy.krd`), "delivered")
})
test("a bounce", async () => {
await waitForStatus(await send(`bounced+${run}@sim.charchy.krd`), "bounced")
})Reading emails needs a key with full permission.
3. Test your own code, not just the API
Call your functions — the sign-up flow, the receipt job — with a magic address as the user's email, and check what your app does with the outcome:
delivered@…— the happy path;bounced@…— does your app mark the address and ask the user to fix it?complained@…— do you stop sending that user optional emails?suppressed@…— does your code treat asuppressedstatus as "not sent"?delayed@…— does nothing panic while an email is delayed? It turnsdeliveredabout 10 seconds later.
Test sends don't count against your plan, credits or daily cap. Their own
allowance is 1,000 recipients per rolling 24 hours per workspace, test keys and
magic addresses together; past it, a send answers 429 daily_limit_reached —
keep CI from looping.
Webhooks in CI
Test-key emails fire your workspace's webhooks for real — one per recipient event. In CI, call your handler directly with a body signed by your own test secret instead of waiting for delivery; the plain HMAC code shows the signature format.