🚀 Cloudflare Edge Mailer (Zero-Dependency)

A blazing fast, modular, zero-dependency SMTP API built exclusively for Cloudflare Workers.

This project demonstrates how to send transactional emails natively from the edge by communicating directly with Google's SMTP servers (smtp.gmail.com) over raw TCP using the new cloudflare:sockets API.

✨ Features

• Zero Dependencies: Absolutely no nodemailer, worker-mailer, or heavy npm packages.
• Native Sockets: Uses Cloudflare's connect() to establish a raw TCP socket connection to Google.
• Secure STARTTLS: Dynamically upgrades the plaintext socket to an encrypted TLS connection mid-stream (socket.startTls()), fully complying with RFC 3207.
• Production-Ready Structure: Clean, modular, and maintainable TypeScript architecture.
• Edge Optimized: Instant execution time with practically zero cold-start bloat.

---

🛠️ Project Structure

mailservicing/
├── src/
│   ├── index.ts        # The Cloudflare Worker entry point (Routing, CORS, Input validation)
│   ├── mailer.ts       # Service to negotiate the SMTP handshake and format the MIME message
│   ├── smtp-client.ts  # The underlying Raw TCP/TLS socket reader/writer wrapper class
│   └── types.ts        # Typescript interfaces
├── .dev.vars           # (Ignored) Local secrets 
└── wrangler.toml       # Cloudflare Worker configuration

---

🚀 Getting Started

1. Generate a Google App Password

Since standard Gmail passwords cannot be used for direct SMTP authentication:

1. Go to your Google Account > Security.
2. Ensure 2-Step Verification is turned ON.
3. Search for App passwords and create one named "Cloudflare Worker".
4. Copy the 16-character password.

2. Set Up Your Environment

Clone the repository, navigate to the folder, and install the TypeScript definitions and Wrangler CLI.

npm install

Create a .dev.vars file in the root directory for your local secrets:

GMAIL_USER=[email protected]
GMAIL_APP_PASSWORD=your-16-character-password

3. Run Locally

Spin up the Wrangler development server:

npm run dev

Test your local endpoint using curl:

curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{"to":"[email protected]", "subject":"Testing my custom SMTP", "text":"Look mom, zero dependencies!"}'

---

🌍 Deployment

Deploying to Cloudflare's global edge network takes seconds.

1. Deploy the code:

npx wrangler deploy

2. Add your secrets to Cloudflare: You must upload your Google credentials to Cloudflare's secure vault so your production worker can access them.

npx wrangler secret put GMAIL_USER
npx wrangler secret put GMAIL_APP_PASSWORD

3. Test Production: Replace localhost:8787 with your newly deployed *.workers.dev URL and fire your request!

---

📖 How it Works Under the Hood

If you look inside src/mailer.ts, you'll see the exact sequence of commands we send over the TCP socket:

1. connect() to smtp.gmail.com:587 (Plaintext)
2. Send EHLO
3. Send STARTTLS
4. Upgrade socket to TLS via socket.startTls()
5. Send EHLO (Encrypted)
6. Send AUTH PLAIN (Base64 encoded)
7. Send MAIL FROM and RCPT TO
8. Send DATA followed by the raw email headers and body
9. Send QUIT

All natively on the edge!