Send an email
POST https://mail.zevuki.com/v1/emails sends one email to up to 50 recipients. It needs an API key with send or full access.
Request body
JSON, with Content-Type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
from | string | Yes | Sender, as hello@acme.dev or Acme <hello@acme.dev>. Must be on a verified domain in your account. |
to | string or string[] | Yes | One or more recipients. |
cc | string or string[] | No | Copy recipients. |
bcc | string or string[] | No | Hidden copy recipients. |
reply_to | string or string[] | No | Where replies should go, if not the from address. |
subject | string | Yes | Subject line. |
html | string | One of html or text | HTML body. |
text | string | One of html or text | Plain-text body. Send both for the best results in every mail app. |
headers | object | No | Extra headers, like {"X-Entity-Ref-ID": "4821"}. |
attachments | object[] | No | Files: filename, content (base64) and optional content_type. Add content_id to show an image inline as cid:… in the HTML. Up to 20 files, 10 MB together. |
tags | object[] | No | Up to 10 {"name", "value"} pairs, returned in webhooks so you can match events to your own records. |
scheduled_at | string | No | Send later: a time like 2026-11-20T09:30:00+05:30, up to 30 days ahead. |
To, CC and BCC together can have at most 50 addresses. Every address counts toward your monthly email limit.
Example
curl https://mail.zevuki.com/v1/emails \
-H "Authorization: Bearer $ZEVUKI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@acme.dev>",
"to": "maya@example.com",
"subject": "Welcome to Acme",
"html": "<p>Your workspace is ready.</p>",
"text": "Your workspace is ready.",
"cc": ["team@acme.dev"],
"reply_to": "support@acme.dev",
"headers": {"X-Entity-Ref-ID": "workspace-4821"}
}'const res = await fetch("https://mail.zevuki.com/v1/emails", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.ZEVUKI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: "Acme <hello@acme.dev>",
to: "maya@example.com",
subject: "Welcome to Acme",
html: "<p>Your workspace is ready.</p>",
}),
})
if (!res.ok) throw new Error((await res.json()).error.message)
const { id } = await res.json()import os, requests
res = requests.post(
"https://mail.zevuki.com/v1/emails",
headers={"Authorization": f"Bearer {os.environ['ZEVUKI_API_KEY']}"},
json={
"from": "Acme <hello@acme.dev>",
"to": "maya@example.com",
"subject": "Welcome to Acme",
"html": "<p>Your workspace is ready.</p>",
},
)
res.raise_for_status()
print(res.json()["id"])Response
201 Created means Zevuki accepted the email and queued it for delivery. It is not yet delivered: follow its status on the Emails page or with GET /v1/emails/{id}.
{
"id": "em_5Gk2…"
}On failure you get a JSON error with a stable code to check in your code and a message for people. See Errors.
{
"error": {
"code": "domain_not_verified",
"message": "The domain acme.dev is not verified yet. Add its DNS records and verify it."
}
}Attachments
{
"from": "Acme Billing <billing@acme.dev>",
"to": "maya@example.com",
"subject": "Your invoice",
"html": "<img src=\"cid:logo\"> <p>Invoice 4821 is attached.</p>",
"attachments": [
{ "filename": "invoice-4821.pdf", "content": "JVBERi0xLjQK..." },
{ "filename": "logo.png", "content": "iVBORw0KGgo...", "content_id": "logo" }
]
}Or give a path instead of content: an https:// URL that serves the file directly. Zevuki fetches it when the email is sent, names it from the URL unless you give a filename, and refuses private addresses and redirects. The 10 MB limit applies to the fetched files.
Open and click tracking
Turn tracking on per email with track. Opens add a 1×1 image to the HTML, and clicks send links through Zevuki, which then redirect to the original address. Opens are approximate: some mail apps load images without the person reading the email. Tracking is off unless you ask for it.
{
"from": "Acme <hello@acme.dev>",
"to": "maya@example.com",
"subject": "Your receipt",
"html": "<p>Thanks! <a href=\"https://acme.dev/receipt\">View it</a></p>",
"track": { "opens": true, "clicks": true }
}Each open and click is sent to your email.opened and email.clicked webhooks. Image and link addresses are signed, so they can't be made up or changed. Repeat opens of the same email within 10 minutes, and repeat clicks on the same link within a minute, count once.
Sending later
With scheduled_at, the email is checked now and sent at that time. Until then its status is scheduled and it doesn't count toward your monthly emails. Checks run again when it's sent: if the recipient was blocked or the domain removed meanwhile, its status becomes failed and an email.failed webhook is sent.
| Request | What it does |
|---|---|
PATCH /v1/emails/{id} | Move it: {"scheduled_at": "…"}. |
POST /v1/emails/{id}/cancel | Cancel it. Status becomes canceled. |
Sending in a batch
POST /v1/emails/batch takes a JSON array of up to 100 emails, each with the fields above except attachments and scheduled_at. Every email is checked first; if one is invalid, nothing is sent and the error names it, like emails[3]: …. The response lists an ID per email, in order. With an Idempotency-Key, each email in the batch is protected on its own.
{
"data": [
{ "id": "em_5Gk2..." },
{ "id": "em_9Hq7..." }
]
}Retrying safely
Send an Idempotency-Key header, for example your own order or notification ID, to make retries safe. If a request with the same key and the same body was already sent in the last 24 hours, you get the first email's ID back and nothing is sent again. The same key with a different body fails with invalid_idempotent_request. If the first request failed, the key is released, so a retry sends normally.
curl https://mail.zevuki.com/v1/emails \ -H "Authorization: Bearer $ZEVUKI_API_KEY" \ -H "Idempotency-Key: order-4821-confirmation" \ -H "Content-Type: application/json" \ -d @email.json
Before an email is sent
Zevuki checks, in this order: that the account isn't paused, that the from domain is yours and verified, the recipients, that no recipient is on your blocked list, and your monthly limit. A failed check sends nothing, to any recipient.
Copies in the mailbox
If the from address has a mailbox, the email is saved in that mailbox's Sent folder, so the people who answer replies can see what your app sent.
Unknown fields
A request with a field not listed above fails with invalid_json, so a typo never goes unnoticed.