Core concepts
The ownership, lifecycle, retry, and delivery rules that apply across the Sendix API.
API invariants
These transport rules apply to every public developer endpoint.
The public API is hosted at https://sendix.dev/api/v1. The version segment is already included; append resource paths such as /emails.
The major version is carried in the path (/v1). New optional response fields and new enum values may be added without changing that path, so clients should ignore unknown fields safely.
Send Content-Type: application/json whenever a request has a JSON body. Successful deletes can return 204 with no body; do not parse those as JSON.
Timestamps are RFC 3339 / ISO 8601 values in UTC. Resource IDs are opaque: store and compare them as strings rather than inferring order or type from their shape.
Ownership and access
A valid key is necessary, but it is not the only authorization boundary.
API resources are resolved inside the workspace that owns the key. An ID from another workspace behaves as unavailable and must never be treated as a globally readable identifier.
Each route checks a read, send, or manage scope. Create separate least-privilege keys for production services, CI jobs, analytics, and support tooling.
Keys can be limited to selected sending domains, an IP allowlist, and an expiry time. These restrictions are enforced in addition to scopes.
A send must use a domain owned by the workspace and healthy for the required DNS checks. A syntactically valid From address is not enough.
key:manage value does not let an API key mint or rotate other keys.Email lifecycle
The create response confirms that Sendix accepted the request; delivery continues asynchronously.
| State | Meaning |
|---|---|
| scheduled | The message is stored for a future RFC 3339 time and can still be changed or cancelled. |
| queued | The request passed validation and the delivery job is waiting for a worker. |
| sending | A worker is actively preparing or handing off the message. |
| accepted_by_remote_mx | The recipient mail server accepted the SMTP transaction. |
| sent / delivered | Delivery processing completed. Neither state guarantees inbox placement. |
| opened / clicked | An enabled tracking signal was observed; privacy controls can affect accuracy. |
| bounced / complained | A permanent delivery failure or complaint was received. |
| failed / suppressed / cancelled | Sendix stopped the message before successful delivery. |
Poll GET /emails/{id} when a synchronous job needs the latest state. For normal production processing, subscribe to webhooks and make the consumer idempotent because the same event can be delivered more than once.
Safe retries
Network timeouts do not tell you whether Sendix accepted a send. Idempotency closes that ambiguity.
Set Idempotency-Key to a stable business operation ID between 8 and 128 characters. The JSON idempotency_key field is also accepted.
A retry with the same key and body returns the original email ID with idempotent: true. Reusing that key with a different body returns a conflict instead of creating a second send.
Delivery signals
Verify the signature against the raw request body, reject stale timestamps, acknowledge quickly, and deduplicate using the event or delivery identifier stored by your consumer.
Remote-MX acceptance means the receiving server accepted responsibility for the message. The provider can still route it to spam, quarantine it, or apply later filtering.
Tracking is observational
Open and click events are useful signals, not perfect user-attention measurements. Image proxying, privacy protection, disabled images, security scanners, and link prefetching can create missing or automated activity. Use delivery, bounce, complaint, and unsubscribe outcomes for operational decisions; interpret engagement statistically.