Mail.tm Skill

Agent-first integration for temporary email addresses. Supports two modes: A) Persistent mailbox mode (reuse one mailbox with periodic activity to reduce expiry risk) B) Throwaway mode (create once, receive a code, then abandon)

Skill version: 1.0.0
API base: https://api.mail.tm
SSE base: https://mercure.mail.tm/.well-known/mercure

Every request except POST /accounts and GET /domains requires a Bearer token. (docs.mail.tm)

Quick Start

Step 1 - Fetch available domains

curl https://api.mail.tm/domains

Returns hydra:member with available domains. (docs.mail.tm)

Step 2 - Create an account

curl -X POST https://api.mail.tm/accounts \
  -H "Content-Type: application/json" \
  -d '{"address":"user@domain.com","password":"secret"}'

The address must use a domain from GET /domains. (docs.mail.tm)

Step 3 - Obtain a token

curl -X POST https://api.mail.tm/token \
  -H "Content-Type: application/json" \
  -d '{"address":"user@domain.com","password":"secret"}'

The response contains token. Use Authorization: Bearer TOKEN for all subsequent requests. (docs.mail.tm)

Step 4 - List messages

curl https://api.mail.tm/messages \
  -H "Authorization: Bearer TOKEN"

Mode A: Persistent Mailbox Mode

Goal: Maintain a stable mailbox address and reuse it for registrations and communication.

1. •Create the account and store address and password.
2. •Periodically call GET /messages or listen via SSE to keep activity on the account.
3. •Share the mailbox address with the owner so they can communicate with it.
4. •When a service requires email registration, reuse this address to receive codes and complete the flow.

Note: Mail.tm does not document an explicit renewal or keep-alive API. Periodic access is a best-effort strategy, not an official guarantee. (docs.mail.tm)

Mode B: Throwaway Mode

Goal: Create a mailbox once for a verification code and do not maintain it.

1. •Call GET /domains, generate a random local-part, and create the account.
2. •Use POST /token to obtain a token.
3. •Poll GET /messages or use SSE to retrieve the verification email.
4. •Stop using the account after the code is received; do not keep it active.

First Boot Protocol

1. •Fetch GET /domains to see available domains.
2. •Create one account and obtain a token to validate auth flow.
3. •Use GET /messages to confirm mailbox access.
4. •Switch to SSE when real-time updates are needed.
5. •Choose Mode A or Mode B per business context.

SSE (Real-time Messages)

Mail.tm uses Mercure SSE, not webhooks. (docs.mail.tm)

Base URL: https://mercure.mail.tm/.well-known/mercure
Topic: /accounts/{id}
Headers: Authorization: Bearer TOKEN

Each new message triggers an account event. (docs.mail.tm)

Error Handling

• •200/201/204 indicate success. (docs.mail.tm)
• •400: Missing or invalid payload. (docs.mail.tm)
• •401: Missing or invalid token. (docs.mail.tm)
• •404: Resource not found. (docs.mail.tm)
• •405: Method not allowed. (docs.mail.tm)
• •422: Validation failed. (docs.mail.tm)
• •429: Rate limit exceeded. (docs.mail.tm)

Rate Limit and Rules

• •Rate limit: 8 QPS per IP. (docs.mail.tm)
• •No illegal usage. (docs.mail.tm)
• •No resale or paid proxy services. (docs.mail.tm)
• •No API proxy or mirror. (docs.mail.tm)
• •If using the API, visibly credit and link back to mail.tm. (docs.mail.tm)

Minimal Endpoint Map

GET    https://api.mail.tm/domains
POST   https://api.mail.tm/accounts
POST   https://api.mail.tm/token
GET    https://api.mail.tm/messages
GET    https://api.mail.tm/messages/{id}
PATCH  https://api.mail.tm/messages/{id}
DELETE https://api.mail.tm/messages/{id}
GET    https://api.mail.tm/sources/{id}