Skip to main content
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 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"
}