📧 Email Client for Cloudflare Workers

A complete email client built with Cloudflare Workers, D1 database, and R2 storage, protected by Cloudflare Access SSO.

Features

• 📧 Receive Emails - Automatically receive emails via Cloudflare Email Routing
• ✉️ Send Emails - Send emails from your domain addresses
• 📎 Attachments - Full attachment support with R2 storage
• 🖥️ Web UI - Clean, modern email client interface
• 🔌 REST API - Full API for integration
• 🔒 SSO Protection - Secured with Cloudflare Access (same login as Cloudflare dashboard)

Quick Start

1. Install Dependencies

cd email-client
npm install

2. Login to Cloudflare

npx wrangler login

3. Configure Email Sender

Edit wrangler.toml - no changes needed for send_email unless you want to restrict destinations.

4. Deploy

npm run deploy

5. Enable Cloudflare Access (SSO Protection)

This is the key step to protect your email client with Cloudflare login:

1. Go to Cloudflare Dashboard → Workers & Pages
2. Click on your email-client worker
3. Go to Settings → Domains & Routes
4. Find your workers.dev URL and click "Enable Cloudflare Access"
5. In the modal that appears, note:
   • Team Domain: https://YOUR-TEAM.cloudflareaccess.com
   • Application AUD: A long string like abc123...
6. Configure who can access (by default, only you)

6. Configure JWT Validation

Add the values from step 5 to your wrangler.toml:

[vars]
TEAM_DOMAIN = "https://YOUR-TEAM.cloudflareaccess.com"
AUD = "your-application-aud-string-here"

Or set them via Dashboard: Workers & Pages → email-client → Settings → Variables

7. Redeploy

npm run deploy

8. Create Email Route

1. Go to Email → Email Routing → Email Workers
2. Find email-client worker
3. Click "Create route"
4. Enter your email address (e.g., hello@yourdomain.com)
5. Save

9. Access Your Email Client

Visit: https://email-client.YOUR-SUBDOMAIN.workers.dev/ui

You'll be prompted to log in with Cloudflare Access (same account as your Cloudflare dashboard).

How Authentication Works

1. When you visit the email client, Cloudflare Access intercepts the request
2. If not logged in, you're redirected to Cloudflare's login page
3. After authentication, Cloudflare adds a signed JWT token to requests
4. The Worker validates this JWT to ensure you're authenticated
5. Only authenticated users can view or send emails

API Endpoints

All endpoints require Cloudflare Access authentication.

Method	Path	Description
GET	/	List all emails
GET	/ui	Web interface
GET	/email/:id	Get specific email
POST	/email/:id/read	Mark as read
DELETE	/email/:id	Delete email
GET	/attachment/:id	Download attachment
POST	/send	Send email

Troubleshooting

"Authentication required" error?

• Make sure you enabled Cloudflare Access on your Worker
• Check that TEAM_DOMAIN and AUD are set correctly in wrangler.toml
• Redeploy after making changes

Can't access after enabling Access?

• Clear your browser cookies for the workers.dev domain
• Try in an incognito window
• Check Access policies in Zero Trust dashboard

Emails not received?

• Enable Email Routing in Cloudflare dashboard
• Create an email route pointing to your worker
• Check worker logs: npm run tail

Security Notes

• Authentication is handled by Cloudflare Access at the edge
• JWT tokens are validated using Cloudflare's public keys
• Only users authorized in your Access policy can access the email client
• Email receiving (the email handler) is not authenticated (emails come from Cloudflare's email routing)