zevuki mailbox

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.

FieldTypeRequiredDescription
fromstringYesSender, as hello@acme.dev or Acme <hello@acme.dev>. Must be on a verified domain in your account.
tostring or string[]YesOne or more recipients.
ccstring or string[]NoCopy recipients.
bccstring or string[]NoHidden copy recipients.
reply_tostring or string[]NoWhere replies should go, if not the from address.
subjectstringYesSubject line.
htmlstringOne of html or textHTML body.
textstringOne of html or textPlain-text body. Send both for the best results in every mail app.
headersobjectNoExtra headers, like {"X-Entity-Ref-ID": "4821"}.
attachmentsobject[]NoFiles: 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.
tagsobject[]NoUp to 10 {"name", "value"} pairs, returned in webhooks so you can match events to your own records.
scheduled_atstringNoSend 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"}
  }'

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}.

201 Created
{
  "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.

403 Forbidden
{
  "error": {
    "code": "domain_not_verified",
    "message": "The domain acme.dev is not verified yet. Add its DNS records and verify it."
  }
}

Attachments

Request body
{
  "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.

Request body
{
  "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.

RequestWhat it does
PATCH /v1/emails/{id}Move it: {"scheduled_at": "…"}.
POST /v1/emails/{id}/cancelCancel 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.

201 Created
{
  "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.

Request
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.