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:

KeyStarts withWhat it does
Testdz_test_Accepts requests and never sends email. Mail is kept as caught mail.
Livedz_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

MethodPathWhat it does
POST/v1/emailsSend one email, or one email to several recipients
POST/v1/emails/batchSend up to 100 emails in one request
GET/v1/emailsList emails, filtered by status, recipient, subject or date
GET/v1/logsThe same list as GET /v1/emails
GET/v1/emails/{id}Read one email, its content and its events
POST/v1/templatesCreate a template
GET/v1/templatesList templates
GET/v1/templates/{id}Read one template
PUT/v1/templates/{id}Replace a template and save a new version
POST/v1/domainsAdd a sending domain and get its DNS records
GET/v1/domainsList domains and their status
GET/v1/domains/{id}Read one domain and its records
POST/v1/domains/{id}/verifyCheck the domain with the sending provider and in DNS now
DELETE/v1/domains/{id}Remove a domain
POST/v1/webhooksCreate a webhook endpoint
GET/v1/webhooksList webhook endpoints for the environment of the key
DELETE/v1/webhooks/{id}Delete a webhook endpoint
POST/v1/validateCheck 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.

FieldTypeRequiredNotes
fromstringYesName <you@example.com> or you@example.com. Live sending needs a verified domain, or a subdomain of one. Free mail addresses are refused.
tostring or array of stringsYesEach address gets its own copy of the email.
ccstring or arrayNoOnly when to has exactly one address.
bccstring or arrayNoOnly when to has exactly one address.
reply_tostring or arrayNoWhere replies go.
subjectstringYes, unless a template sets itOne line, up to 998 characters. A subject in the request replaces the template's subject.
htmlstringOne of html, text or templateUp to 500,000 characters.
textstringOne of html, text or templateUp to 200,000 characters. If you send only html, Darzus writes the text part from it.
templateobjectOne of html, text or template{ "id": "tpl_...", "variables": { ... } }. Cannot be combined with html or text. See Templates.
attachmentsarrayNoUp 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>.
headersobject of stringsNoUp 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.
tagsarray of { "name", "value" }NoUp to 10 tags. Names and values use letters, numbers, underscores and dashes, up to 64 characters.
categorytransactional or marketingNoDefaults 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 409 with the code idempotency_conflict.
  • A repeat that arrives while the first request is still running returns 409 with the code idempotency_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/templates returns { "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 raises version by 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.

  • status is pending, partial, verified or failed. partial means the signing records are in place and the MAIL FROM records are not checked yet.
  • can_send is true once the signing records are verified. Live sending from a domain needs can_send to be true.
  • Each record has status: unchecked, ok, missing or mismatch.

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/domains returns { "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 parameterNotes
statusOne of queued, sent, delivered, opened, clicked, bounced, complained, failed, suppressed or caught
toReturns emails sent to this address
qMatches words in the subject, the sender or a recipient
sinceAn ISO date, such as 2026-11-01
untilAn ISO date, such as 2026-11-30
limitFrom 1 to 100. The default is 25.
afterThe 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, bcc and reply_to
  • template_id, if the email was sent from a template
  • warnings, which lists what a live key would have refused, for test mail
  • error and bounce, when they apply
  • events, a list of { "type", "at", "detail" } in the order they happened. Types include send, delivery, bounce, complaint, open, click, delivery_delay, reject and rendering_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.sent
  • email.delivered
  • email.bounced
  • email.complained
  • email.opened
  • email.clicked
  • email.delivery_delayed
  • email.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 event id. 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."
  }
}
StatusCodeWhen it happens
401missing_api_keyNo Authorization header
401invalid_api_keyThe key is wrong, revoked or deleted
403account_pausedSending is paused on the account. Contact support.
403domain_not_verifiedThe From domain is not verified (live keys only)
403free_email_fromThe From address uses a free mail provider
404not_foundThe ID does not exist, or belongs to another environment
409conflictThe domain is already on your account or another account
409idempotency_conflictThe Idempotency-Key was used with a different request
409idempotency_in_progressThe first request with this key is still running
422validation_errorA field is missing or wrong. details.issues or details.missing says which.
429plan_limit_reachedYour plan limit is reached: emails on Free, domains, or webhook endpoints
429daily_limit_reachedA new live account has reached its daily sending limit
429test_limit_reachedA test key has caught its daily limit of 500 emails
500internal_errorSomething failed on our side. Quote the request ID.
502provider_errorThe 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

LimitValue
Recipients in one send (to, cc and bcc together)50
Emails in one batch100
Attachments in one email10, 20 MB in total
Custom headers20
Tags10
HTML body500,000 characters
Text body200,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.