Postflare

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.dev

Authentication

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 sk_xxxxxxxxx

You can also provide the key with the x-api-key header. Send exactly one of these headers; sending both returns 400 invalid_api_key.

All 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:

2xx codes indicate success
4xx codes indicate an error with the information provided (e.g., a required parameter was missing, invalid email address, etc.)
5xx codes 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 the resource's current state, for example deleting a segment a pending broadcast still uses, or reusing an idempotency key with a different body.
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": 400,
  "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

Idempotency-Key is supported on POST /emails and POST /emails/batch for safely retrying sends without accidentally performing the same operation twice. Other API endpoints ignore this header.

To perform an idempotent request, provide an Idempotency-Key header:

Idempotency-Key: unique-key-per-request

Idempotency keys expire after 24 hours and have a maximum length of 256 characters.

Introduction