Offload Email Worker

A Cloudflare Worker that receives emails at *@offloadmy.work, stores them in a D1 database, and exposes a REST API for email management.

Features

• ✉️ Receives emails via Cloudflare Email Routing
• 💾 Stores emails in D1 database (from, to, subject, body, headers)
• 🔐 Secure REST API with Bearer token authentication
• 📊 Email statistics (total, unread, starred)
• ⭐ Mark emails as read/starred
• 🗑️ Delete emails
• 🌐 CORS enabled for web clients

API Endpoints

All endpoints require Authorization: Bearer YOUR_API_TOKEN header.

GET /api/emails

List emails with optional filters:

• ?limit=50 - Limit results (default: 50)
• ?offset=0 - Pagination offset (default: 0)
• ?unread=true - Only unread emails

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://email.offloadmy.work/api/emails?limit=10&unread=true"

GET /api/emails/:id

Get a single email by ID.

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://email.offloadmy.work/api/emails/abc-123-def

PATCH /api/emails/:id

Update email properties (mark as read, star).

Example:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read": true, "starred": true}' \
  https://email.offloadmy.work/api/emails/abc-123-def

DELETE /api/emails/:id

Delete an email.

Example:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://email.offloadmy.work/api/emails/abc-123-def

GET /api/stats

Get email statistics.

Response:

{
  "total": 42,
  "unread": 5,
  "starred": 3
}

Setup

Prerequisites

• Cloudflare account
• Domain configured in Cloudflare (offloadmy.work)
• Wrangler CLI authenticated

Installation

1. Clone and install:

cd /Users/netanelgilad/development/offload-email-worker
npm install

2. Configure your API token:

# Your API token is stored in:
cat ~/.config/offload/email-worker.json

3. Deploy:

npx wrangler deploy

Required Manual Configuration

After deploying, you need to:

1. Add DNS Record

1. Go to Cloudflare Dashboard
2. Select offloadmy.work domain
3. Go to DNS → Records
4. Add record:
   • Type: A or AAAA (or CNAME if you have a workers.dev subdomain)
   • Name: email
   • Content: Point to your Cloudflare Worker (usually automatic with routes)
   • Proxy: ✅ ON (orange cloud)

2. Configure Email Routing

1. Go to Cloudflare Dashboard
2. Select offloadmy.work domain
3. Go to Email → Email Routing
4. Enable Email Routing if not already enabled
5. Add Email Worker route:
   • Pattern: *@offloadmy.work (catch-all)
   • Action: Send to Worker
   • Worker: offload-email

See DEPLOY_LOG.md for detailed step-by-step instructions.

Database Schema

CREATE TABLE emails (
  id TEXT PRIMARY KEY,
  from_address TEXT NOT NULL,
  to_address TEXT NOT NULL,
  subject TEXT,
  body_text TEXT,
  body_html TEXT,
  headers TEXT,  -- JSON string
  received_at TEXT NOT NULL,
  read INTEGER DEFAULT 0,
  starred INTEGER DEFAULT 0
);

Development

Local Testing

npx wrangler dev

View Logs

npx wrangler tail offload-email

Access D1 Database

# Local
npx wrangler d1 execute email-store --command "SELECT * FROM emails LIMIT 10"

# Remote
npx wrangler d1 execute email-store --remote --command "SELECT * FROM emails LIMIT 10"

Security

• API is protected with Bearer token authentication
• Token is stored in ~/.config/offload/email-worker.json
• Never commit the API secret to version control
• Rotate the secret if compromised: wrangler secret put API_SECRET

Troubleshooting

Emails Not Received

• Check Email Routing is enabled in Cloudflare
• Verify worker route is configured correctly
• Check worker logs: npx wrangler tail offload-email

API Returns 401

• Verify Authorization header: Authorization: Bearer YOUR_TOKEN
• Check token in ~/.config/offload/email-worker.json

DNS Not Resolving

• Wait for DNS propagation (can take up to 24h, usually <5 min)
• Verify record is created and proxied in Cloudflare DNS

License

ISC