Deploy Cloudflare Temp Email with GitHub Actions

Introduction#

This guide deploys dreamhunter2333/cloudflare_temp_email as a private temporary-email service on Cloudflare.

It complements the project’s official documentation and official quick start. Use those pages for the complete feature reference and this post for a reviewed, automation-oriented GitHub Actions workflow.

The workflow favors explicit, verifiable steps:

inputs are named variables instead of hard-coded identifiers;
commands prefer machine-readable output and explicit read-back checks;
secrets enter through hidden prompts or standard input;
deployments stop when the reviewed commit does not match the dispatched commit;
destructive boundaries, especially MX changes, require human confirmation.

For every Cloudflare or GitHub mutation, the automated path appears first and the dashboard equivalent follows. Choose one mutation path; use the other only to verify the resulting state.

Protect existing email before you begin
Enabling Cloudflare Email Routing changes the domain’s MX records. If the domain already receives mail through Google Workspace, Microsoft 365, Fastmail, or another provider, use a separate domain or prepare a tested migration and rollback plan.

Overview#

The finished deployment serves the web interface and Worker from one custom domain, stores mail in D1, and routes all incoming addresses to the Worker.

flowchart LR accTitle: Cloudflare temporary email architecture accDescr: Email Routing sends mail to a Worker backed by D1. Sender[External sender] --> Routing[Cloudflare Email Routing] Routing --> Worker[Email Worker] Actions[Reviewed GitHub Actions run] --> Worker Worker --> D1[(Cloudflare D1)] Browser[Private webmail user] --> Worker

This guide uses Worker Static Assets, so only the backend workflow is required:

enable Deploy Backend;
keep Upstream Sync disabled during the initial deployment;
keep Deploy Frontend disabled;
keep Deploy Frontend with page function disabled.

The two frontend workflows are alternative split-frontend designs. They are not extra steps for Worker Static Assets. Automatic upstream sync stays disabled until the first deployment passes verification. The Maintenance section shows how to enable it and trigger its first run.

Deployment phases#

Phase	Outcome	Human checkpoint
Prepare	Reviewed source and named inputs	Confirm account and domain
Provision	D1 and private Worker config	Confirm names and scopes
Deploy	Protected, reviewed Worker	Create and rotate tokens
Route mail	Catch-all to the Worker	Approve MX replacement
Verify	Web, Worker, routing, and D1	Send a safe test message

Prerequisites#

Accounts and domain#

You need:

a GitHub account that can create a fork and repository secrets;
a Cloudflare account with an active zone;
a domain that is not carrying email you need to preserve;
permission to create a Worker, D1 database, custom domain, and Email Routing rules.

Deployment inputs#

Decide these values before creating Cloudflare or GitHub resources:

ROOT_DOMAIN: the domain that receives mail, such as example.com;
MAIL_WEB_DOMAIN: the Webmail hostname, such as mail.example.com;
WORKER_NAME: the deployed Worker name;
D1_DATABASE_NAME: the remote database name;
site access and administrator passwords: two different, non-empty values.

The D1 UUID is generated later. The JWT secret is generated locally immediately before it is uploaded, so neither value needs to be prepared manually.

Cloudflare credentials and permissions#

The CLI and website paths use the same least-privilege credential plan.

Using the CLI#

Use separate credentials for interactive setup, the routing REST call, first CI deployment, and later CI deployments.

Credential	Used from	Resource scope	Required access	Lifetime and storage
Wrangler OAuth	Local terminal	Accounts and zones available to the signed-in member	OAuth scopes plus the member’s Cloudflare permissions; Wrangler requests all available scopes by default	Use `--use-keyring`; run `wrangler logout` after one-time setup
Routing API token	Local REST helper	Target account and `ROOT_DOMAIN`	Zone Read; Email Routing Rules Write	Store in a password manager; load only into `CF_ROUTING_API_TOKEN`; revoke after routing read-back
CI bootstrap token	GitHub Actions	Target account and `ROOT_DOMAIN`	Workers product Admin; Zone Read; Workers Routes Write	Temporarily store as repository secret `CLOUDFLARE_API_TOKEN`; replace and revoke after the first successful steady-state deployment
CI steady-state token	GitHub Actions	Existing `WORKER_NAME`	Editor on the selected Worker	Store as repository secret `CLOUDFLARE_API_TOKEN` until planned rotation or revocation

Wrangler OAuth persists access and refresh credentials locally. --use-keyring encrypts them with a key from the operating-system keychain. The last three rows are API tokens; never reuse one token across those roles.

Cloudflare’s older token interface may show Edit where newer documentation uses Write. The capability is the same.

The later CLI phases show where to load the routing token and how to save each CI token as the GitHub repository secret. Wrangler OAuth remains local and is never copied into GitHub.

Using the Cloudflare website UI#

Open the Cloudflare dashboard’s API Tokens page.
Select Create Token, then create a custom token.
Add the permissions for the token type listed above.
For the routing token, restrict Zone Resources to ROOT_DOMAIN.
For the bootstrap token, select Workers product → Admin for only the intended account. Add the two zone permissions for only ROOT_DOMAIN.
After the Worker exists, create the steady-state token with Individual Workers → Editor and select only WORKER_NAME. Do not choose the product-level Worker scope for this token.
Create each token, copy it once, and store it in a password manager.

Create the routing and bootstrap tokens initially. After the Worker exists, create the steady-state per-Worker token, replace the GitHub repository secret, and prove one deployment succeeds with it. Only then revoke the bootstrap token.

Local tools#

Install the reusable tools with Homebrew. The formula is named cloudflare-wrangler, but it provides the wrangler command. Then use mise to install Bun:

1
brew install gh jq mise bind cloudflare-wrangler
2
mise use --global bun@latest

Bun
GitHub CLI
jq
curl
openssl
dig (dnsutils or bind-utils on many Linux distributions)

Verify the tools:

1
bun --version
2
wrangler --version
3
gh --version
4
jq --version

Authenticate GitHub and Cloudflare:

1
gh auth login
2
gh auth status
3

4
wrangler login --use-keyring
5
wrangler whoami

Wrangler’s Email Routing commands may still be marked as beta. Read the local help before relying on a flag:

1
wrangler email routing --help
2
wrangler email routing rules update --help

Phase 1: Prepare the source and account#

Set session variables#

Replace the example domains in your private terminal. Do not publish the edited block.

1
set +x
2

3
export UPSTREAM_REPO="dreamhunter2333/cloudflare_temp_email"
4
export ROOT_DOMAIN="example.com"
5
export MAIL_WEB_DOMAIN="mail.example.com"
6
export WORKER_NAME="cloudflare_temp_email"
7
export D1_DATABASE_NAME="temp-email-db"
8

9
export GITHUB_OWNER="$(gh api user --jq .login)"
10
export REPOSITORY="${GITHUB_OWNER}/cloudflare_temp_email"

set +x prevents shell tracing from echoing later values. It does not repair a secret that has already reached logs or shell history. Revoke any exposed token.

Fork and clone the repository#

For a new fork:

1
gh repo fork "$UPSTREAM_REPO" --clone --default-branch-only
2
cd cloudflare_temp_email

If the fork already exists:

1
gh repo clone "$REPOSITORY"
2
cd cloudflare_temp_email
3
git remote add upstream \
4
  "https://github.com/${UPSTREAM_REPO}.git" \
5
  2>/dev/null || true

Fork with the GitHub website#

Open the upstream repository on GitHub.
Select Fork, choose the destination owner, and select Create fork.
On the new fork, select Code and copy its HTTPS URL.
Clone that URL with GitHub Desktop or your preferred Git client.
Add the upstream repository as an upstream remote when it is absent.

Inspect the exact source that will be deployed:

1
git remote -v
2
git status --short --branch
3
git show --no-patch --oneline HEAD

Resolve the Cloudflare account#

If Wrangler reports exactly one account, extract its ID without copying terminal text:

1
export CLOUDFLARE_ACCOUNT_ID="$(
2
  wrangler whoami --json |
3
    jq -er '
4
      .accounts |
5
      if length == 1 then
6
        .[0].id
7
      else
8
        error("more than one account; choose explicitly")
9
      end
10
    '
11
)"

For multiple accounts, inspect the candidates and enter the intended ID privately:

1
wrangler whoami --json |
2
  jq -r '.accounts[] | [.name, .id] | @tsv'
3

4
printf 'Cloudflare Account ID: ' >&2
5
IFS= read -r CLOUDFLARE_ACCOUNT_ID
6
export CLOUDFLARE_ACCOUNT_ID

Find the Account ID in Cloudflare#

Open the Cloudflare dashboard and select the intended account.
Open the account or zone Overview page.
Find Account ID in the account details panel and copy it privately.
Compare the account name with wrangler whoami before using the ID.

Phase 2: Provision storage and configuration#

Create and initialize D1#

Create the remote database. Change the location hint when appropriate.

1
wrangler d1 create "$D1_DATABASE_NAME" --location wnam

Resolve the database UUID from JSON:

1
export D1_DATABASE_ID="$(
2
  wrangler d1 list --json |
3
    jq -er --arg name "$D1_DATABASE_NAME" \
4
      '[.[] | select(.name == $name)] |
5
       if length == 1 then
6
         .[0].uuid
7
       else
8
         error("database name is missing or not unique")
9
       end'
10
)"

Apply the schema from the same reviewed commit as the Worker code:

1
wrangler d1 execute "$D1_DATABASE_NAME" \
2
  --remote \
3
  --file db/schema.sql \
4
  --yes

Verify that the remote tables exist:

1
wrangler d1 execute "$D1_DATABASE_NAME" \
2
  --remote \
3
  --command "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;" \
4
  --json |
5
  jq

Create D1 in the Cloudflare dashboard#

Go to Storage & Databases → D1 SQL Database.
Select Create Database, enter D1_DATABASE_NAME, choose an optional location, and select Create.
Copy the database ID from the new database’s details page.
Open the database’s Console tab.
Paste db/schema.sql from the same reviewed repository commit and run it.
Open Tables or rerun the table query in Console to verify initialization.

Do not paste a schema copied from a different upstream revision.

Generate a private bootstrap configuration#

Create a private temporary directory that will be deleted when the shell exits:

1
umask 077
2
export PRIVATE_TMP="$(mktemp -d)"
3
trap 'rm -rf "$PRIVATE_TMP"' EXIT
4
export BACKEND_TOML_PATH="$PRIVATE_TMP/backend.toml"

Create the file shown above. Replace the example domain and D1 UUID with the values resolved earlier. Address creation starts disabled so the first deployment cannot become an open mailbox service before passwords are installed.

1
name = "cloudflare_temp_email"
2
main = "src/worker.ts"
3
compatibility_date = "2025-04-01"
4
compatibility_flags = ["nodejs_compat"]
5
keep_vars = true
6

7
routes = [
8
  { pattern = "mail.example.com", custom_domain = true }
9
]
10

11
[assets]
12
directory = "../frontend/dist/"
13
binding = "ASSETS"
14
run_worker_first = true
15

16
[triggers]
17
crons = ["0 0 * * *"]
18

19
[vars]
20
PREFIX = "tmp"
21
DOMAINS = ["example.com"]
22
DEFAULT_DOMAINS = ["example.com"]
23
ENABLE_USER_CREATE_EMAIL = false
24
ENABLE_USER_DELETE_EMAIL = true
25
ENABLE_ADDRESS_PASSWORD = true
26

27
[[d1_databases]]
28
binding = "DB"
29
database_name = "temp-email-db"
30
database_id = "<D1_DATABASE_ID>"

After saving the file, restrict its permissions:

1
chmod 600 "$BACKEND_TOML_PATH"

Do not put JWT_SECRET, PASSWORDS, or ADMIN_PASSWORDS in this file. Upload them as Worker secrets. Do not copy the file into the repository: even without passwords, it contains a real domain and D1 UUID.

Understand dashboard configuration ownership#

After the Worker exists, the dashboard can add the DB binding under Settings → Bindings and the hostname under Settings → Domains & Routes. However, the next GitHub Actions deployment reconciles those settings from BACKEND_TOML. Treat the TOML secret as the source of truth and use the dashboard for verification or recovery, not as an independent long-term configuration.

Phase 3: Deploy a protected Worker#

Create a short-lived bootstrap token#

Cloudflare’s current granular permission model requires Workers product-level Admin to create a Worker. Updating an existing Worker can use single-Worker Editor.

Create a temporary bootstrap token with only:

Scope	Permission	Why
Target account	Workers product: Admin	Create the first Worker deployment
Target zone	Workers Routes: Write	Attach the custom domain
Target zone	Zone: Read	Resolve the selected zone

It does not need DNS, Email Routing, or D1 edit access. The D1 database already exists and is only referenced as a binding. Older token interfaces may use legacy permission names; check the current Workers permissions documentation instead of granting all resources.

Enter the token without placing it in a command argument:

1
CF_CI_API_TOKEN=''
2
while [ -z "$CF_CI_API_TOKEN" ]; do
3
  printf 'Non-empty Cloudflare Bootstrap Token: ' >&2
4
  IFS= read -r -s CF_CI_API_TOKEN
5
  printf '\n' >&2
6
done
7

8
printf '%s' "$CF_CI_API_TOKEN" |
9
  gh secret set CLOUDFLARE_API_TOKEN --repo "$REPOSITORY"
10

11
unset CF_CI_API_TOKEN

Save the bootstrap token manually#

On Cloudflare’s API Tokens page, create the bootstrap token with the three scopes listed above.
On the GitHub fork, open Settings → Secrets and variables → Actions.
Select New repository secret.
Name it CLOUDFLARE_API_TOKEN, paste the token, and select Add secret.

Configure GitHub Actions secrets#

The backend workflow reads this repository-secret contract:

CLOUDFLARE_ACCOUNT_ID (required): select the Cloudflare account;
CLOUDFLARE_API_TOKEN (required): authenticate the deployment;
BACKEND_TOML (required): supply the Worker configuration;
USE_WORKER_ASSETS (required here): bundle Webmail into the Worker;
BACKEND_USE_MAIL_WASM_PARSER (recommended): enable the WASM parser;
DEBUG_MODE (optional): print detailed output when set to true.

JWT_SECRET, PASSWORDS, and ADMIN_PASSWORDS are Worker runtime secrets, not GitHub Actions secrets. Upload them later with wrangler secret bulk.

1
printf '%s' "$CLOUDFLARE_ACCOUNT_ID" |
2
  gh secret set CLOUDFLARE_ACCOUNT_ID --repo "$REPOSITORY"
3

4
gh secret set BACKEND_TOML \
5
  --repo "$REPOSITORY" \
6
  < "$BACKEND_TOML_PATH"
7

8
printf '%s' 'true' |
9
  gh secret set USE_WORKER_ASSETS --repo "$REPOSITORY"
10

11
printf '%s' 'true' |
12
  gh secret set BACKEND_USE_MAIL_WASM_PARSER --repo "$REPOSITORY"
13

14
printf '%s' 'false' |
15
  gh secret set DEBUG_MODE --repo "$REPOSITORY"

Add repository secrets in GitHub#

Open Settings → Secrets and variables → Actions → Secrets on the fork.
Select New repository secret for each name in the contract above.
Paste the corresponding value and select Add secret.
For BACKEND_TOML, paste the complete contents of the private TOML file.
Return to the secrets list and confirm that all six names are present.

GitHub shows secret names and update times after saving, but never reveals the values.

Keep DEBUG_MODE=false. A public fork’s detailed Wrangler output can reveal domains, Worker names, bindings, D1 identifiers, and deployment IDs.

Verify names and timestamps without attempting to read secret values:

1
gh secret list --repo "$REPOSITORY"

The GitHub workflow installs its own Node.js and pnpm. Neither needs a separate manual setup step; Homebrew manages the runtime dependency of its Wrangler formula.

Enable only the required workflow#

1
gh workflow enable backend_deploy.yaml --repo "$REPOSITORY"
2
gh workflow disable sync.yaml --repo "$REPOSITORY"
3
gh workflow disable frontend_deploy.yaml --repo "$REPOSITORY"
4
gh workflow disable frontend_pagefunction_deploy.yaml --repo "$REPOSITORY"
5

6
gh workflow list --repo "$REPOSITORY" --all

Enable workflows in GitHub#

Open the fork’s Actions tab and enable workflows if GitHub shows the fork confirmation banner.
Select Deploy Backend and choose Enable workflow if it is disabled.
Open each unused frontend workflow’s menu and choose Disable workflow.
Keep Upstream Sync disabled until the initial deployment is verified.

Define a fail-closed deployment function#

The function below refuses dirty or mismatched source, verifies the dispatched headSha, and cancels the run if GitHub does not execute the reviewed commit.

1
deploy_reviewed_main() (
2
  set -euo pipefail
3

4
  local deploy_commit remote_main run_url run_id run_head
5
  deploy_commit="$(git rev-parse HEAD)"
6
  remote_main="$(gh api "repos/${REPOSITORY}/commits/main" --jq .sha)"
7

8
  git status --short --branch
9
  git show --no-patch --oneline "$deploy_commit"
10

11
  if [ -n "$(git status --porcelain)" ]; then
12
    printf 'Refusing to deploy a dirty working tree.\n' >&2
13
    return 1
14
  fi
15

16
  if [ "$deploy_commit" != "$remote_main" ]; then
17
    printf 'Local HEAD does not match remote main.\n' >&2
18
    return 1
19
  fi
20

21
  run_url="$(
22
    gh workflow run backend_deploy.yaml \
23
      --repo "$REPOSITORY" \
24
      --ref main
25
  )"
26

27
  if [ -z "$run_url" ]; then
28
    printf 'GitHub CLI did not return a workflow URL.\n' >&2
29
    return 1
30
  fi
31

32
  run_id="${run_url##*/}"
33
  run_head="$(
34
    gh run view "$run_id" \
35
      --repo "$REPOSITORY" \
36
      --json headSha \
37
      --jq .headSha
38
  )"
39

40
  if [ "$run_head" != "$deploy_commit" ]; then
41
    gh run cancel "$run_id" --repo "$REPOSITORY"
42
    printf 'Canceled run: dispatched commit did not match.\n' >&2
43
    return 1
44
  fi
45

46
  gh run watch "$run_id" \
47
    --repo "$REPOSITORY" \
48
    --compact \
49
    --exit-status
50
)

Run the protected bootstrap deployment:

1
deploy_reviewed_main

Run the initial deployment in GitHub#

Confirm the reviewed commit is the current commit on the fork’s main branch.
Open Actions → Deploy Backend.
Select Run workflow, choose main, and select Run workflow again.
Open the new run and verify its commit SHA immediately.
If it differs from the reviewed commit, select Cancel workflow and stop.
Only when the SHA matches, wait for every deployment step to succeed.

Install application secrets#

Use different, non-empty site and administrator passwords:

1
SITE_PASSWORD=''
2
ADMIN_PASSWORD=''
3

4
while [ -z "$SITE_PASSWORD" ]; do
5
  printf 'Non-empty site access password: ' >&2
6
  IFS= read -r -s SITE_PASSWORD
7
  printf '\n' >&2
8
done
9

10
while [ -z "$ADMIN_PASSWORD" ]; do
11
  printf 'Non-empty admin password: ' >&2
12
  IFS= read -r -s ADMIN_PASSWORD
13
  printf '\n' >&2
14
done
15

16
if [ "$SITE_PASSWORD" = "$ADMIN_PASSWORD" ]; then
17
  printf 'Site and admin passwords must be different.\n' >&2
18
else
19
  jq -cn \
20
    --arg jwt "$(openssl rand -base64 48)" \
21
    --arg site "$SITE_PASSWORD" \
22
    --arg admin "$ADMIN_PASSWORD" \
23
    '{
24
      JWT_SECRET: $jwt,
25
      PASSWORDS: ([$site] | tojson),
26
      ADMIN_PASSWORDS: ([$admin] | tojson)
27
    }' |
28
    wrangler secret bulk --name "$WORKER_NAME"
29
fi
30

31
unset SITE_PASSWORD ADMIN_PASSWORD

Verify that all three secret names exist:

1
wrangler secret list --name "$WORKER_NAME"

Add Worker secrets in Cloudflare#

Generate a JWT secret locally with openssl rand -base64 48.
Go to Workers & Pages → your Worker → Settings.
Under Variables and Secrets, select Add and choose Secret.
Add JWT_SECRET with the generated value.
Add PASSWORDS as a JSON array string containing the site password.
Add ADMIN_PASSWORDS as a JSON array string containing the admin password.
Add all three changes to one version, then select Deploy.

Do not create these as plaintext variables.

Open https://$MAIL_WEB_DOMAIN in a private browser window. Confirm that no password and an incorrect password are rejected, while the site password succeeds.

Only after that check should address creation be enabled:

1
awk '
2
  /^ENABLE_USER_CREATE_EMAIL = false$/ {
3
    print "ENABLE_USER_CREATE_EMAIL = true"
4
    next
5
  }
6
  { print }
7
' "$BACKEND_TOML_PATH" > "$BACKEND_TOML_PATH.next"
8

9
mv "$BACKEND_TOML_PATH.next" "$BACKEND_TOML_PATH"
10
chmod 600 "$BACKEND_TOML_PATH"
11

12
gh secret set BACKEND_TOML \
13
  --repo "$REPOSITORY" \
14
  < "$BACKEND_TOML_PATH"
15

16
deploy_reviewed_main

Enable address creation in GitHub#

Change ENABLE_USER_CREATE_EMAIL from false to true in the retained private $BACKEND_TOML_PATH file.
Open Settings → Secrets and variables → Actions → Secrets.
Select BACKEND_TOML, then select Update secret.
Paste the complete revised TOML file and save the secret.
Run Deploy Backend using the protected SHA-check procedure above.

Rotate to a steady-state token#

Create a new token with Editor scoped only to the existing $WORKER_NAME. Because the custom-domain connection already exists and remains unchanged, future deployments do not need zone route write access. A later route change will fail closed.

1
CF_CI_API_TOKEN=''
2
while [ -z "$CF_CI_API_TOKEN" ]; do
3
  printf 'Non-empty steady-state Worker Editor token: ' >&2
4
  IFS= read -r -s CF_CI_API_TOKEN
5
  printf '\n' >&2
6
done
7

8
printf '%s' "$CF_CI_API_TOKEN" |
9
  gh secret set CLOUDFLARE_API_TOKEN --repo "$REPOSITORY"
10

11
deploy_reviewed_main
12
unset CF_CI_API_TOKEN

Rotate the CI token manually#

On Cloudflare’s API Tokens page, create a token with Editor access scoped only to the existing Worker.
On GitHub, open Settings → Secrets and variables → Actions.
Select CLOUDFLARE_API_TOKEN, choose Update secret, and paste the new token.
Run Deploy Backend using the protected SHA-check procedure above.
Return to Cloudflare’s API Tokens page and revoke the bootstrap token.

For either path, do not leave the broad and narrow tokens active together.

Phase 4: Route incoming email#

Preserve the current DNS state#

The next function stores complete MX and TXT responses in a persistent private file. It fails if either DNS query fails or returns a status other than NOERROR.

1
snapshot_email_dns() (
2
  set -euo pipefail
3

4
  local backup_dir stamp snapshot mx_result txt_result
5
  backup_dir="${XDG_STATE_HOME:-$HOME/.local/state}/cloudflare-email-routing"
6
  stamp="$(date -u +%Y%m%dT%H%M%SZ)"
7
  snapshot="$backup_dir/${ROOT_DOMAIN}-${stamp}.txt"
8

9
  mkdir -p "$backup_dir"
10
  chmod 700 "$backup_dir"
11

12
  mx_result="$(
13
    dig +noall +comments +answer MX "$ROOT_DOMAIN"
14
  )"
15
  txt_result="$(
16
    dig +noall +comments +answer TXT "$ROOT_DOMAIN"
17
  )"
18

19
  printf '%s\n' "$mx_result" | grep -q 'status: NOERROR'
20
  printf '%s\n' "$txt_result" | grep -q 'status: NOERROR'
21

22
  {
23
    printf '# Captured at %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
24
    printf '\n## MX\n%s\n' "$mx_result"
25
    printf '\n## TXT\n%s\n' "$txt_result"
26
  } > "$snapshot"
27

28
  chmod 600 "$snapshot"
29
  printf '%s\n' "$snapshot"
30
)
31

32
DNS_SNAPSHOT="$(snapshot_email_dns)"
33
export DNS_SNAPSHOT
34
less "$DNS_SNAPSHOT"

Snapshot DNS in Cloudflare#

Select the zone in Cloudflare and open DNS → Records.
Record or export every existing MX record and mail-related TXT record, including SPF values and TTLs.
Save the snapshot outside the repository in a private location.
Identify the provider behind each MX record before changing Email Routing.

Human confirmation: MX replacement
If the snapshot contains MX records, identify the service behind every record. Do not continue until losing that service is acceptable and its restoration procedure is documented. Wrangler’s dns get shows Cloudflare’s requirements; it does not inventory the provider currently serving your email.

Read the current Email Routing state and Cloudflare’s required DNS changes:

1
wrangler email routing settings "$ROOT_DOMAIN"
2
wrangler email routing dns get "$ROOT_DOMAIN"

Prepare catch-all API access#

Wrangler’s help lists worker as an action type, but its catch-all validation still rejects Worker actions. Use Cloudflare’s catch-all REST endpoint with the local routing API token instead.

Skip this API preparation when using the dashboard path in the next section.

Read the token without exposing it in command history, then resolve the target zone:

1
CF_ROUTING_API_TOKEN=''
2
while [ -z "$CF_ROUTING_API_TOKEN" ]; do
3
  printf 'Non-empty Cloudflare routing API token: ' >&2
4
  IFS= read -r -s CF_ROUTING_API_TOKEN
5
  printf '\n' >&2
6
done
7
export CF_ROUTING_API_TOKEN
8

9
cloudflare_auth_header() {
10
  printf 'Authorization: Bearer %s\n' "$CF_ROUTING_API_TOKEN"
11
}
12

13
export CF_ZONE_ID="$(
14
  curl --fail --silent --show-error --get \
15
    "https://api.cloudflare.com/client/v4/zones" \
16
    --header @<(cloudflare_auth_header) \
17
    --data-urlencode "name=$ROOT_DOMAIN" \
18
    --data-urlencode "account.id=$CLOUDFLARE_ACCOUNT_ID" |
19
    jq -er '
20
      if .success and (.result | length == 1) then
21
        .result[0].id
22
      else
23
        error("target zone is missing or not unique")
24
      end
25
    '
26
)"

Define update and read-back helpers. The token is passed through an anonymous file descriptor instead of a process argument:

1
update_worker_catch_all() (
2
  set -euo pipefail
3

4
  local api_url enabled payload
5
  api_url="https://api.cloudflare.com/client/v4/zones"
6
  api_url+="/${CF_ZONE_ID}/email/routing/rules/catch_all"
7
  enabled="${1:?enabled must be true or false}"
8
  payload="$(
9
    jq -cn \
10
      --arg worker "$WORKER_NAME" \
11
      --argjson enabled "$enabled" \
12
      '{
13
        actions: [{type: "worker", value: [$worker]}],
14
        matchers: [{type: "all"}],
15
        enabled: $enabled,
16
        name: "Send catch-all to temp email Worker",
17
        source: "api"
18
      }'
19
  )"
20

21
  printf '%s' "$payload" |
22
    curl --fail --silent --show-error \
23
      --request PUT \
24
      "$api_url" \
25
      --header @<(cloudflare_auth_header) \
26
      --header 'Content-Type: application/json' \
27
      --data-binary @- |
28
    jq -e '
29
      if .success then
30
        .result
31
      else
32
        error(.errors | map(.message) | join("; "))
33
      end
34
    '
35
)
36

37
read_worker_catch_all() (
38
  local api_url="https://api.cloudflare.com/client/v4/zones"
39
  api_url+="/${CF_ZONE_ID}/email/routing/rules/catch_all"
40

41
  curl --fail --silent --show-error \
42
    "$api_url" \
43
    --header @<(cloudflare_auth_header) |
44
    jq -e '
45
      if .success then
46
        .result
47
      else
48
        error(.errors | map(.message) | join("; "))
49
      end
50
    '
51
)

Enable routing and the Worker catch-all#

1
wrangler email routing enable "$ROOT_DOMAIN"
2
update_worker_catch_all true

Configure Email Routing in Cloudflare#

Go to Compute → Email Service → Email Routing.
Select Onboard Domain and choose ROOT_DOMAIN.
Review the MX and TXT records that Cloudflare will add, then select Done.
Select the domain and open Routing Rules.
Edit or enable Catch-all rule.
Set Action to Send to a Worker and select WORKER_NAME.
Set the rule to Active and select Save.

Read everything back:

1
wrangler email routing settings "$ROOT_DOMAIN"
2
wrangler email routing dns get "$ROOT_DOMAIN"
3
read_worker_catch_all

Roll back Email Routing#

To reverse the routing change, disable the catch-all before disabling Email Routing:

1
update_worker_catch_all false
2
read_worker_catch_all
3
wrangler email routing disable "$ROOT_DOMAIN"

Roll back routing in Cloudflare#

For a provider migration without an intentional mail outage:

Go to Compute → Email Service → Email Routing and select ROOT_DOMAIN.
Under Settings, unlock the routing MX, SPF, and DKIM records.
In DNS → Records, add the former provider’s records from the private snapshot.
Verify the replacement provider’s required records and mail flow.
Return to Routing Rules and disable Catch-all rule.
Return to Settings, select Disable Email Routing, and confirm.
Verify that the replacement provider’s records remain and still receive mail.

If the goal is to stop receiving mail entirely, skip steps 2–4, disable the catch-all, then disable Email Routing.

Disabling Email Routing removes Cloudflare-managed routing records but does not restore a previous provider. Restore its records from $DNS_SNAPSHOT and the saved configuration. Never commit the snapshot or attach it to a public issue.

After the routing read-back succeeds, unset and revoke CF_ROUTING_API_TOKEN. Create a new narrowly scoped token if API rollback is needed later. Dashboard rollback does not require this token.

Verification#

Worker deployment#

1
wrangler deployments list \
2
  --name "$WORKER_NAME" \
3
  --json |
4
  jq

Verify the Worker in Cloudflare#

Go to Workers & Pages and select WORKER_NAME.
Open Deployments and confirm the latest deployment succeeded.
Under Settings → Domains & Routes, confirm MAIL_WEB_DOMAIN is active.
Under Settings → Bindings, confirm the D1 binding is named DB.

Web interface#

1
curl --fail --silent --show-error \
2
  --output /dev/null \
3
  --write-out '%{http_code}\n' \
4
  "https://${MAIL_WEB_DOMAIN}/"

Expect HTTP 200, then verify that the site password is required and create a test address.

Administration and database state#

Open https://$MAIL_WEB_DOMAIN/admin and sign in as an administrator. Under Quick Setup → Database, confirm the schema is healthy. Reinitialize only when the current migration guide requires it.

End-to-end delivery#

Watch only error events in one terminal:

1
wrangler tail "$WORKER_NAME" \
2
  --format pretty \
3
  --status error

Send a non-sensitive message from an external mailbox to the test address. In another terminal, inspect the newest D1 rows:

1
wrangler d1 execute "$D1_DATABASE_NAME" \
2
  --remote \
3
  --command \
4
  'SELECT address, created_at FROM raw_mails ORDER BY id DESC LIMIT 5;' \
5
  --json |
6
  jq

Verify delivery in Cloudflare#

Open the Worker in Workers & Pages, then open its live logs or observability view before sending the test message.
Send the test message and confirm that the Worker invocation has no exception.
Open Storage & Databases → D1 SQL Database → your database → Console.
Run the same SELECT query and confirm the new address and timestamp appear.

The deployment is complete only when all of these are true:

The catch-all rule is enabled and targets the intended Worker.
The Worker error tail remains clean during the test.
Webmail displays the test message.
D1 contains the test address with a reasonable timestamp.

Do not test with real invoices, one-time passwords, resumes, recovery links, or other sensitive mail.

Maintenance#

Review upstream changes before deployment#

Keep Upstream Sync disabled if every release must be reviewed. Inspect releases, the changelog, configuration changes, and D1 migrations before merging an update:

1
git fetch upstream
2
git log --oneline HEAD..upstream/main
3
git diff --stat HEAD...upstream/main
4
git diff --name-only HEAD...upstream/main -- db

Review upstream in GitHub#

Open the fork and select Sync fork → Compare instead of updating immediately.
Review the upstream Releases and CHANGELOG since the deployed revision.
Inspect changed files, especially .github/workflows, db, and Worker config.
Apply required D1 migrations before deploying code that depends on them.
Merge only the reviewed update into the fork’s main branch.

Back up D1 before an upgrade. If upstream documents a schema migration, run the specific reviewed migration before dispatching Deploy Backend. Do not replay the full schema blindly against a production database.

Optional: enable automatic upstream sync#

The project’s official auto-update guide uses the Upstream Sync workflow. Enable it only after the initial deployment and end-to-end verification succeed.

Understand what auto-sync changes
Auto-sync can merge upstream code and workflow changes into the production branch. It does not execute D1 SQL migrations. The backend workflow also reacts when Upstream Sync completes, so verify the sync and the following deployment. Review breaking changes and apply required D1 migrations separately.

The sync workflow uses GITHUB_TOKEN to write to the fork. Allow repository contents write access, without allowing workflows to approve pull requests:

1
gh api --method PUT "repos/${REPOSITORY}/actions/permissions/workflow" \
2
  -f default_workflow_permissions=write \
3
  -F can_approve_pull_request_reviews=false

This setting is repository-wide. Review every enabled workflow first, then enable the sync and backend workflows:

1
gh workflow enable sync.yaml --repo "$REPOSITORY"
2
gh workflow enable backend_deploy.yaml --repo "$REPOSITORY"
3
gh workflow list --repo "$REPOSITORY" --all

Trigger Upstream Sync manually the first time instead of waiting for its weekly schedule. This confirms immediately that the permission and upstream relationship work:

1
trigger_first_sync() (
2
  set -euo pipefail
3

4
  local run_url run_id
5
  run_url="$(
6
    gh workflow run sync.yaml \
7
      --repo "$REPOSITORY" \
8
      --ref main
9
  )"
10

11
  if [ -z "$run_url" ]; then
12
    printf 'GitHub CLI did not return a sync run URL.\n' >&2
13
    return 1
14
  fi
15

16
  run_id="${run_url##*/}"
17
  gh run watch "$run_id" \
18
    --repo "$REPOSITORY" \
19
    --compact \
20
    --exit-status
21
)
22

23
trigger_first_sync

Enable auto-sync in GitHub#

Open Settings → Actions → General on the fork.
Under Workflow permissions, select Read and write permissions.
Leave the pull-request approval option unchecked, then select Save.
Open Actions → Upstream Sync and select Enable workflow.
Select Run workflow, choose main, and start the first run manually.
Wait for the sync to succeed, then verify the resulting Deploy Backend run.

After the sync succeeds, verify the sync and the triggered backend deployment:

1
gh run list \
2
  --repo "$REPOSITORY" \
3
  --workflow sync.yaml \
4
  --limit 3
5

6
gh run list \
7
  --repo "$REPOSITORY" \
8
  --workflow backend_deploy.yaml \
9
  --limit 3

Future scheduled syncs use the cron expression in .github/workflows/sync.yaml. Review that file to change the interval. Disable automatic sync at any time:

1
gh workflow disable sync.yaml --repo "$REPOSITORY"

Configure retention#

The daily Cron Trigger only wakes the Worker; it does not define a retention policy. Configure and verify cleanup in the administration interface so D1 does not grow without limit and test mail does not remain indefinitely.

Configure retention manually#

Open the Webmail administration interface and configure the cleanup policy.
In Cloudflare, open Workers & Pages → your Worker → Settings.
Confirm the daily Cron Trigger is present under trigger settings.
Recheck D1 usage after the first scheduled cleanup.

Clean the local session#

1
wrangler logout
2
unset CLOUDFLARE_ACCOUNT_ID D1_DATABASE_ID ROOT_DOMAIN MAIL_WEB_DOMAIN
3
unset WORKER_NAME D1_DATABASE_NAME GITHUB_OWNER REPOSITORY
4
unset DNS_SNAPSHOT CF_ROUTING_API_TOKEN CF_ZONE_ID

wrangler logout invalidates OAuth and removes stored credentials. The EXIT trap removes the temporary Worker config but preserves the DNS rollback snapshot.

Troubleshooting#

`Authentication error [code: 10000]`#

The CI token, account ID, or resource scope does not match. Confirm that the token belongs to the target account and that the GitHub secret has no quotes or newline.

The custom domain returns 404#

Confirm that USE_WORKER_ASSETS exists, BACKEND_TOML contains [assets], and the route uses custom_domain = true.

`Catch-all rule only supports 'forward' or 'drop' action types`#

Wrangler currently rejects Worker actions for catch-all rules even though its help lists worker. Use the catch-all REST helpers from Phase 4 and read the rule back.

`Cannot read properties of undefined (reading 'map')`#

Open /open_api/settings and confirm that it returns valid JSON. This error usually means a JSON-shaped variable is missing or malformed. Check DOMAINS and DEFAULT_DOMAINS, then confirm the password secrets contain JSON array strings.

`D1_ERROR: no such table`#

For a new empty database, apply the schema from the exact deployed commit:

1
wrangler d1 execute "$D1_DATABASE_NAME" \
2
  --remote \
3
  --file db/schema.sql \
4
  --yes

For an existing database, use the specific migration documented for the upgrade.

`D1_ERROR: Exceeded maximum DB size`#

The database can no longer store mail. Remove unneeded messages and configure cleanup. Confirm the Worker has a Cron Trigger, then review D1 limits before changing retention.

`Upstream Sync` cannot push#

Read back the repository workflow permission:

1
gh api "repos/${REPOSITORY}/actions/permissions/workflow"

default_workflow_permissions must be write. The sync workflow does not need permission to approve pull requests.

Mail does not arrive#

1
wrangler email routing settings "$ROOT_DOMAIN"
2
wrangler email routing dns get "$ROOT_DOMAIN"
3
wrangler email routing rules get "$ROOT_DOMAIN" catch-all

Confirm that no old provider MX records remain, then inspect the Worker error tail.

Introduction#

Overview#

Deployment phases#

Prerequisites#

Accounts and domain#

Deployment inputs#

Cloudflare credentials and permissions#

Using the CLI#

Using the Cloudflare website UI#

Local tools#

Phase 1: Prepare the source and account#

Set session variables#

Fork and clone the repository#

Fork with the GitHub website#

Resolve the Cloudflare account#

Find the Account ID in Cloudflare#

Phase 2: Provision storage and configuration#

Create and initialize D1#

Create D1 in the Cloudflare dashboard#

Generate a private bootstrap configuration#

Understand dashboard configuration ownership#

Phase 3: Deploy a protected Worker#

Create a short-lived bootstrap token#

Save the bootstrap token manually#

Configure GitHub Actions secrets#

Add repository secrets in GitHub#

Enable only the required workflow#

Enable workflows in GitHub#

Define a fail-closed deployment function#

Run the initial deployment in GitHub#

Install application secrets#

Add Worker secrets in Cloudflare#

Enable address creation in GitHub#

Rotate to a steady-state token#

Rotate the CI token manually#

Phase 4: Route incoming email#

Preserve the current DNS state#

Snapshot DNS in Cloudflare#

Prepare catch-all API access#

Enable routing and the Worker catch-all#

Configure Email Routing in Cloudflare#

Roll back Email Routing#

Roll back routing in Cloudflare#

Verification#

Worker deployment#

Verify the Worker in Cloudflare#

Web interface#

Administration and database state#

End-to-end delivery#

Verify delivery in Cloudflare#

Maintenance#

Review upstream changes before deployment#

Review upstream in GitHub#

Optional: enable automatic upstream sync#

Enable auto-sync in GitHub#

Configure retention#

Configure retention manually#

Clean the local session#

Troubleshooting#

Authentication error [code: 10000]#

The custom domain returns 404#

Catch-all rule only supports 'forward' or 'drop' action types#

Cannot read properties of undefined (reading 'map')#

D1_ERROR: no such table#

D1_ERROR: Exceeded maximum DB size#

Upstream Sync cannot push#

Mail does not arrive#

References#

Project documentation#

Cloudflare platform#

GitHub Actions#

Tooling#

`Authentication error [code: 10000]`#

`Catch-all rule only supports 'forward' or 'drop' action types`#

`Cannot read properties of undefined (reading 'map')`#

`D1_ERROR: no such table`#

`D1_ERROR: Exceeded maximum DB size`#

`Upstream Sync` cannot push#