Errors and conventions
The Better Email API uses JSON requests and responses. Successful responses return the resource or collection described in the endpoint reference. Error responses use a shared envelope.
Error format
{
"error": {
"code": "validation_failed",
"message": "Recipient field is invalid.",
"details": {
"name": ["can't be blank"]
}
}
}
details is only included when the API has structured details to return. When handling errors programmatically, check error.code first.
Common status codes
| Status | Meaning |
|---|---|
400 Bad Request | The request body could not be parsed or recipient_field was not a JSON object. |
401 Unauthorized | A valid API key was not provided. |
403 Forbidden | The API key is valid, but the request is not allowed. |
404 Not Found | The requested resource does not exist in your organization. |
409 Conflict | The request conflicts with existing data or active dependencies. |
422 Unprocessable Entity | The request was parsed, but a required wrapper such as recipient_field was missing or one or more fields were invalid. |
503 Service Unavailable | Authentication is temporarily unavailable. |
JSON behavior
All public API endpoints under /api/v1 return JSON, even if another format is requested in the path.
For requests with a JSON body, send:
Content-Type: application/json
Accept: application/json
Browser requests
The public API is intended for server-side systems that you control. Do not call it directly from browser code or expose API keys in client-side applications.
Versioning
Current public endpoints use the /api/v1 prefix. Additive changes, such as new optional response fields or new endpoints, may be added to v1. Breaking changes, such as removing fields or changing required request shapes, should use a new API version.