Quick Start

This guide will walk you through using CloakMail for disposable email addresses.

Deployment Options

CloakMail ships with two independent deployment paths. Pick whichever fits your situation — they don't interact, and you can run both for different domains.

Option 1 — Cloudflare Workers (fastest, free tier)

Run CloakMail entirely on Cloudflare's free tier — no servers, no Docker, no SSH. One command from any directory:

bunx cloakmail-cli setup

The cloakmail-cli wizard provisions D1 + R2, deploys both Workers, configures Email Routing, binds your custom domain, and verifies the whole thing — in about two minutes. Free tier supports ~100k emails/day.

Prerequisites: a Cloudflare account, a domain already on Cloudflare DNS, and Bun installed locally.

See the full Cloudflare deployment guide for API token scopes, architecture details, and advanced flags.

Option 2 — Docker / VPS (full control)

Pull and run directly from GitHub Container Registry on any server with Docker:

curl -fsSL https://raw.githubusercontent.com/DreamsHive/cloakmail/main/docker-compose.yml -o docker-compose.yml
export DOMAIN=yourdomain.com
docker compose up -d

See the installation guide for prerequisites and the Docker deployment guide for production tuning.

Using the Web UI

1. Access the Web Interface

Open your browser and navigate to your CloakMail instance:

http://localhost:5173

2. Generate an Inbox

Click the "Generate Inbox" button. You'll instantly receive:

• A unique email address (e.g., random123@mail.example.com)
• An inbox that automatically expires based on your TTL settings

3. Receive Emails

Use the generated email address anywhere you need a temporary email. All incoming emails will appear in your inbox in real-time.

4. View and Manage Emails

• Click on any email to view its full content
• Delete individual emails or the entire inbox
• Copy the email address to clipboard

Using the API

You can also interact with CloakMail programmatically via the REST API.

Get Emails for an Inbox

After sending emails to your generated address, retrieve them:

curl http://localhost:3000/api/inbox/random123@mail.example.com

Response:

{
  "emails": [
    {
      "id": "abc123",
      "to": "random123@mail.example.com",
      "from": "sender@example.com",
      "subject": "Welcome!",
      "text": "Hello...",
      "html": "<p>Hello...</p>",
      "receivedAt": "2024-01-15T10:35:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasMore": false
  }
}

Get a Specific Email

curl http://localhost:3000/api/email/abc123

Delete an Inbox

curl -X DELETE http://localhost:3000/api/inbox/random123@mail.example.com

How It Works

1. Generate an address — Use the web UI or any address at your configured domain
2. Use the address — Sign up for services, receive verification codes, etc.
3. Check your inbox — Emails appear instantly via the web UI or API
4. Auto-cleanup — Emails are automatically deleted after the configured TTL

Common Use Cases

Next Steps

• API Reference — Full API documentation
• Configuration — Customize your instance
• TTL Settings — Configure email expiration