MCP & API Docs

Give AI agents (Claude Code, Claude Desktop, Cursor, Cline, Codex and any MCP client) their own disposable inbox: create an address, wait for a verification email, read the code, clean up.

1. Get an API key

Sign in and open Profile.
In API Key, create a key and copy it (starts with mk_). It is shown once.
Your role needs API key permission (Duke or above). Ask the site admin if the panel is missing.

2. Connect your MCP client

Requires Node.js 20+. Download the server (single file, includes the 2FA tool), then register it. Replace YOUR_API_KEY; MOEMAIL_API_URL points to this site.

Download

# macOS / Linux
mkdir -p ~/.mcp/moemail && curl -fsSL https://moemail-9mf.pages.dev/mcp/moemail-mcp.mjs -o ~/.mcp/moemail/moemail-mcp.mjs

# Windows (PowerShell)
mkdir -Force $HOME\.mcp\moemail; iwr https://moemail-9mf.pages.dev/mcp/moemail-mcp.mjs -OutFile $HOME\.mcp\moemail\moemail-mcp.mjs

Claude Code (CLI)

claude mcp add moemail --scope user \
  -e MOEMAIL_API_KEY=YOUR_API_KEY \
  -e MOEMAIL_API_URL=https://moemail-9mf.pages.dev \
  -- node $HOME/.mcp/moemail/moemail-mcp.mjs

Claude Desktop / Cursor / Cline / Windsurf (mcp.json)

{
  "mcpServers": {
    "moemail": {
      "command": "node",
      "args": ["/absolute/path/to/.mcp/moemail/moemail-mcp.mjs"],
      "env": {
        "MOEMAIL_API_KEY": "YOUR_API_KEY",
        "MOEMAIL_API_URL": "https://moemail-9mf.pages.dev"
      }
    }
  }
}

OpenAI Codex (~/.codex/config.toml)

[mcp_servers.moemail]
command = "node"
args = ["/absolute/path/to/.mcp/moemail/moemail-mcp.mjs"]
env = { MOEMAIL_API_KEY = "YOUR_API_KEY", MOEMAIL_API_URL = "https://moemail-9mf.pages.dev" }

Alternative: upstream npm package (email tools only, no get_2fa_code)

claude mcp add moemail --scope user \
  -e MOEMAIL_API_KEY=YOUR_API_KEY \
  -e MOEMAIL_API_URL=https://moemail-9mf.pages.dev \
  -- npx -y @moemail/mcp

Restart the client after adding the server. Re-run the download to update.

3. Tools

Tool	Arguments	Description
`create_email`	`name?, domain?, expiry? (1h \| 24h \| 3d \| permanent)`	Create a mailbox. Returns its id and address.
`list_emails`	`cursor?`	List mailboxes owned by the API key.
`list_messages`	`emailId, cursor?`	List messages in a mailbox, newest first.
`read_message`	`emailId, messageId`	Read the full text and HTML of a message.
`wait_for_email`	`emailId, timeoutSec? (max 90), intervalSec?`	Poll until a new message arrives. Returns status "timeout" so the agent can call it again.
`send_email`	`emailId, to, subject, content`	Send from a temporary address (needs send permission).
`delete_email`	`emailId`	Delete a mailbox and all its messages.
`delete_message`	`emailId, messageId`	Delete a single message.
`get_2fa_code`	`secret? (Base32 or otpauth://), qrImagePath? (PNG/JPEG)`	Get the current TOTP 2FA code, next code and seconds remaining. Computed locally.

Available domains: snapply.space, redgorilla.my.id, cuan.blog

4. Example prompts

"Create a temp email on snapply.space, sign up at example.com with it, then wait for the verification code."
"Make a 24h mailbox, wait for the magic link email and open the link."
"List my temp mailboxes and delete the ones with no messages."
"Get the 2FA code for secret JBSWY3DPEHPK3PXP." or "Read the 2FA QR at ~/Downloads/qr.png and give me the code."

REST API

Every request needs the X-API-Key header. expiryTime is in milliseconds: 3600000 (1h), 86400000 (24h), 259200000 (3d), 0 (permanent). Get available domains from GET /api/config.

Create mailbox

curl -X POST https://moemail-9mf.pages.dev/api/emails/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "signup", "expiryTime": 3600000, "domain": "snapply.space"}'

List messages

curl https://moemail-9mf.pages.dev/api/emails/{emailId} \
  -H "X-API-Key: YOUR_API_KEY"

Read message

curl https://moemail-9mf.pages.dev/api/emails/{emailId}/{messageId} \
  -H "X-API-Key: YOUR_API_KEY"

More endpoints (share links, pagination) are listed in Profile → API Key → docs.