# agent-inbox
Give any AI agent a disposable email inbox in one tool call.
## Install
```bash
npx gsd-agent-inbox
```
The interactive installer auto-detects your AI coding agents (Claude Code, Codex CLI, Cursor, Gemini CLI, Windsurf), configures the MCP server, and installs the optional skill for each.
When launched by an MCP client (non-TTY), it starts the MCP server normally. When you run it from a terminal, you get the installer.
## What it does
An [MCP server](https://modelcontextprotocol.io) that creates real, temporary email addresses on demand. Your agent can sign up for services, receive confirmation emails, extract verification links, and clean up — without you lifting a finger.
No API keys. No accounts. No configuration. Works with any email-sending service — Supabase, Resend, SendGrid, Postmark, AWS SES, whatever.
## The problem
AI agents hit a wall when a service requires email verification. They can fill out a sign-up form, but they can't receive the confirmation email. So they stop and ask you to do it.
## The fix
```
Agent: create_inbox({ prefix: "signup", name: "test" })
→ signup-1712345678@somedomain.com (name: test)
Agent: [fills sign-up form with that email]
Agent: verify_email({ address: "test", subject_contains: "confirm" })
→ Email verified successfully!
Verification URL: https://myapp.supabase.co/auth/v1/verify?token=abc123
HTTP Status: 200
Agent: delete_inbox({ address: "test" })
→ Done.
```
## Manual setup
If you prefer to configure manually instead of using the installer:
### Claude Code
```bash
claude mcp add agent-inbox -- npx -y gsd-agent-inbox
```
Or add to `~/.claude/settings.json`:
```json
{
"mcpServers": {
"agent-inbox": {
"command": "npx",
"args": ["-y", "gsd-agent-inbox"]
}
}
}
```
### Codex CLI
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.agent-inbox]
command = "npx"
args = ["-y", "gsd-agent-inbox"]
env = { }
```
### Cursor
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"agent-inbox": {
"command": "npx",
"args": ["-y", "gsd-agent-inbox"]
}
}
}
```
### Gemini CLI
Add to `~/.gemini/settings.json`:
```json
{
"mcpServers": {
"agent-inbox": {
"command": "npx",
"args": ["-y", "gsd-agent-inbox"]
}
}
}
```
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"agent-inbox": {
"command": "npx",
"args": ["-y", "gsd-agent-inbox"]
}
}
}
```
### Any other MCP client
Any client that supports stdio transport:
```json
{
"command": "npx",
"args": ["-y", "gsd-agent-inbox"]
}
```
### Build from source
```bash
git clone https://github.com/gsd-build/agent-inbox.git
cd agent-inbox
npm install
npm run build
npm start
```
## Tools
| Tool | What it does |
|------|-------------|
| `create_inbox` | Spin up a temporary email address. Optional `prefix` for readability, optional `name` for easy reference. |
| `check_inbox` | Check for messages. Returns subjects, bodies, and auto-extracted verification links. |
| `wait_for_email` | Poll until a matching email arrives. Filters by sender and subject. Auto-retries with backoff. |
| `verify_email` | One-shot verification: polls for confirmation email, extracts the link, visits it via HTTP. Three steps in one tool call. |
| `list_inboxes` | Show all active inboxes with names and providers. |
| `delete_inbox` | Destroy an inbox and its backing account. |
### Named inboxes
Give inboxes a name for easy reference across multiple tool calls:
```
create_inbox({ prefix: "signup", name: "main" })
wait_for_email({ address: "main", subject_contains: "confirm" })
delete_inbox({ address: "main" })
```
## Skill
The installer can optionally add a skill file that teaches your AI agent *when* and *how* to use agent-inbox — so it reaches for the inbox tools automatically when it encounters auth flows, email verification, or sign-up testing.
To install the skill manually:
```bash
mkdir -p ~/.claude/skills/agent-inbox
curl -fsSL https://raw.githubusercontent.com/gsd-build/agent-inbox/main/skill/SKILL.md \
-o ~/.claude/skills/agent-inbox/SKILL.md
```
## How it works
Uses [mail.tm](https://mail.tm) as the primary provider with automatic fallback to [1secmail](https://www.1secmail.com) if mail.tm is down. No API keys or accounts required.
- **Fallback providers** — if mail.tm fails, 1secmail kicks in automatically
- **Cleanup on exit** — inboxes are deleted when the MCP server shuts down (SIGINT/SIGTERM)
- **Smart polling** — `wait_for_email` retries with backoff (3s → 5s → 10s → 15s)
- **Link extraction** — confirmation/verification URLs auto-detected via keyword matching
## Limitations
- Some services block disposable email domains. If sign-up is rejected, try a different service or provider.
- Inboxes don't survive server restarts (in-memory only).
- Text and HTML bodies only — no attachment support.
## License
MIT