# Smails

> Agent-native disposable email — Cloudflare Workers + Durable Objects, with CLI & MCP. https://smails.dev

- **Type:** MCP server
- **Install:** `agentstack add mcp-pexni-smails`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pexni](https://agentstack.voostack.com/s/pexni)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [pexni](https://github.com/pexni)
- **Source:** https://github.com/pexni/smails
- **Website:** https://smails.dev

## Install

```sh
agentstack add mcp-pexni-smails
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 --force  # 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

There are two independent release tracks — pushing to `main` ships the service, but **not** the CLI.

**Worker + frontend** — auto-deployed by [Cloudflare Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) on every push to `main` (the frontend builds to static assets the Worker serves). No manual step. To deploy by hand instead:

```bash
cd frontend && pnpm build         # → build/client
cd ../worker && pnpm run deploy   # wrangler deploy — serves assets + API + DOs
```

**CLI (`@smails/cli`) + MCP server** — *not* auto-deployed; publishing is a separate, manual release:

1. Bump the version in `cli/package.json` (npm rejects re-publishing an existing version).
2. Push to `main`.
3. `gh release create cli-vX.Y.Z --target main` — creating the GitHub Release triggers `.github/workflows/publish-cli.yml`, which publishes to npm and syncs the [MCP registry](https://registry.modelcontextprotocol.io) listing from `server.json`.

> `server.json`'s `description` must be ≤ 100 characters or the MCP registry publish step 422s.

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pexni](https://github.com/pexni)
- **Source:** [pexni/smails](https://github.com/pexni/smails)
- **License:** MIT
- **Homepage:** https://smails.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pexni-smails
- Seller: https://agentstack.voostack.com/s/pexni
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.