Skip to content
Postiix

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.

POST /v1/transactional/send

Headers

HeaderRequiredPurpose
ql-api-keyYesYour project's live or test API key
Content-TypeYesapplication/json
Idempotency-KeyNoSee 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

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

POST /v1/events

Headers

HeaderRequiredPurpose
AuthorizationYesBearer YOUR_API_KEY
Content-TypeYesapplication/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: 409 with { "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

EventFires when
send.deliveredThe provider confirms delivery
send.bouncedThe provider reports a bounce
send.complainedA recipient marks the message as spam
subscriber.unsubscribedA recipient unsubscribes
form.submittedAn embedded form receives a submission

Verifying a delivery

Every delivery includes:

HeaderContents
X-Postiix-Signature-V1t=<timestamp>,v1=<hmac-sha256>, signed with your subscription's secret
X-Postiix-TimestampUnix timestamp the request was signed at
X-Postiix-EventThe event type, e.g. send.delivered
X-Postiix-DeliveryA 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.