Create temporary mailboxes and read incoming email over a simple REST API.
Pass your API key in the Authorization header as a Bearer token, or in the X-API-Key header. Get a free key from your account page.
curl https://maildrop.cx/api/v1/me \ -H "Authorization: Bearer md_your_api_key"
Create (claim) a mailbox. Optional JSON body: prefix (3-20 chars, a-z 0-9 _), suffix (one of the public domains). Returns the full address. Claimed mailboxes are readable only by your key.
List messages for a mailbox you created. Query params: page (default 1), limit (max 50). Returns total count and message summaries.
Fetch a single message: subject, sender, HTML content and attachment metadata.
Inspect your key: plan, usage today/this month, remaining quota, spending cap and pay-as-you-go balance.
# Create a mailbox
curl -X POST https://maildrop.cx/api/v1/mailboxes \
-H "Authorization: Bearer md_your_api_key" \
-H "Content-Type: application/json" \
-d '{"prefix": "myinbox42", "suffix": "206969.xyz"}'
# {"address":"[email protected]","prefix":"myinbox42","suffix":"206969.xyz"}
# Poll for messages
curl "https://maildrop.cx/api/v1/mailboxes/[email protected]/messages" \
-H "Authorization: Bearer md_your_api_key"
# Fetch one message
curl https://maildrop.cx/api/v1/messages/12345 \
-H "Authorization: Bearer md_your_api_key"
Errors are returned as JSON with an error object containing a machine-readable code and a human-readable message.
{"error": {"code": "daily_quota_exceeded", "message": "Daily quota of 300 requests reached."}}
| code | HTTP | |
|---|---|---|
missing_api_key | 401 | No key supplied in headers. |
invalid_api_key | 401 | Key not found. |
subscription_expired | 402 | Paid plan subscription inactive. |
insufficient_balance | 402 | Pay-as-you-go balance empty. |
key_disabled | 403 | Key was disabled in the dashboard. |
mailbox_not_found | 404 | Mailbox does not belong to this key. |
invalid_prefix | 422 | Prefix fails validation. |
invalid_suffix | 422 | Suffix not in the public domain list. |
address_taken | 409 | Address claimed by another key. |
mailbox_limit_reached | 429 | Plan mailbox limit hit for the last 24h. |
daily_quota_exceeded | 429 | Free plan daily quota reached. |
monthly_quota_exceeded | 429 | Monthly plan quota reached. |
spending_cap_reached | 429 | Your own monthly spending cap hit. |
Quota state is exposed via X-RateLimit-Limit and X-RateLimit-Remaining response headers. When a quota is exhausted the API responds with HTTP 429.