API reference
A concise, manually-maintained reference for the endpoints most developers integrate against. New to Postiix? Start with the quickstart.
Authentication
Postiix's public endpoints don't all share one authentication scheme today — each is documented below exactly as implemented, not normalized into a single invented convention.
| Endpoint | Header |
|---|---|
POST /v1/transactional/send | ql-api-key: YOUR_API_KEY |
POST /v1/events | Authorization: Bearer YOUR_API_KEY |
Both accept either your project's live key or test key (see Test mode) — which one you send determines whether the request actually delivers.
Transactional send
Send a single transactional email using a template you've already created.
Headers
| Header | Required | Purpose |
|---|---|---|
ql-api-key | Yes | Your project's live or test API key |
Content-Type | Yes | application/json |
Idempotency-Key | No | See Idempotency |
Request body
{
"to": "person@example.com",
"template_id": "your-template-id",
"variables": {
"first_name": "Alex"
},
"subscriber_id": "optional-existing-contact-id"
}Response — 200
{
"success": true,
"id": "0100019..."
}Errors
| Status | Body | Cause |
|---|---|---|
| 401 | { "error": "Missing ql-api-key header" } | No API key sent |
| 401 | { "error": "Unauthorized: Invalid API Key" } | Key doesn't match a project |
| 400 | { "error": "Missing required fields: to, template_id, or variables" } | Required field missing |
| 404 | { "error": "Template not found or does not belong to this project" } | Bad template_id |
| 422 | { "error": { "code": "missing_variable", "message": "..." } } | Template needs a variable you didn't send |
| 429 | { "error": { "code": "rate_limited", "message": "..." } } | See Rate limits |
Note: auth and validation failures on this endpoint
return a plain { "error": "..." } string, while policy
failures (rate limiting, missing variables) return the structured
{ "error": { "code", "message" } } shape used elsewhere in
the API. Both are shown above exactly as returned — this is documented
product debt, not a documentation error. See Errors.
Test mode
Authenticate with your test key and the full pipeline runs — including
suppression checks and logging — but no message reaches a real inbox
and no provider quota is used.
Events
Send a product event and let Postiix resolve it to a transactional type
and template on your behalf, instead of specifying template_id
yourself.
Headers
| Header | Required | Purpose |
|---|---|---|
Authorization | Yes | Bearer YOUR_API_KEY |
Content-Type | Yes | application/json |
Request body
{
"source": "billing",
"event": "invoice.paid",
"event_id": "evt_8f14e45f",
"organisation_id": "org_...",
"project_id": "proj_...",
"payload": {
"customer_email": "person@example.com"
}
} event_id is your idempotency mechanism for this endpoint — see
Idempotency. There is no separate
Idempotency-Key header on this route.
What happens next
If an automation Workflow in your project is subscribed to this event
type, it enrolls into that Workflow. Otherwise, Postiix looks for a
transactional type matching your event string, scoped to
your project, and — if one exists — resolves its template and sends
immediately. There is no queue in this direct path. If no Workflow and
no matching transactional type exist, the event is still recorded, but
nothing is sent.
Response — 200
{
"success": true,
"status": "sent"
}Idempotency
POST /v1/transactional/send and POST /v1/campaigns/send accept an
optional Idempotency-Key header. POST /v1/events uses your
event_id the same way — supply a stable, unique ID and a retried
request with the identical body is safe to resend.
- Same key, same body: the original response is replayed verbatim, with its original status code.
- Same key, different body:
409with{ "error": { "code": "duplicate_request", "message": "..." } }. - Keys are only held for a limited retention window (currently on the order of a day) — don't rely on replaying a key indefinitely; use a fresh one for anything sent well after the original request.
Webhooks
Subscribe to delivery and engagement events from your project's dashboard — under Developer > Webhooks — by giving Postiix a URL and the event types you want. There is currently no public API to create a subscription; it's a dashboard action. A signing secret is generated when you create the subscription and shown to you once.
Event types
| Event | Fires when |
|---|---|
send.delivered | The provider confirms delivery |
send.bounced | The provider reports a bounce |
send.complained | A recipient marks the message as spam |
subscriber.unsubscribed | A recipient unsubscribes |
form.submitted | An embedded form receives a submission |
Verifying a delivery
Every delivery includes:
| Header | Contents |
|---|---|
X-Postiix-Signature-V1 | t=<timestamp>,v1=<hmac-sha256>, signed with your subscription's secret |
X-Postiix-Timestamp | Unix timestamp the request was signed at |
X-Postiix-Event | The event type, e.g. send.delivered |
X-Postiix-Delivery | A unique ID for this delivery attempt |
Compute an HMAC-SHA256 over the request body using your secret and
compare it to the v1= value, after checking the timestamp is
recent. A legacy X-Postiix-Signature header (unversioned) is also
sent for backward compatibility — prefer the versioned header for new
integrations.
Retries
A delivery that times out, doesn't connect, or returns a retryable status
(408, 409, 425, 429, or 5xx) is retried automatically a
small number of times with increasing backoff between attempts. After
that, it's marked dead-lettered and won't be retried further — the
exact attempt count and backoff schedule are an operational detail we
may tune, not a fixed contract to build hard dependencies on.
Rate limits
Requests are rate limited per project on a rolling window.
POST /v1/transactional/send is allowed a materially higher rate than
POST /v1/campaigns/send or POST /v1/forms/submit; POST /v1/events
is not currently rate-limited. Exact thresholds are operational
configuration we tune over time rather than a fixed public number — a
request over the limit receives 429 with
{ "error": { "code": "rate_limited", ... } }, and you should back off and retry.
Errors
Most endpoints return { "error": { "code": "...", "message": "..." } }. Two
older endpoints — /v1/transactional/send and /v1/campaigns/send —
return a plain { "error": "..." } string specifically for
authentication and request-validation failures, while returning the
structured shape for everything else (rate limits, suppressed
recipients, missing template variables). Handle both shapes on those
two endpoints; every other endpoint is consistently structured.