DOCS/QUICKSTART

Documentation

Provision a temp inbox, point your signup flow at it, pull the OTP — in three REST calls or one MCP tool call.

5 min read Last updated · 2026-05-12 v1.0.0

Quickstart

Sign in with GitHub to get your API key (prefixed msk_).
Create an inbox: POST /v1/inboxes
Use the returned address in your signup or verification flow.
Extract the code: GET /v1/inboxes/{id}/latest-code

Authentication

All API requests require a Bearer token:

http

Authorization: Bearer msk_your_api_key_here

Endpoints

METHOD	PATH	DESCRIPTION
POST	/v1/inboxes	Create inbox
GET	/v1/inboxes	List active inboxes
DELETE	/v1/inboxes/{id}	Delete inbox
GET	/v1/inboxes/{id}/messages	List messages
GET	/v1/inboxes/{id}/latest-code	Latest OTP code
GET	/v1/inboxes/{id}/latest-link	Latest verification link
GET	/v1/inboxes/{id}/wait-for-code	Block until OTP arrives
GET	/v1/messages/{id}	Full message content
GET	/v1/messages/{id}/raw	Raw .eml download
POST	/v1/keys	Create API key
DELETE	/v1/keys/{id}	Revoke API key

Create inbox

curl

curl -X POST https://api.mailsink.dev/v1/inboxes \
  -H "Authorization: Bearer $MAILSINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"local_part":"signup"}'

# Response (HTTP 201)
{
  "id":         "inb_rae1znj8eh4a",
  "address":    "[email protected]",
  "expires_at": "2026-05-13T10:00:00Z"
}

TIP

Provide local_part if you want a memorable prefix; otherwise MailSink generates one. Domain rotates across codenotify.net / letterhub.net / mailkite.net.

Extract verification code

curl

curl https://api.mailsink.dev/v1/inboxes/inb_rae1z/latest-code \
  -H "Authorization: Bearer $MAILSINK_API_KEY"

# Response
{
  "code":        "847291",
  "from":        "[email protected]",
  "subject":     "Your verification code",
  "received_at": "2026-05-12T14:01:23Z"
}

PROTIP

For CI runs, use GET /v1/inboxes/{id}/wait-for-code — it long-polls (up to 30s) until a code arrives. No retry loop, no flaky 200/null shuffle.

MCP server

For AI agents, drop the MCP server into Claude Desktop, Cursor, or Claude Code:

json · claude-desktop config

{
  "mcpServers": {
    "mailsink": {
      "command": "npx",
      "args":    ["-y", "@mailsink/mcp"],
      "env":     { "MAILSINK_API_KEY": "msk_..." }
    }
  }
}

Tools available: create_inbox, wait_for_email, get_verification_code, get_verification_link, list_messages, list_inboxes, delete_inbox, get_message.

Rate limits

PLAN	LIMIT	BURST
Free	60 req/min	—
Pro	600 req/min	30 burst
Team	3,000 req/min	200 burst

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining.