Charchy Senddocs

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.

.github/workflows/test.yml
- name: Email tests
  env:
    CHARCHY_SEND_KEY: ${{ secrets.CHARCHY_SEND_TEST_KEY }}
  run: npm test -- emails

2. A test per outcome

Label each run with + so parallel runs don't mix, then poll GET /v1/emails/{id} for the status:

emails.test.ts
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 a suppressed status as "not sent"?
  • delayed@… — does nothing panic while an email is delayed? It turns delivered about 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.

On this page