Errors

HTTP error codes returned by the Paubox Email API, with common causes and fixes.

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

Code	Meaning	Common cause
200	OK	Request succeeded
400	Bad Request	Invalid request body: see checklist below
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key valid but lacks permission for this action
404	Not Found	Resource (e.g. tracking ID) does not exist
422	Unprocessable Entity	Request is well-formed but semantically invalid (e.g. unverified from domain)
429	Too Many Requests	Rate limit exceeded; see Limits
500	Internal Server Error	Unexpected server-side error
502	Bad Gateway	Upstream connectivity issue; retry with backoff
503	Service Unavailable	Temporary outage; check status.paubox.com
504	Gateway Timeout	Request 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 or malformed.

# Check: is the Authorization header present and using a valid key?
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.paubox.com/v1/email/messages

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"
}