Setup Guide

Deployment Preparation

Nodejs v18.20 +

Cloudflare account (with a bound domain)

Clone the project to your local machine:

git clone https://github.com/eoao/cloud-mail
cd cloud-mail/mail-worker

Install Dependencies:

npm i

Configure the Project

mail-worker/wrangler.toml

[[d1_databases]]
binding = "db"			# Default binding name for D1 database, cannot be changed
database_name = ""		# Database name
database_id = ""		# Database ID

[[kv_namespaces]]
binding = "kv"			# Default binding name for KV storage, cannot be changed
id = ""			        # KV namespace ID


[[r2_buckets]]
binding = "r2"                  # Default binding name for R2 storage, cannot be changed
bucket_name = ""	        # R2 bucket name

[assets]
binding = "assets"		# Static asset binding name, cannot be changed
directory = "./dist"	        # Directory for frontend Vue project build, default: dist

[triggers]
crons = ["0 16 * * *"]	# A scheduled job runs at 00:00 every day

[vars]
orm_log = false
domain = []			# Configure email domains, example: ["example1.com", "example2.com"]
admin = ""		        # Admin email, example: "admin@example.com"
jwt_secret = ""			# JWT secret for login tokens, choose a random string

Remote Deployment

1. Create KV, D1 database, and R2 object storage in Cloudflare Console.

2. In the project directory mail-worker/wrangler.toml, configure the environment variables and database IDs/names.

3. Run the deployment command:

   npm run deploy

4. In Cloudflare → Account Home → Your Domain → Email → Email Routing → Route Rules → Catch-all Address, edit and route to the worker.

5. In your browser, visit https://your-project-domain/api/init/your-jwt-secret to initialize or update the D1 and KV databases.

6. After deployment, log in to the site with the admin account to configure R2 domains, Turnstile keys, and more.

Run Locally

1. Run locally. Databases and object storage will automatically be set up, no manual creation needed. Data is stored in the mail-worker/.wrangler folder.

   npm run dev

2. In your browser, visit http://127.0.0.1:8787/api/init/your-jwt-secret to initialize D1 and KV databases.

3. For local testing, you can set the R2 domain to http://127.0.0.1:8787/api/file.

Email Sending

1. Register on Resend, then click on “Domains” to add and verify your domain. Wait for verification.

2. Go to "API Keys" to create an API key, then copy the token and paste it in the project website settings.

3. Go to "Webhooks" and add a callback URL https://your-project-domain/api/webhooks.
   Select the following events: ✅ (email.bounced, email.complained, email.delivered, email.delivery_delayed).