smails

MCP server

Let your agent create inboxes and wait for verification emails. Add the remote server to Claude Code or Codex and sign in with GitHub once.

Fastest: ask your agent

Paste this into Claude Code or Codex. The agent reads the setup instructions, adds the server and tells you when to sign in.

prompt
Set up smails for me by following https://smails.dev/setup.md

Claude Code

terminal
claude mcp add --transport http --scope user smails https://smails.dev/mcp

Then run /mcp inside Claude Code, pick smails and sign in with GitHub in the browser window that opens.

Codex

terminal
codex mcp add smails --url https://smails.dev/mcp
codex mcp login smails

codex mcp login opens a browser window to sign in with GitHub. On a machine without a browser, add --no-browser and paste the redirect URL back into the terminal.

Local server (stdio)

If you prefer a local process, the CLI runs the same tools over stdio (it forwards to the remote server).

terminal
claude mcp add smails -- npx -y @smails/cli mcp      # Claude Code
codex mcp add smails -- npx -y @smails/cli mcp       # Codex

Sign in once: run npx @smails/cli login in a terminal, or let the agent call the login tool — it returns a link for you to open and confirm.

Tools

  • create_mailbox — Create a new address. Mailboxes live for 7 days.
  • wait_for_message — Block (up to 50 s) until mail arrives, then return it in full. Filters: from, subject.
  • list_messages — List what a mailbox has received: sender, subject, time, id.
  • read_message — Read one message as plain text (HTML is converted; links are kept).
  • list_mailboxes — Your mailboxes that have not expired.
  • delete_message — Delete one message.
  • whoami — The signed-in account and today's quota.

A typical run: create_mailbox → use the address on the website → wait_for_message with subject "code" → read the code from the returned text.

Limits

  • 20 new mailboxes per account per day (UTC).
  • Mailboxes expire after 7 days; after that their mail can no longer be read.
  • Receive-only. Messages over 5 MB are rejected; attachments are not returned.

Prefer the command line? See the CLI. Writing your own integration? See the HTTP API.