Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paubox.com/llms.txt

Use this file to discover all available pages before exploring further.

The Paubox Email API uses standard HTTP status codes. All error responses include a JSON body with a message field describing the problem.

​
Status codes

CodeMeaningCommon cause
200OKRequest succeeded
400Bad RequestInvalid request body — see checklist below
401UnauthorizedMissing or invalid API key
403ForbiddenAPI key valid but lacks permission for this action
404Not FoundResource (e.g. tracking ID) does not exist
422Unprocessable EntityRequest is well-formed but semantically invalid (e.g. unverified from domain)
429Too Many RequestsRate limit exceeded — see Limits
500Internal Server ErrorUnexpected server-side error
502Bad GatewayUpstream connectivity issue — retry with backoff
503Service UnavailableTemporary outage — check status.paubox.com
504Gateway TimeoutRequest timed out — retry with backoff

​
400 Bad Request — debugging checklist

A 400 usually means the request body is missing a required field or contains an invalid value. Work through this list:
The most common causes of 400 Bad Request:
  • from domain not verified — the sender address must belong to a domain you have verified in Email API > Settings. Sending from @gmail.com or any unverified domain always returns a 400.
  • Missing subject — data.message.headers.subject is required.
  • Empty recipients array — data.message.recipients must contain at least one valid email address.
  • Invalid base64 in attachment — the content field of every attachment must be valid base64-encoded data.
  • No message body — at least one of text/plain or text/html must be present in data.message.content.

​
401 Unauthorized

The API key is missing, malformed, or does not match the username in the URL. 
# Check: does the base URL username match the account that owns the key?
https://api.paubox.net/v1/YOUR_USERNAME/messages
#                          ^^^^^^^^^^^^
# This must be YOUR endpoint username, not your email address.

​
429 Too Many Requests

You have exceeded the rate limit for your plan. Back off and retry. See Limits for rate limit details. For high-volume sending, use the bulk messages endpoint (recommended max 50 per request) rather than looping over individual /messages calls.

​
Example error response

{
  "errors": "Sender domain not verified"
}