Skip to main content
The Paubox Email API uses standard HTTP status codes. Error responses include a JSON body describing the problem; see Error response format below.

Status codes

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 Settings > Domains. Sending from @gmail.com or any unverified domain always returns a 400.
  • Empty recipients array: data.message.recipients must contain at least one valid email address.
  • Missing attachment field: every attachment needs fileName, contentType, and content. Inline attachments also need contentId and an image/* contentType.
Always include data.message.content with text/plain, text/html, or both. A send request with no content object is not rejected with a 400; it returns a 500.

401 Unauthorized

The API key is missing or malformed.

403 Forbidden: new accounts

New accounts are under review for 24 hours after signup. During that window, send requests (/messages, /bulk_messages, and /templated_messages) return 403 with the title Account Under Review. Wait until 24 hours after signup and try again, or contact support@paubox.com.

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.

Error response format

Most errors return an errors array. Each entry has a code, title, and details.
A request body that is missing a required field or uses the wrong type (for example, no data.message.recipients) is rejected before processing with a single error object instead of an array: