Build against Run2Mail

Developer API Documentation

Learn how to create API keys, authenticate requests, create inboxes, fetch messages, and handle common Run2Mail API responses.

API Keys Authentication Core Endpoints Error Codes

API keys

Generate developer API keys from your dashboard. Each key is shown in full only once, then stored as a secure hash for future verification.

Create keys from your logged-in dashboard.
Keep keys private and store them in your own secret manager.
Revoke old keys whenever a device, script, or teammate no longer needs access.

Authentication

Use a Bearer token in the Authorization header for every protected request.

Authorization: Bearer YOUR_API_KEY

If the key is invalid, revoked, or missing, the API responds with an authentication error.

Core endpoints

The most common workflow is: inspect the authenticated user, create an inbox, then fetch messages from that inbox.

Check the current account

curl -X GET "https://run2mail.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Create an inbox

curl -X POST "https://run2mail.com/api/v1/emails/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "random"
  }'

Fetch inbox messages

curl -X GET "https://run2mail.com/api/v1/emails/example@2mail.lol/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Sample JSON response

{
  "success": true,
  "data": {
    "email": "example@2mail.lol",
    "messages": []
  }
}

Rate limiting

Run2Mail applies plan-based request limits and daily inbox creation limits to protect the service and keep API access stable.

Per-minute rate limits depend on your active plan.
Email creation limits are tracked separately from basic read calls.
Usage is logged for visibility inside the admin analytics dashboard.

Error codes

401: Missing or invalid API credentials.
403: Access blocked, restricted, or not allowed for the request.
429: Request volume exceeded the current limit.
503: Developer API temporarily disabled by the platform.

Dashboard API screenshots coming soon

This area is reserved for future screenshots of the API key manager and usage dashboard.