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
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.
| Setting | Value | Notes |
|---|---|---|
| Root directory | apps/dashboard | Where the Worker lives in the repository. |
| Build command | Leave empty | The predeploy script runs the build for you. |
| Deploy command | pnpm run deploy | Merges wrangler.production.jsonc into the base config, applies D1 migrations, then deploys. |
| Production branch | Your default branch | Pushes 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.
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:
just dashboard-deployBindings
Binding names are part of the app. Do not rename them. Only resource names and IDs change per install.
| Resource | Binding | What it is used for |
|---|---|---|
| D1 database | DB | Users, mailboxes, threads, contacts, templates, API keys, domains, logs and suppressions. Migrations in apps/dashboard/migrations run on every deploy. |
| R2 bucket | ATTACHMENTS | Raw inbound messages (MIME) and attachments. |
| KV namespace | RATE_LIMIT_KV | Login and password-reset rate limits, plus short-lived tokens such as password resets and two-factor setup. |
| Queue | EMAIL_QUEUE | Producer and consumer for sequence steps and scheduled sends. Batches of up to 10, with a 30 second timeout. |
| Durable Object | NOTIFICATIONS | The NotificationsHub class. Pushes live inbox updates to open browsers over WebSocket. |
| Rate limiting | RATE_LIMITER | 100 requests per 60 seconds per API key. Needs a Workers Paid plan. If the binding is missing, requests are not limited per key. |
| Static assets | ASSETS | The 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.
{
"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"
}
}| Key | Set it to |
|---|---|
name | The Worker name. Change it if emailflare is taken in your account. |
d1_databases[].database_id | The ID of your D1 database. The all-zero placeholder fails the deploy. |
kv_namespaces[].id | The ID of your KV namespace. The all-zero placeholder fails the deploy. |
r2_buckets[].bucket_name | The name of your R2 bucket. Required, and the bucket must already exist. |
queues | The queue name, set the same under producers and consumers. Create the queue before the first deploy. |
vars.PUBLIC_URL | Your public origin, such as https://mail.yourcompany.com, with no trailing slash. Invite, password reset, unsubscribe and tracking links use it. |
vars.INBOX_WORKER_NAME | The Worker that receives catch-all mail. Keep it equal to name. |
vars.CF_DAILY_LIMIT | The 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.
| Secret | What it is |
|---|---|
SESSION_SECRET | Signs session cookies. Use at least 32 random characters. Generate one with openssl rand -hex 32. |
CF_API_TOKEN | Your Cloudflare API token. Used to list zones, create sending subdomains, write DNS records and set Email Routing. How to create it. |
CF_ACCOUNT_ID | Your 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:
just dashboard-secret SESSION_SECRET
just dashboard-secret CF_API_TOKEN
just dashboard-secret CF_ACCOUNT_IDOr use Wrangler directly, or Settings, then Variables and secrets on the Worker in the Cloudflare dashboard.
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_IDAfter the first deploy
Set the secrets
Sign-in, setup and invites need
SESSION_SECRET. Domain setup needsCF_API_TOKENandCF_ACCOUNT_ID.Create the administrator
Open your
workers.devaddress, or your custom domain, and complete the/setupwizard. It creates the first administrator and your workspace.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.Update PUBLIC_URL if you add a custom domain
Set
vars.PUBLIC_URLto the new origin and deploy again, so invite and unsubscribe links point at it.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.
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-devPut 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
| Symptom | Cause | Fix |
|---|---|---|
still has placeholder D1 or KV IDs | wrangler.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.jsonc | The deploy script reads this gitignored file and stops without it. | Copy wrangler.production.example.jsonc and fill it in. |
missing ATTACHMENTS.bucket_name | The R2 binding has no bucket name. | Create the bucket and set bucket_name on the ATTACHMENTS binding. |
| Domain setup says a permission is missing | The API token lacks one of the permissions EmailFlare calls. | Compare the token with the permissions table. |
| Mail to your domain does not arrive | The 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. |
Still stuck? Read the deployment notes in the repository or open an issue.
Ready when you are.
The deploy button creates the Worker. Set three secrets, run the setup wizard and add a domain.