https://github.com/pexni/smails
Agent-native disposable email — Cloudflare Workers + Durable Objects, with CLI & MCP. https://smails.dev
https://github.com/pexni/smails
ai-agents cli cloudflare-workers disposable-email durable-objects email-api mcp model-context-protocol temporary-email throwaway-email
Last synced: 1 day ago
JSON representation
Agent-native disposable email — Cloudflare Workers + Durable Objects, with CLI & MCP. https://smails.dev
- Host: GitHub
- URL: https://github.com/pexni/smails
- Owner: pexni
- License: mit
- Created: 2026-06-24T14:59:55.000Z (3 days ago)
- Default Branch: main
- Last Pushed: 2026-06-24T18:43:54.000Z (3 days ago)
- Last Synced: 2026-06-24T19:11:09.828Z (3 days ago)
- Topics: ai-agents, cli, cloudflare-workers, disposable-email, durable-objects, email-api, mcp, model-context-protocol, temporary-email, throwaway-email
- Language: TypeScript
- Homepage: https://smails.dev
- Size: 268 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# smails
[](https://www.npmjs.com/package/@smails/cli)
[](https://smails.dev)
[](./LICENSE)
**Disposable email for humans and AI agents.** An instant, anonymous throwaway inbox for sign-ups, one-time codes, and confirmations — with a REST API, a CLI, and an **MCP server**, so your AI agent can receive verification emails too. No signup, no password.
→ **[smails.dev](https://smails.dev)** · `npx @smails/cli create`
> Give your agent its own inbox: plug the MCP server into Claude, Cursor, or any MCP client and it can create a mailbox and read incoming mail (verification codes, magic links) on its own.
## Features
- **Instant inbox** — open the site and you have an address, zero clicks
- **Real-time** — new mail arrives over WebSocket, no polling
- **Built for agents** — REST API, CLI, and an MCP server share the same mailbox
- **Multi-domain** — pick from configurable receiving domains
- **Self-cleaning** — mailboxes auto-expire after 7 days of inactivity
- **Serverless** — Cloudflare Workers + Durable Objects (one DO per mailbox, SQLite storage)
## Quick start
### Web
Visit **[smails.dev](https://smails.dev)** — an inbox is created for you on first load.
### CLI
```bash
npx @smails/cli create # create a mailbox (token saved to ~/.smails)
npx @smails/cli inbox # list messages
npx @smails/cli read # read a message (id prefix is enough)
npx @smails/cli whoami # show the current address
npx @smails/cli create --new # replace with a fresh mailbox
```
### MCP (for AI agents)
Add the server to any MCP client (e.g. Claude Desktop, `~/.claude/mcp.json`):
```json
{
"mcpServers": {
"smails": { "command": "npx", "args": ["@smails/cli", "mcp"] }
}
}
```
Tools: `create_mailbox`, `list_messages`, `read_message`, `delete_message`, `get_address`.
### REST API
```bash
# create a mailbox
curl -X POST https://smails.dev/api/mailbox
# → { "address": "...", "token": "..." }
# list messages with the returned token
curl https://smails.dev/api/mailbox/messages \
-H "Authorization: Bearer "
```
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/mailbox` | Create a mailbox → `{ address, token }` |
| `GET` | `/api/mailbox/messages` | List messages |
| `GET` | `/api/mailbox/messages/:id` | Read a message (full parsed body) |
| `DELETE` | `/api/mailbox/messages/:id` | Delete a message |
| `WS` | `/api/mailbox/connect?token=` | Stream new-mail notifications |
Authenticate every request (except create) with `Authorization: Bearer `.
## How it works
```
Inbound mail ──▶ Cloudflare Email Routing (catch-all)
│
▼
Worker email() handler ──┐
▼
Web / CLI / MCP ──REST + WS──▶ Durable Object (one per mailbox)
├─ SQLite (messages)
├─ token auth
└─ 7-day alarm → cleanup
```
- Each mailbox is a single **Durable Object**, addressed by its name; messages live in the DO's SQLite.
- The token is `{address}.{secret}`; the Worker routes by address, the DO verifies the full token.
- A 7-day alarm wipes inactive mailboxes; any activity renews it.
## Project structure
```
frontend/ React Router SPA (prerendered) — Tailwind v4 + shadcn
worker/ Cloudflare Worker + Durable Objects — Hono routing, postal-mime parsing
cli/ npm package — CLI + MCP server (@smails/cli)
```
## Development
Each package is independent (pnpm). Install per package.
```bash
# frontend
cd frontend && pnpm install && pnpm dev
# worker (API + Durable Objects)
cd worker && pnpm install && pnpm dev
# cli / mcp
cd cli && pnpm install && pnpm build
SMAILS_API_URL=http://localhost:8787 node dist/index.js create
```
## Deployment
The frontend builds to static assets that the Worker serves, so it's a single deploy:
```bash
cd frontend && pnpm build # → build/client
cd ../worker && pnpm run deploy # wrangler deploy — serves assets + API + DOs
```
Receiving mail uses Cloudflare Email Routing (catch-all → the Worker's `email` handler). Configure receiving domains via the `DOMAINS` var and the route in `worker/wrangler.jsonc`.
## License
MIT