Introduction
The Postflare API is a Resend-compatible REST API for sending emails, managing contacts, templates, broadcasts, and webhooks.
Base URL
The Postflare API is built on REST principles. The API has resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.
https://api.postflare.appAuthentication
The Postflare API uses API keys to authenticate requests. You can view and manage your API keys in the Postflare Dashboard.
Your API keys carry privileges, so be sure to keep them secure. Don't share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication is performed via the Authorization header with a Bearer token:
Authorization: Bearer re_xxxxxxxxxAll API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Errors
Postflare uses conventional HTTP response codes to indicate the success or failure of an API request.
In general:
2xxcodes indicate success4xxcodes indicate an error with the information provided (e.g., a required parameter was missing, invalid email address, etc.)5xxcodes indicate an error with Postflare's servers
| Status Code | Description |
|---|---|
| 200 | OK — Everything worked as expected. |
| 400 | Bad Request — The request was unacceptable, often due to missing a required parameter. |
| 401 | Unauthorized — No valid API key provided. |
| 403 | Forbidden — The API key doesn't have permissions to perform the request. |
| 404 | Not Found — The requested resource doesn't exist. |
| 409 | Conflict — The request conflicts with another request (e.g., duplicate idempotency key). |
| 422 | Unprocessable Entity — The request body contains invalid data. |
| 429 | Too Many Requests — Too many requests hit the API too quickly. |
| 500 | Internal Server Error — Something went wrong on Postflare's end. |
Error Response Format
{
"statusCode": 422,
"name": "validation_error",
"message": "Either 'html' or 'text' content is required."
}Rate Limits
The API is rate limited to ensure fair usage. If you exceed the rate limit, you'll receive a 429 response.
Idempotent Requests
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.
To perform an idempotent request, provide an Idempotency-Key header:
Idempotency-Key: unique-key-per-requestIdempotency keys expire after 24 hours and have a maximum length of 256 characters.