Skip to main content
The Mail API base is https://api.spitzli.cloud/api/mail/v1. The Mail API reference tab preserves the existing TypeScript OpenAPI contract for messages, batches, domains, keys, webhooks, suppressions, logs and analytics. The native Mail runtime and each enabled connection have separate acceptance gates.
The reference is a retained compatibility contract; generation alone does not establish native endpoint parity or production enablement. The public documentation does not send authenticated requests from an embedded playground.

​
Authorization

Send Authorization: Bearer YOUR_KEY. Use a Spitzli Cloud Mail key, not a provider key or Console cookie. Sending endpoints accept sending_access; reading or managing other resources requires full_access, within the key’s resource restrictions.

​
Request limits

Use base64 content for attachments; filesystem paths and remote attachment URLs are unsupported. Consult the generated schema for each operation’s fields and response shapes.

​
Idempotency and revisions

Use a stable Idempotency-Key when sending a message or batch. Completed responses replay for 24 hours. Unknown handoffs remain reserved until reconciliation. Do not change the key to bypass an uncertain result. Rescheduling and cancellation require the current message revision in If-Match. A missing revision returns 428; a stale revision returns 409. Read the current message before making another change.

​
Message and recipient state

Acceptance, delivery, bounce and complaint are different events. A batch can have partial outcomes; inspect the batch and individual messages before deciding what to retry. Simulation is marked separately from live sending and is excluded from default analytics unless requested. The currently verified Turbo transport may provide HTML without a separate text alternative when both are supplied. For inline attachments, follow the documented CID convention: a content_id local part is referenced in HTML with the sender domain appended.

​
Contract source

The reference snapshot is exported from the Mail OpenAPI builder (legacy/control-plane/src/modules/mail/product/openapi.ts). Download the OpenAPI JSON for client tooling. Refresh it whenever the source contract changes; see documentation maintenance. The export script deliberately reads that retained contract. Check the native Mail implementation (crates/mail) and the enabled connection before relying on endpoint availability.