Sending and delivery.

Sending

Fields: from, to, subject, html and/or text, plus optional cc, bcc, reply_to (each up to 50 addresses), headers, tags, attachments (base64 content), scheduled_at, template ({ "id", "variables" }) and topic_id (send under a topic: contacts who opted out of it are skipped, not sent and not charged). The from domain must be verified.

Idempotency

Add an Idempotency-Key header to make a send safe to retry. Repeating a request with the same key and body returns the first response instead of sending again. Reusing a key with a different body returns 409 invalid_idempotent_request.

Idempotency-Key: welcome-user-4812

Scheduling

Set scheduled_at to an ISO 8601 time up to 30 days ahead. Until it starts sending, reschedule with PATCH /api/v1/emails/:id or cancel with POST /api/v1/emails/:id/cancel.

Batches

POST /api/v1/emails/batch takes an array of up to 100 email objects and returns { "data": [{ "id" }, …] }.

Checking what happened

GET /api/v1/emails/:id returns the email with last_event: one of queued, scheduled, sent, delivered, delivery_delayed, bounced, complained, failed and others. GET /api/v1/emails/:id/events returns every recorded event with a plain statement of what it proves (for example, delivered means the recipient’s server accepted the message, not that it reached the inbox), and, when something went wrong, a diagnosis with retry_safe and a next_step. The diagnosis is built only from the evidence the receiving server and the delivery network returned; when they give no specific reason, it says so. Webhooks can push the same events to your endpoint.

Test mode. Send to delivered@mailtruss.test, bounced@mailtruss.test, complained@mailtruss.test or suppressed@mailtruss.test to see each outcome without sending real mail. These messages run through the real pipeline, so the events, the diagnosis and your signed webhooks all fire, but nothing is handed to a mail server, nothing counts toward your plan, and the from address does not need a verified domain. They cannot be mixed with real recipients in one message, and are limited to 500 per 24 hours. Test events never add addresses to your suppression list.

Webhooks are signed with the Standard Webhooks scheme (webhook-id, webhook-timestamp, webhook-signature, also sent as svix-*). Verify them with verifyWebhook(rawBody, headers, secret) from the mailtruss package (0.2.0 or later), or with the standardwebhooks or svix libraries. Always verify the raw body, before parsing it.