Delivery Model
Truncus separates the transport layer from the control plane. Understanding this separation clarifies what "deterministic delivery" means in practice.
Architecture
Transport layer: AWS SES handles SMTP delivery to recipient mail servers.
Control plane (EU): Truncus orchestrates sends, stores delivery events, enforces idempotency, manages replay, and records the outcome of every email.
Your system interacts only with the control plane. The transport layer is an implementation detail.
Delivery flow
- Send request received by Truncus
- Request validated (API key, payload, domain authorization)
- Transport attempt via AWS SES
- Outcome (delivery, bounce or complaint) recorded from SES feedback
- Event stored in the EU (Frankfurt)
- Webhook dispatched to your endpoint
Two send paths
POST /api/v1/emails/send is asynchronous. It answers as soon as a provider accepts or refuses the message, not when the message is delivered. status is one of sent (accepted by a provider), queued (transient error, retry scheduled), scheduled (deferred via send_at), duplicate (idempotency replay), blocked (suppressed or domain type mismatch) or failed (permanent error). The delivery outcome arrives later as an event.
POST /api/v1/emails/send_sync waits up to 25 seconds for that event and returns the terminal state in the same request:
| Status | Meaning |
|---|---|
delivered | Accepted by recipient mail server |
bounced | Rejected by recipient mail server |
complained | Recipient marked the message as spam |
pending | No event within the window; the email was sent. Poll GET /api/v1/emails/{id} |
delivered means the message was accepted by the recipient's mail server. It does not guarantee inbox placement.
A bounce event carries the bounce type SES reports (bounce_type: Permanent, Transient or Undetermined) and its bounce_subtype. Permanent bounces and complaints add the address to your suppression list.
blocked happens before any send attempt, on both paths: the address is suppressed, or the sending domain cannot send this message. The response carries a machine-readable code, for example ALL_RECIPIENTS_SUPPRESSED.
What Truncus does not do
- No implicit retries after a bounce or a block
- No status coalescing — every send is independently tracked
- No optimistic success responses — if SES rejects, your system is told
Event storage
All delivery events are stored in the EU (Frankfurt) and queryable via the API or dashboard. Events are retained for 90 days on all plans.
Events are replayable on demand.
Synchronous vs. asynchronous state
The /emails/send response reports what happened to the request (sent, queued, …), not the delivery outcome. SES feedback is asynchronous and updates the stored email when it arrives. To wait for it in one call, use /emails/send_sync: it returns the terminal state, or pending when no event arrived within 25 seconds.
For production systems, consume delivery state via webhook rather than polling the send response.