Email for professionals and teams
update readme
Hieu Nguyen (Jack)dbd07802c604
diff --git a/.dev.vars.example b/.dev.vars.exampleindex ebef89a..4e671f6 100644--- a/.dev.vars.example+++ b/.dev.vars.example@@ -3,7 +3,6 @@CF_TOKEN=your_api_token_with_zone_email_permissions# Optional account id. Read by the database backup workflow.# CF_AID=your_account_id-# CF_EMAIL_WORKER_NAME=mailflare# Optional: lets the admin dashboard trigger the GitHub update workflow.# GITHUB_UPDATE_TOKEN=github_pat_with_actions_writediff --git a/README.md b/README.mdindex a02681a..e0d6aeb 100644--- a/README.md+++ b/README.md@@ -31,15 +31,15 @@ A [Paid Worker](https://developers.cloudflare.com/workers/platform/pricing/) pla## Deploy-The easiest way to get started is with the **Deploy to Cloudflare** button above. You will need:+Getting started takes three steps:-- A Cloudflare account.-- A domain managed by Cloudflare.-- A Cloudflare API token that Mailflare can use to configure email routing.+1. **Deploy the app.** Click **Deploy to Cloudflare** and keep the app name as `mailflare`. The app will not work correctly under another Worker name.+2. **Complete setup.** Open the deployed app and follow `/setup` to check the installation and create your admin account.+3. **Connect your domain.** Add a domain managed by the same Cloudflare account. Mailflare configures its email routing and helps you create the first mailbox.-After deployment, open your Mailflare URL and follow the first-run setup. The setup checks your Cloudflare configuration, creates the initial account, and helps you connect your first domain.+`CF_TOKEN` is required during deployment. Use a scoped Cloudflare API token with **Zone Read**, **Email Routing Edit**, **Email Sending Edit**, and **Email Routing Rules Write** permissions for the domains you want to connect. This runtime token is separate from the token Cloudflare uses to deploy the app.-See the [deployment guide](docs/deployment.md) for required permissions, manual deployment, backups, updates, and custom Worker names.+See the [deployment guide](docs/deployment.md) for required permissions, manual deployment, backups, and updates.## Local developmentdiff --git a/docs/api.md b/docs/api.mdindex 94bf28b..aa1e689 100644--- a/docs/api.md+++ b/docs/api.md@@ -14,7 +14,7 @@ Adding or removing a domain from Mailflare also updates Cloudflare Email Routing| `DELETE /api/domains/[id]` | Remove a domain and clean up its Cloudflare resources || `GET /api/domains/[id]/dns` | View its routing and sending DNS status |-The hostname must be the apex of a zone available to the configured Cloudflare credentials, or a subdomain of that zone. Creating a mailbox also creates the Cloudflare Email Routing rule that delivers its address to `CF_EMAIL_WORKER_NAME`.+The hostname must be the apex of a zone available to the configured Cloudflare credentials, or a subdomain of that zone. Creating a mailbox also creates the Cloudflare Email Routing rule that delivers its address to the `mailflare` Worker.## Sending emaildiff --git a/docs/deployment.md b/docs/deployment.mdindex 4ebc752..974c820 100644--- a/docs/deployment.md+++ b/docs/deployment.md@@ -2,6 +2,16 @@This guide covers Cloudflare deployment, runtime configuration, database backups, and application updates.+## Deployment overview++Set up Mailflare in three steps:++1. **Deploy the app:** use the Deploy to Cloudflare button, set the app name to `mailflare`, and provide the required `CF_TOKEN`.+2. **Complete setup:** open the deployed app and follow `/setup` to check the installation and create the first admin account.+3. **Connect your domain:** add a domain managed by the same Cloudflare account. Mailflare configures email routing and sending, then helps you create the first mailbox.++The Worker name must remain `mailflare`. Before starting, create the required `CF_TOKEN` with **Zone Read**, **Email Routing Edit**, **Email Sending Edit**, and **Email Routing Rules Write** permissions for every domain you plan to connect.+## One-click deployment[](https://deploy.workers.cloudflare.com/?url=https://github.com/hieunc229/mailflare)@@ -12,33 +22,39 @@ Cloudflare automatically detects `npm run build` as the build command and `npm rKeep `wrangler.jsonc` committed. Do not commit `.dev.vars`; enter secrets during Cloudflare setup or keep them in a local `.dev.vars` file.-## Required configuration+### Step 1: Deploy the app-Mailflare needs these runtime values:+1. Click **Deploy to Cloudflare** above and sign in to Cloudflare if prompted.+2. Choose the Cloudflare account that owns the domain you want to use.+3. Set the app name to exactly `mailflare`. Do not rename it.+4. Add `CF_TOKEN` when Cloudflare asks for the app's runtime variables or secrets.+5. Start the deployment and wait for Cloudflare to finish provisioning and deploying the Worker.-- `CF_TOKEN` — a scoped Cloudflare API token with Zone Read, Email Routing Edit, Email Sending Edit, and Email Routing Rules Write access for the domains you will connect. This is separate from the token Cloudflare uses to deploy the app.-- `CF_EMAIL_WORKER_NAME` — the deployed Worker name. It must match the Worker name exactly so Mailflare can create Email Routing rules.-- `CF_AID` — the Cloudflare account ID. This is optional for normal mail use but required for database backups.+## Required configuration-You can use a legacy Global API Key instead of `CF_TOKEN` by setting both `CF_API_KEY` and `CF_EMAIL`.+Mailflare requires this runtime value:-Copy `.dev.vars.example` when configuring a local environment:+- `CF_TOKEN` — a scoped Cloudflare API token with **Zone Read**, **Email Routing Edit**, **Email Sending Edit**, and **Email Routing Rules Write** access for the domains you will connect. This is separate from the token Cloudflare uses to deploy the app.-```bash-cp .dev.vars.example .dev.vars-```+Paste only the token secret into `CF_TOKEN`. Do not include the word `Bearer` and do not use the token ID. The token must belong to the same Cloudflare account as the domains you connect.-Paste only the token value into `CF_TOKEN`; do not include `Bearer` and do not use the token ID.+## Step 2: Complete first-run setup-## First-run setup+1. Open the URL of the deployed `mailflare` Worker.+2. Go to `/setup` if Mailflare does not take you there automatically.+3. Let Mailflare check the required Cloudflare configuration and initialize the empty D1 database.+4. Create the first admin account when prompted.-Open `/setup` after deployment. Mailflare checks the required runtime configuration and initializes an empty D1 database. It never applies later migrations to an existing database from the setup page.+The setup page initializes only a new, empty database. It never applies later migrations to an existing database.-Use the normal migration command when updating an existing installation:+## Step 3: Connect your domain-```bash-npm run db:migrate:remote-```+1. Enter a domain that already uses Cloudflare DNS on the same account as `CF_TOKEN`.+2. Continue while Mailflare enables Email Routing and configures the required routing and sending DNS.+3. Choose the address for your first mailbox and finish setup.+4. Open the inbox and send a test message to the new address.++To connect more domains later, open **Admin → Domains**, select **New domain**, and enter the hostname. Mailflare configures Email Routing and Email Sending automatically.## Manual deployment@@ -59,26 +75,14 @@ npm run db:migrate:remoteRemote migrations require the target account's `database_id` in your local `wrangler.jsonc`. Do not commit an account-specific database ID to a reusable repository.-## Custom Worker names+## Worker name-If you rename the Worker, keep these values aligned:--- `name` in `wrangler.jsonc`-- `services[].service` for the `WORKER_SELF_REFERENCE` binding-- `CF_EMAIL_WORKER_NAME`--Cloudflare service bindings use a literal Worker name and cannot inherit the top-level `name` value automatically.+The Worker name is fixed to `mailflare`. Email Routing rules and the `WORKER_SELF_REFERENCE` service binding use this name, so do not rename the Worker.## Database backupsManual and scheduled backups use the `DATABASE_BACKUP_WORKFLOW` binding declared in `wrangler.jsonc`. Deploy the complete Worker with `npm run deploy` whenever this binding is added or changed.-Backups require:--- `CF_AID`-- `D1_DATABASE_ID`-- `D1_BACKUP_TOKEN`, or a `CF_TOKEN` that is also allowed to export the D1 database-## Updating MailflareThe **Update Mailflare** button in the admin dashboard dispatches `.github/workflows/update.yml` in the installation repository. The workflow merges the latest upstream source, applies pending D1 migrations, and pushes the updated source. A connected Cloudflare Git integration can then build and deploy the change.diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex 770bccf..e682e81 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -49,7 +49,7 @@ Also confirm that `CF_AID` and `D1_DATABASE_ID` are set, and that `D1_BACKUP_TOKConfirm that:-- `CF_EMAIL_WORKER_NAME` exactly matches the deployed Worker name.-- `services[].service` in `wrangler.jsonc` uses the same name.+- The deployed Worker is named `mailflare`.+- `services[].service` in `wrangler.jsonc` is also `mailflare`.- Email Routing is enabled for the domain in Cloudflare.- The mailbox has an Email Routing rule pointing to the Worker.diff --git a/env.d.ts b/env.d.tsindex 47e9fe9..a64f28c 100644--- a/env.d.ts+++ b/env.d.ts@@ -19,7 +19,6 @@ interface CloudflareEnv {D1_DATABASE_ID?: string;D1_BACKUP_TOKEN?: string;TURNSTILE_SECRET_KEY?: string;- CF_EMAIL_WORKER_NAME?: string;GITHUB_UPDATE_TOKEN?: string;GITHUB_UPDATE_REF?: string;GITHUB_UPDATE_REPO?: stringdiff --git a/package.json b/package.jsonindex 3d1c492..c5e95b5 100644--- a/package.json+++ b/package.json@@ -41,9 +41,6 @@"NEXT_PUBLIC_TURNSTILE_SITE_KEY": {"description": "Cloudflare Turnstile public site key used by the login and first-run registration widgets."},- "CF_EMAIL_WORKER_NAME": {- "description": "Worker name used when creating Cloudflare Email Routing rules. Set this to the deployed Worker name; if you rename the Worker, update this value too."- },"GITHUB_UPDATE_TOKEN": {"description": "Fine-grained GitHub token for the installation repository with Actions: write permission, Contents: write read permission. Used only by the admin update endpoint to dispatch update.yml."},diff --git a/src/lib/cloudflare-api-utils.ts b/src/lib/cloudflare-api-utils.tsindex 42fb3c7..7a570cd 100644--- a/src/lib/cloudflare-api-utils.ts+++ b/src/lib/cloudflare-api-utils.ts@@ -58,7 +58,6 @@ export function getCloudflareAuthHint(errors: CfApiError[]) {return " Verify CF_TOKEN with `curl https://api.cloudflare.com/client/v4/user/tokens/verify -H \"Authorization: Bearer <token>\"`. Use the token secret value without `Bearer`, or use CF_API_KEY plus CF_EMAIL for a Global API Key.";}-export function getEmailWorkerName(env: CloudflareEnv): string {- const workerName = env.CF_EMAIL_WORKER_NAME?.trim();- return workerName || "mailflare";+export function getEmailWorkerName(): string {+ return "mailflare";}diff --git a/src/lib/cloudflare-api.ts b/src/lib/cloudflare-api.tsindex 8ce7b4e..c86c85f 100644--- a/src/lib/cloudflare-api.ts+++ b/src/lib/cloudflare-api.ts@@ -168,7 +168,7 @@ export async function createEmailRoutingRuleToWorker(zoneId: string,address: string,) {- const workerName = getEmailWorkerName(env);+ const workerName = getEmailWorkerName();return cfRequest<CfEmailRoutingRule>(env,`/zones/${zoneId}/email/routing/rules`,@@ -204,7 +204,7 @@ export async function ensureEmailRoutingRuleToWorker(address: string,) {const normalized = address.toLowerCase();- const workerName = getEmailWorkerName(env);+ const workerName = getEmailWorkerName();const rules = await listEmailRoutingRules(env, zoneId);const existing = rules.find((rule) => isWorkerRouteForAddress(rule, normalized, workerName));@@ -235,7 +235,7 @@ export async function deleteEmailRoutingRuleForAddress(address: string,): Promise<boolean> {const normalized = address.toLowerCase();- const workerName = getEmailWorkerName(env);+ const workerName = getEmailWorkerName();const rules = await listEmailRoutingRules(env, zoneId);const existing = rules.find((rule) => isWorkerRouteForAddress(rule, normalized, workerName));if (!existing?.id) return false;diff --git a/src/lib/domains/catch-all-routing.ts b/src/lib/domains/catch-all-routing.tsindex 31ce611..7b166e9 100644--- a/src/lib/domains/catch-all-routing.ts+++ b/src/lib/domains/catch-all-routing.ts@@ -6,7 +6,7 @@ export async function ensureEmailRoutingCatchAllToWorker(env: CloudflareEnv,zoneId: string,): Promise<CfEmailRoutingRule> {- const workerName = getEmailWorkerName(env);+ const workerName = getEmailWorkerName();return cfRequest<CfEmailRoutingRule>(env,`/zones/${zoneId}/email/routing/rules/catch_all`,diff --git a/src/lib/setup/configuration.ts b/src/lib/setup/configuration.tsindex 27f2f71..bca382d 100644--- a/src/lib/setup/configuration.ts+++ b/src/lib/setup/configuration.ts@@ -10,11 +10,6 @@ export function getSetupRequirementChecks(env: CloudflareEnv): SetupRequirementCconfigured: hasApiToken || hasGlobalKey,message: "Set CF_TOKEN, or set both CF_API_KEY and CF_EMAIL.",},- {- key: "Email Worker name",- configured: !!env.CF_EMAIL_WORKER_NAME?.trim(),- message: "Set CF_EMAIL_WORKER_NAME to the deployed Worker name.",- },{key: "D1 database",configured: !!env.DB,