Skip to content

Deploy

Deploy EmailFlare on Cloudflare Workers

One Worker, plus a D1 database, an R2 bucket, a KV namespace, a queue and a Durable Object, all in your account. Use the deploy button, or deploy from the command line.

What you are deploying

One Worker, five services.

The dashboard, the REST API and the email handlers ship together. Cloudflare Email Routing hands inbound mail to the Worker's email handler.

  • Inbound mail

    Email Routing catch-all

  • Browser and API calls

    HTTPS to your Worker

  • Scheduled work

    Cron for sequences

one Cloudflare Worker
  • Dashboard

    Inbox and workspace

  • REST API

    /v1/send and /api/*

  • Handlers

    email, queue, scheduled

  • D1

    Threads, contacts, keys, logs

  • R2

    Raw MIME and attachments

  • Queues

    Reliable outbound sends

  • KV

    Rate limits, short tokens

  • Durable Objects

    Live inbox updates

Before you start

  • A Cloudflare account. Any domain you want to send from or receive on must be added to it as a zone.
  • A Cloudflare API token and your account ID. The token guide lists the exact permissions.
  • For command-line deploys: Node.js 22 or later, pnpm and just.

Deploy

Option 1: the deploy button

The button opens Cloudflare's deploy flow. It copies the repository into your Git account and creates a Worker connected to it with Workers Builds, along with the bindings described below. Check the build settings it proposes against this table.

Workers Builds settings
SettingValueNotes
Root directoryapps/dashboardWhere the Worker lives in the repository.
Build commandLeave emptyThe predeploy script runs the build for you.
Deploy commandpnpm run deployMerges wrangler.production.jsonc into the base config, applies D1 migrations, then deploys.
Production branchYour default branchPushes to it build and deploy a new version.

Option 2: the command line

Create the D1 database, KV namespace, R2 bucket and queue yourself, then fill in wrangler.production.jsonc. This file is gitignored, so it stays on your machine.

Create resources
git clone https://github.com/0xdps/emailflare.git
cd emailflare
just install

# Create the resources, then copy the IDs into the config
cd apps/dashboard
pnpm exec wrangler login
pnpm exec wrangler d1 create emailflare
pnpm exec wrangler kv namespace create RATE_LIMIT_KV
pnpm exec wrangler r2 bucket create emailflare-attachments
pnpm exec wrangler queues create emailflare-sequences
cp wrangler.production.example.jsonc wrangler.production.jsonc
cd ../..

Fill in the config in the next two sections, set the secrets, then deploy:

Deploy
just dashboard-deploy

Bindings

Binding names are part of the app. Do not rename them. Only resource names and IDs change per install.

Cloudflare bindings and triggers
ResourceBindingWhat it is used for
D1 databaseDBUsers, mailboxes, threads, contacts, templates, API keys, domains, logs and suppressions. Migrations in apps/dashboard/migrations run on every deploy.
R2 bucketATTACHMENTSRaw inbound messages (MIME) and attachments.
KV namespaceRATE_LIMIT_KVLogin and password-reset rate limits, plus short-lived tokens such as password resets and two-factor setup.
QueueEMAIL_QUEUEProducer and consumer for sequence steps and scheduled sends. Batches of up to 10, with a 30 second timeout.
Durable ObjectNOTIFICATIONSThe NotificationsHub class. Pushes live inbox updates to open browsers over WebSocket.
Rate limitingRATE_LIMITER100 requests per 60 seconds per API key. Needs a Workers Paid plan. If the binding is missing, requests are not limited per key.
Static assetsASSETSThe dashboard's client files.
Cron trigger*/5 * * * *Runs scheduled() every five minutes to process due sequence steps.

The Worker exports three handlers next to the web app: email() for inbound mail, queue() for the send queue and scheduled() for the cron trigger.

Configuration

wrangler.jsonc holds the defaults and is committed. Your install overrides it in a file that stays out of Git: wrangler.production.jsonc for deploys and wrangler.local.jsonc for just dashboard-dev. Start from the matching .example.jsonc file.

apps/dashboard/wrangler.production.jsonc
{
	"name": "emailflare",

	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "emailflare",
			"database_id": "<your D1 database id>",
			"migrations_dir": "migrations"
		}
	],
	"kv_namespaces": [
		{ "binding": "RATE_LIMIT_KV", "id": "<your KV namespace id>" }
	],
	"r2_buckets": [
		{ "binding": "ATTACHMENTS", "bucket_name": "emailflare-attachments" }
	],
	"queues": {
		"producers": [{ "binding": "EMAIL_QUEUE", "queue": "emailflare-sequences" }],
		"consumers": [
			{ "queue": "emailflare-sequences", "max_batch_size": 10, "max_batch_timeout": 30 }
		]
	},

	"vars": {
		"PUBLIC_URL": "https://mail.yourcompany.com",
		"INBOX_WORKER_NAME": "emailflare",
		"CF_DAILY_LIMIT": "1000"
	}
}
Keys to set in wrangler.production.jsonc
KeySet it to
nameThe Worker name. Change it if emailflare is taken in your account.
d1_databases[].database_idThe ID of your D1 database. The all-zero placeholder fails the deploy.
kv_namespaces[].idThe ID of your KV namespace. The all-zero placeholder fails the deploy.
r2_buckets[].bucket_nameThe name of your R2 bucket. Required, and the bucket must already exist.
queuesThe queue name, set the same under producers and consumers. Create the queue before the first deploy.
vars.PUBLIC_URLYour public origin, such as https://mail.yourcompany.com, with no trailing slash. Invite, password reset, unsubscribe and tracking links use it.
vars.INBOX_WORKER_NAMEThe Worker that receives catch-all mail. Keep it equal to name.
vars.CF_DAILY_LIMITThe daily send limit shown on the Overview page. Defaults to 1000.

Secrets

Three values are secrets. Never put them in a Wrangler file or commit them. Set them once the Worker exists.

Worker secrets
SecretWhat it is
SESSION_SECRETSigns session cookies. Use at least 32 random characters. Generate one with openssl rand -hex 32.
CF_API_TOKENYour Cloudflare API token. Used to list zones, create sending subdomains, write DNS records and set Email Routing. How to create it.
CF_ACCOUNT_IDYour Cloudflare account ID, shown under Workers & Pages in the dashboard. Used for sending and token status.

Set each one with the just recipe, which merges your production config first:

Set the secrets
just dashboard-secret SESSION_SECRET
just dashboard-secret CF_API_TOKEN
just dashboard-secret CF_ACCOUNT_ID

Or use Wrangler directly, or Settings, then Variables and secrets on the Worker in the Cloudflare dashboard.

With Wrangler
cd apps/dashboard
pnpm exec wrangler secret put SESSION_SECRET
pnpm exec wrangler secret put CF_API_TOKEN
pnpm exec wrangler secret put CF_ACCOUNT_ID

After the first deploy

  1. Set the secrets

    Sign-in, setup and invites need SESSION_SECRET. Domain setup needs CF_API_TOKEN and CF_ACCOUNT_ID.

  2. Create the administrator

    Open your workers.dev address, or your custom domain, and complete the /setup wizard. It creates the first administrator and your workspace.

  3. Enable a domain

    In the dashboard, enable a domain from your account. If the token can edit DNS, Zone Settings and Email Routing rules, EmailFlare writes the records and points the zone's catch-all at the Worker.

    If it cannot, the domain is still saved and the dashboard shows what is left. To finish by hand, open the zone, go to Email, then Email Routing, and send the catch-all to the Worker named in INBOX_WORKER_NAME.

  4. Update PUBLIC_URL if you add a custom domain

    Set vars.PUBLIC_URL to the new origin and deploy again, so invite and unsubscribe links point at it.

  5. Create an API key and send

    Create a key in the dashboard and call POST /v1/send. See the Email API page.

Updating

Pull the latest release into your repository and deploy again. With Workers Builds, pushing to the production branch does this. Each deploy applies any new D1 migrations before the Worker ships. The changelog lists what changed.

Local development

Locally the app runs on Miniflare with emulated D1, KV and R2, so you need no Cloudflare resources and no mail server. It serves on http://localhost:5173.

Run locally
just install

cp apps/dashboard/wrangler.local.example.jsonc apps/dashboard/wrangler.local.jsonc
cp apps/dashboard/.dev.vars.example apps/dashboard/.dev.vars

just dashboard-migrate
just dashboard-dev

Put local secrets in apps/dashboard/.dev.vars. Mail sent with a test key is captured in the sandbox mailbox, and inbound mail is not delivered to a local instance. just dashboard-fresh deletes the local database, applies migrations and starts the dev server again.

Troubleshooting

Common deploy and setup problems
SymptomCauseFix
still has placeholder D1 or KV IDswrangler.production.jsonc still contains the all-zero IDs from the example.Paste the real database_id and KV id, then deploy again.
Missing wrangler.production.jsoncThe deploy script reads this gitignored file and stops without it.Copy wrangler.production.example.jsonc and fill it in.
missing ATTACHMENTS.bucket_nameThe R2 binding has no bucket name.Create the bucket and set bucket_name on the ATTACHMENTS binding.
Domain setup says a permission is missingThe API token lacks one of the permissions EmailFlare calls.Compare the token with the permissions table.
Mail to your domain does not arriveThe zone's catch-all rule does not point at this Worker, or INBOX_WORKER_NAME differs from name.In the zone, open Email, then Email Routing, and send the catch-all to the Worker named in INBOX_WORKER_NAME.

Ready when you are.

The deploy button creates the Worker. Set three secrets, run the setup wizard and add a domain.