Getting started
Error handling
Use the HTTP status and stable error.code. Responses contain a request_id for support.
Response format
Successful JSON responses use a data envelope. Errors use error.code, error.message and request_id. Error messages may be localized; branch on code rather than message text. DELETE success returns 204 with no JSON body.
{
"error": {
"code": "MAILBOX_SESSION_REQUIRED",
"message": "A mailbox session is required"
},
"request_id": "example-request-id"
}Status codes
| Field / endpoint | Details |
|---|---|
| 200 / 201 / 204 | Read or update succeeded / mailbox created / deletion succeeded. |
| 400 / 413 | Invalid JSON, unknown fields, invalid UUID or pagination / body too large. |
| 401 | Missing, invalid, expired or revoked mailbox session. Recreate if credentials are lost. |
| 404 | Resource unavailable, deleted, or outside the current inbox. |
| 429 | Request, creation, or active-inbox limit reached. Stop and back off. |
| 500 / 503 | Temporary server or dependency failure. Retry safe reads with backoff. |
Limits and retry policy
Free endpoints share an 8-request-per-second limit per client IP (one-second fixed window). Request-rate 429 replies include Retry-After: 1. Poll every 5 seconds or slower; several workers behind one IP share this allowance. Mailbox creation is additionally limited to 5 attempts per minute, 10 per hour, 20 per day per IP, and 5 active inboxes per IP. The shared service also caps creation at 5,000 per minute globally. These limits include web usage and failed creation attempts. A creation-limit 429 may not include Retry-After: stop and wait for the applicable window, or delete an inbox you own if the active cap is reached. Never rotate IPs to bypass limits. Do not automatically retry POST /mailboxes after a timeout: creation is not idempotent. Check the response and saved cookies first. For safe reads, use exponential backoff with jitter. A 503 from request protection also includes Retry-After: 1.
When no message appears
An empty data.items array is a valid result, not a failed request. Verify the exact generated address and active timer, then check the sender delivery queue. Some senders block temporary domains or delay messages. A status of pending means processing is still underway; failed means the message could not be processed. Email verification codes come from the sender. InboxFlick cannot generate codes, receive SMS, change a code deadline, or guarantee that a third-party service accepts disposable addresses.