Local development
Run the mailer on your machine, fake delivery events, and run the tests.
Set up
From the repo root:
pnpm install
pnpm build # builds the packages the mailer imports (turbo)Then in apps/mailer:
cp .dev.vars.example .dev.vars
npx wrangler d1 migrations apply flaresend --local.dev.vars.example sets ADMIN_API_KEY=dev-admin-key, TRACKING_SECRET=dev-tracking-secret and an empty CF_API_TOKEN. pnpm migrate:local in apps/mailer runs the same migration command.
Two ways to run it
cd apps/mailer
npx wrangler dev --var ENVIRONMENT:developmentUses wrangler.jsonc with a local send_email binding. Nothing is delivered: emails reach sent with a fake message ID. Good for API and dashboard work.
--var ENVIRONMENT:development matters: wrangler.jsonc says production, which turns off the fake-events route below.
Either way the mailer listens on http://localhost:8787. Create a project and key with the CLI or the admin API:
export FLARESEND_BASE_URL=http://localhost:8787 FLARESEND_ADMIN_KEY=dev-admin-key
flaresend projects create --slug acme --name Acme --domains acme.com --default-from "Acme <hello@acme.com>"
flaresend keys create --project acme --name local --mode liveFake delivery events
Cloudflare's event subscriptions don't deliver to wrangler dev, so emails stop at sent. Push them further with a fake event:
pnpm dev:event delivered <emailId> # from the repo rootThe other types are deferred, bounced, failed, rejected and complained. This runs flaresend dev event, which posts a Cloudflare-shaped event per recipient to POST /v1/admin/dev/events. That route answers 404 when ENVIRONMENT is production. Options are in the CLI reference.
The events go through the same code as real ones, so status updates, suppressions and webhooks all run.
Run the dashboard against it
See Dashboard → Run it locally.
Tests
pnpm test # every package (turbo)
pnpm typecheckOr one package:
pnpm --filter @flaresend/mailer test
pnpm --filter @flaresend/client testThe mailer's tests run inside workerd with @cloudflare/vitest-pool-workers. They apply the D1 migrations to a fresh database and use ADMIN_API_KEY=test-admin-key and TRACKING_SECRET=test-tracking-secret. Sample Cloudflare events are in apps/mailer/test/fixtures/cf-events.
The docs site
pnpm --filter @flaresend/docs dev # http://localhost:3217