API reference
The Darzus API is a REST API over HTTPS. You send JSON and get JSON back.
Base URL: https://darzus.com/v1
Every path in this reference starts with /v1.
Authentication
Send your API key in the Authorization header:
Authorization: Bearer dz_test_replace_with_your_key
Create keys in the dashboard under API keys. A key is shown once, when you create it. Its name can be 1 to 64 characters.
There are two kinds of key:
| Key | Starts with | What it does |
|---|---|---|
| Test | dz_test_ | Accepts requests and never sends email. Mail is kept as caught mail. |
| Live | dz_live_ | Sends real email and counts toward your plan. |
A key is dz_test_ or dz_live_ followed by 40 letters and numbers.
Logs and webhook endpoints are separate for each environment, so a test key never reads live mail. Domains and templates belong to your account and work with either key.
Keep keys secret. Anyone with a live key can send mail from your verified domains. To replace a key, create a new one in the dashboard and revoke the old one.
A request without a key returns 401 with the code missing_api_key. A key that does not exist, is revoked or is deleted returns 401 with invalid_api_key.
Endpoints
| Method | Path | What it does |
|---|---|---|
POST | /v1/emails | Send one email, or one email to several recipients |
POST | /v1/emails/batch | Send up to 100 emails in one request |
GET | /v1/emails | List emails, filtered by status, recipient, subject or date |
GET | /v1/logs | The same list as GET /v1/emails |
GET | /v1/emails/{id} | Read one email, its content and its events |
POST | /v1/templates | Create a template |
GET | /v1/templates | List templates |
GET | /v1/templates/{id} | Read one template |
PUT | /v1/templates/{id} | Replace a template and save a new version |
POST | /v1/domains | Add a sending domain and get its DNS records |
GET | /v1/domains | List domains and their status |
GET | /v1/domains/{id} | Read one domain and its records |
POST | /v1/domains/{id}/verify | Check the domain with the sending provider and in DNS now |
DELETE | /v1/domains/{id} | Remove a domain |
POST | /v1/webhooks | Create a webhook endpoint |
GET | /v1/webhooks | List webhook endpoints for the environment of the key |
DELETE | /v1/webhooks/{id} | Delete a webhook endpoint |
POST | /v1/validate | Check an email address without sending to it |
Send an email
POST /v1/emails
curl https://darzus.com/v1/emails \
-H "Authorization: Bearer $DARZUS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-receipt" \
-d '{
"from": "Example Shop <hello@example.com>",
"to": "ada@example.com",
"subject": "Your receipt",
"html": "<p>Thanks for your order.</p>"
}'
The body is a JSON object. Any field not listed below returns 422.
| Field | Type | Required | Notes |
|---|---|---|---|
from | string | Yes | Name <you@example.com> or you@example.com. Live sending needs a verified domain, or a subdomain of one. Free mail addresses are refused. |
to | string or array of strings | Yes | Each address gets its own copy of the email. |
cc | string or array | No | Only when to has exactly one address. |
bcc | string or array | No | Only when to has exactly one address. |
reply_to | string or array | No | Where replies go. |
subject | string | Yes, unless a template sets it | One line, up to 998 characters. A subject in the request replaces the template's subject. |
html | string | One of html, text or template | Up to 500,000 characters. |
text | string | One of html, text or template | Up to 200,000 characters. If you send only html, Darzus writes the text part from it. |
template | object | One of html, text or template | { "id": "tpl_...", "variables": { ... } }. Cannot be combined with html or text. See Templates. |
attachments | array | No | Up to 10 files, 20 MB in total. Each item has filename, content (base64) and optionally content_type and content_id. Set content_id to show an image in the HTML with cid:<content_id>. |
headers | object of strings | No | Up to 20 custom headers. Names use letters, numbers and dashes. You cannot set headers Darzus sets itself, such as From, To, Subject or Message-ID. If you set List-Unsubscribe, also set List-Unsubscribe-Post. |
tags | array of { "name", "value" } | No | Up to 10 tags. Names and values use letters, numbers, underscores and dashes, up to 64 characters. |
category | transactional or marketing | No | Defaults to transactional. Marketing mail is not sent to people who unsubscribed. |
A request can have up to 50 recipients across to, cc and bcc. Each recipient counts toward your plan.
A send to one address returns 200 OK:
{
"id": "eml_01jd3k5m7p8h2x6q4r9t",
"status": "sent"
}
A send to several addresses returns 200 OK with an ids list and one entry for each recipient:
{
"ids": ["eml_01jd3k5m7p8h2x6q4r9t", "eml_01jd3k5m7p8h2x6q4r9u"],
"emails": [
{ "id": "eml_01jd3k5m7p8h2x6q4r9t", "to": "ada@example.com", "status": "sent" },
{ "id": "eml_01jd3k5m7p8h2x6q4r9u", "to": "grace@example.com", "status": "sent" }
]
}
The status is sent for a live key and caught for a test key. It is suppressed when the recipient unsubscribed or previously bounced or complained. A suppressed recipient is skipped and the request still returns 200.
A 200 means Darzus accepted the email and handed it to the sending provider. It does not mean the recipient has it. Follow the status in Logs, or receive the events with webhooks.
Batch send
POST /v1/emails/batch
The body is a JSON array. Each item has the same fields as a single send. A batch can have up to 100 emails.
curl https://darzus.com/v1/emails/batch \
-H "Authorization: Bearer $DARZUS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: receipts-batch-2026-11-12-01" \
-d '[
{ "from": "Example Shop <hello@example.com>", "to": "ada@example.com", "subject": "Receipt 1042", "text": "Thanks for order 1042." },
{ "from": "Example Shop <hello@example.com>", "to": "grace@example.com", "subject": "Receipt 1043", "text": "Thanks for order 1043." }
]'
A batch returns 200 OK:
{
"data": [
{ "id": "eml_01jd3k5m7p8h2x6q4r9t", "to": "ada@example.com", "status": "sent" },
{ "id": "eml_01jd3k5m7p8h2x6q4r9u", "to": "grace@example.com", "status": "sent" }
],
"errors": []
}
Darzus checks the shape of every email before it sends any. If one email has a field error, the whole batch returns 422 and nothing is sent. The message names the email by its position, for example Email 1: subject: a subject is required.
Some problems are found per email while sending, such as an unverified domain, a paused account or a plan limit. Those emails are left out of data. Each one appears in errors with its position in the array and the error:
{
"data": [{ "id": "eml_01jd3k5m7p8h2x6q4r9t", "to": "ada@example.com", "status": "sent" }],
"errors": [{ "index": 1, "error": { "code": "plan_limit_reached", "message": "The Free plan includes 5,000 emails a month. Upgrade to keep sending." } }]
}
Each email in a batch counts toward your plan on its own.
Idempotency keys
Send an Idempotency-Key header with POST /v1/emails and POST /v1/emails/batch. Use a value that is unique to the send, such as an order number with a step name, for example order-1042-receipt.
- The key can be 1 to 255 printable characters with no spaces.
- A repeat with the same key and the same body returns the first response and sends nothing new. That response has the header
idempotent-replayed: true. - A repeat with the same key and a different body returns
409with the codeidempotency_conflict. - A repeat that arrives while the first request is still running returns
409with the codeidempotency_in_progress. Wait a moment and send it again. - Keys are kept for 24 hours.
- A request that fails is not kept. You can fix it and send it again with the same key.
To retry after a timeout or a 5xx error, send the same request again with the same Idempotency-Key.
Templates
A template is a saved subject and body with variables. Send it with the template field of POST /v1/emails. Templates belong to your account, so both keys can use them.
POST /v1/templates takes name (1 to 100 characters), subject (required), html (required) and text (optional). No other fields are accepted.
curl https://darzus.com/v1/templates \
-H "Authorization: Bearer $DARZUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Receipt",
"subject": "Receipt for order {{order_id}}",
"html": "<p>Thanks for your order, {{first_name}}.</p>"
}'
It returns 201 Created:
{
"id": "tpl_01jd3k5m7p8h2x6q4r9t",
"name": "Receipt",
"subject": "Receipt for order {{order_id}}",
"html": "<p>Thanks for your order, {{first_name}}.</p>",
"text": null,
"variables": ["order_id", "first_name"],
"version": 1,
"created_at": "2026-11-12T14:03:22.410Z",
"updated_at": "2026-11-12T14:03:22.410Z"
}
GET /v1/templatesreturns{ "data": [ ... ] }.GET /v1/templates/{id}returns one template.PUT /v1/templates/{id}takes the same fields as the create call, and replaces the template. Each save raisesversionby one.
A variable is a name in double braces, such as {{first_name}}. Names start with a letter or underscore and can contain letters, numbers, underscores and dots. In html, {{name}} is escaped for HTML. {{{name}}} is inserted as it is, so use it only for HTML you trust.
To send the template:
curl https://darzus.com/v1/emails \
-H "Authorization: Bearer $DARZUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Example Shop <hello@example.com>",
"to": "ada@example.com",
"template": {
"id": "tpl_01jd3k5m7p8h2x6q4r9t",
"variables": { "order_id": "1042", "first_name": "Ada" }
}
}'
If a variable used by the template has no value, the request returns 422 with validation_error. The message names the variable, and nothing is sent. Values can be strings, numbers or booleans.
Domains
POST /v1/domains takes a name, such as example.com. Enter the domain only, without http:// or a path. It returns 201 Created with the DNS records to publish:
{
"id": "dom_01jd3k5m7p8h2x6q4r9t",
"name": "example.com",
"status": "pending",
"can_send": false,
"mail_from_domain": "send.example.com",
"created_at": "2026-11-12T14:05:10.018Z",
"last_checked_at": null,
"verified_at": null,
"records": [
{
"purpose": "dkim",
"required": true,
"type": "CNAME",
"name": "abc123._domainkey.example.com",
"value": "abc123.dkim.amazonses.com",
"status": "unchecked"
},
{
"purpose": "mail_from_mx",
"required": true,
"type": "MX",
"name": "send.example.com",
"value": "feedback-smtp.us-east-1.amazonses.com",
"priority": 10,
"status": "unchecked"
},
{
"purpose": "mail_from_spf",
"required": true,
"type": "TXT",
"name": "send.example.com",
"value": "v=spf1 include:amazonses.com ~all",
"status": "unchecked"
},
{
"purpose": "dmarc",
"required": false,
"type": "TXT",
"name": "_dmarc.example.com",
"value": "v=DMARC1; p=none;",
"status": "unchecked"
}
]
}
The example shows one DKIM record. A domain has three DKIM records, one for each token. The values in your response are the ones to publish. The domains guide explains each record.
statusispending,partial,verifiedorfailed.partialmeans the signing records are in place and the MAIL FROM records are not checked yet.can_sendistrueonce the signing records are verified. Live sending from a domain needscan_sendto betrue.- Each record has
status:unchecked,ok,missingormismatch.
After you add the records, call POST /v1/domains/{id}/verify. It returns the same shape with the current status of each record. You can also press Verify on the domain in the dashboard.
Other domain endpoints:
GET /v1/domainsreturns{ "data": [ ... ] }.GET /v1/domains/{id}returns one domain.DELETE /v1/domains/{id}returns{ "id": "dom_...", "deleted": true }.
Free mail addresses cannot be added as domains. A domain that is already on another account returns 409. Your plan sets how many domains you can add.
Logs
GET /v1/emails, or its alias GET /v1/logs, lists emails for the environment of your key, newest first.
| Query parameter | Notes |
|---|---|
status | One of queued, sent, delivered, opened, clicked, bounced, complained, failed, suppressed or caught |
to | Returns emails sent to this address |
q | Matches words in the subject, the sender or a recipient |
since | An ISO date, such as 2026-11-01 |
until | An ISO date, such as 2026-11-30 |
limit | From 1 to 100. The default is 25. |
after | The next value from the previous page |
{
"data": [
{
"id": "eml_01jd3k5m7p8h2x6q4r9t",
"from": "Example Shop <hello@example.com>",
"to": ["ada@example.com"],
"cc": [],
"subject": "Your receipt",
"status": "delivered",
"mode": "live",
"category": "transactional",
"created_at": "2026-11-12T14:10:02.551Z",
"last_event_at": "2026-11-12T14:10:05.203Z",
"opens": 0,
"clicks": 0
}
],
"next": null
}
When there are more results, next holds the ID to pass back as after. Otherwise it is null.
How far back logs go depends on your plan: 30 days on Free, 90 days on Starter and Pro, and 1 year on Scale.
GET /v1/emails/{id} returns one email with its content and events:
html,text,headers,tags,attachments,bccandreply_totemplate_id, if the email was sent from a templatewarnings, which lists what a live key would have refused, for test mailerrorandbounce, when they applyevents, a list of{ "type", "at", "detail" }in the order they happened. Types includesend,delivery,bounce,complaint,open,click,delivery_delay,rejectandrendering_failure.
An email that belongs to the other environment returns 404.
Webhooks
Webhooks send email events to a URL on your server as they happen.
POST /v1/webhooks takes a url and an optional list of events. If you leave out events, the endpoint gets all of them.
curl https://darzus.com/v1/webhooks \
-H "Authorization: Bearer $DARZUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://app.example.com/darzus/events",
"events": ["email.delivered", "email.bounced", "email.complained"]
}'
The response is 201 Created:
{
"id": "whk_01jd3k5m7p8h2x6q4r9t",
"url": "https://app.example.com/darzus/events",
"events": ["email.delivered", "email.bounced", "email.complained"],
"mode": "live",
"status": "enabled",
"created_at": "2026-11-12T14:12:40.007Z",
"signing_secret": "whsec_..."
}
The signing_secret is shown only in this response. Store it. GET /v1/webhooks returns the endpoints without it.
The event types are:
email.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.delivery_delayedemail.failed
The URL must start with https:// and must point to a public address. Darzus refuses addresses on private networks, and URLs with a username or password. Plans limit how many endpoints you can create for each environment: 2 on Free, 5 on Starter, 20 on Pro and 100 on Scale.
Each delivery is a POST with a JSON body:
{
"id": "evt_01jd3k5m7p8h2x6q4r9t",
"type": "email.delivered",
"created_at": "2026-11-12T14:10:05.203Z",
"data": {
"email_id": "eml_01jd3k5m7p8h2x6q4r9t",
"from": "Example Shop <hello@example.com>",
"to": ["ada@example.com"],
"subject": "Your receipt",
"occurred_at": "2026-11-12T14:10:05.203Z"
}
}
Each request has these headers:
darzus-event-id: the eventid. Use it to skip events you have already handled.darzus-signature:t=<unix seconds>,v1=<hex HMAC>. The HMAC is SHA-256 over the timestamp, a dot and the raw body, using the signing secret.
Check the signature with the raw body, before you parse the JSON. This Node function does the check:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyDarzusWebhook(rawBody, signatureHeader, signingSecret) {
const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
const expected = Buffer.from(
createHmac("sha256", signingSecret).update(`${parts.t}.${rawBody}`).digest("hex"),
);
const given = Buffer.from(parts.v1 ?? "");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
return fresh && given.length === expected.length && timingSafeEqual(given, expected);
}
Return a 2xx status once your server has accepted the event. Any other status, and any request that takes longer than 5 seconds, counts as a failure. Darzus then retries after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. After the sixth attempt the delivery is marked failed. Redirects are not followed.
DELETE /v1/webhooks/{id} removes an endpoint and returns { "id": "whk_...", "deleted": true }.
Validate an address
POST /v1/validate checks one address without sending to it:
curl https://darzus.com/v1/validate \
-H "Authorization: Bearer $DARZUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "ada@example.com"}'
{
"email": "ada@example.com",
"valid": true,
"reason": null,
"checks": {
"syntax": true,
"mail_server": true,
"disposable": false,
"role_account": false,
"free_provider": false
},
"suggestion": null
}
reason is null when the address looks deliverable. Otherwise it is invalid_syntax, no_mail_server or disposable_domain. suggestion holds a likely correction for a few common misspelled domains, such as gmial.com. role_account is true for addresses such as info@ or support@.
A valid result means the address looks deliverable. It does not prove who owns the address.
Errors
Every response has an x-request-id header. Quote it when you contact support.
Errors return a JSON body with a code and a message. Some errors also have details:
{
"error": {
"code": "domain_not_verified",
"message": "The domain example.com is not verified. Add it under Domains and publish its DNS records first."
}
}
| Status | Code | When it happens |
|---|---|---|
401 | missing_api_key | No Authorization header |
401 | invalid_api_key | The key is wrong, revoked or deleted |
403 | account_paused | Sending is paused on the account. Contact support. |
403 | domain_not_verified | The From domain is not verified (live keys only) |
403 | free_email_from | The From address uses a free mail provider |
404 | not_found | The ID does not exist, or belongs to another environment |
409 | conflict | The domain is already on your account or another account |
409 | idempotency_conflict | The Idempotency-Key was used with a different request |
409 | idempotency_in_progress | The first request with this key is still running |
422 | validation_error | A field is missing or wrong. details.issues or details.missing says which. |
429 | plan_limit_reached | Your plan limit is reached: emails on Free, domains, or webhook endpoints |
429 | daily_limit_reached | A new live account has reached its daily sending limit |
429 | test_limit_reached | A test key has caught its daily limit of 500 emails |
500 | internal_error | Something failed on our side. Quote the request ID. |
502 | provider_error | The sending provider could not send the email. The message says why. |
For 403, 404, 409 and 422, change the request or fix the setting, then send it again. For 429, wait until the limit resets or your plan changes. For 500 and 502, send the same request again with the same Idempotency-Key.
Limits
| Limit | Value |
|---|---|
Recipients in one send (to, cc and bcc together) | 50 |
| Emails in one batch | 100 |
| Attachments in one email | 10, 20 MB in total |
| Custom headers | 20 |
| Tags | 10 |
| HTML body | 500,000 characters |
| Text body | 200,000 characters |
New live accounts can send 100 emails a day until the limit lifts. Test keys can catch 500 emails a day. The daily limits reset at midnight UTC.
Test and live keys in code
Use a test key in development and a live key only in production. The responses have the same shape with either key, so your code does not change when you switch. Read Test mode for what test keys do with mail.