Send an email over a REST API with your SMTP mailbox

Updated on October 12, 2026

Sending is a POST /v1/messages authenticated with an API key. The only required field is mailbox_id: the mailbox that sends.

curl https://smapiz.com/v1/messages \
  -H "Authorization: Bearer smz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mbx_...",
    "to": "Ada <[email protected]>",
    "cc": ["[email protected]"],
    "subject": "Your order",
    "html": "<p>Your order has shipped.</p>",
    "text": "Your order has shipped."
  }'

The response contains the message with its id (msg_…) and status. SMTP delivery then happens in the background, with retries on temporary failures.

Useful fields

to, cc, bcc, reply_to: an address, "Name <address>", or a list.
html and/or text: the content, or a template_id (see templates).
from_name: overrides the mailbox’s sender name for this email.
headers: custom headers.
tags and metadata: your own values, echoed back in webhooks (handy to find an order or a customer).

Attachments

Content is base64-encoded. Add content_id to display an image in the HTML with cid:.

"attachments": [
  { "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." },
  { "filename": "logo.png", "content": "iVBORw0KGgo...", "content_id": "logo" }
],
"html": "<img src=\"cid:logo\"> <p>Your invoice is attached.</p>"

Avoid duplicates

Send an Idempotency-Key header (for instance the order ID). If the request is replayed with the same key, the email is not sent a second time.

-H "Idempotency-Key: order-1042"

Schedule a send

Add send_at in ISO 8601 format, up to 30 days ahead. To cancel before then: POST /v1/messages/{id}/cancel, or the Cancel scheduled send button in Messages.

"send_at": "2026-11-02T09:00:00+01:00"

Track the result

The Messages tab shows each email, its status and the SMTP server’s response. In code, subscribe a webhook to message.sent, message.failed and message.bounced (unknown address, full mailbox…).

You can also send by hand from Messages > Compose, which is handy to test a mailbox.