Dbrij Send Documentation

Dbrij Send is the email platform for developers: transactional sending, templates, audiences, broadcasts, automations, suppressions, receiving and webhooks, all from your own domain, all through one API. Every message keeps a timeline of what happened to it, and these docs alone are enough to implement email end to end.

Every endpoint is relative to that base. All requests and responses are JSON. Authenticate with an API key (see Authentication).

Every success response is wrapped in an envelope: { "success": true, "data": … }. Read your payload from data, never from the top level; the Response examples throughout show the envelope. Errors are wrapped the same way with success: false (see Plans, errors and limits).

Three steps from nothing to a delivered email.

1 · Verify your domain. In the Send dashboard, open Domains and add a domain you own. We issue the DKIM, SPF and MX records; publish them at your DNS host and verification completes on its own within minutes.

2 · Create an API key. On the API keys page, create a key with the emails:send scope. You choose the address it sends as when you create it, so the key IS the sender: from can be omitted on every call. Use a test key while building (nothing is relayed, nothing billed) and a live key in production.

3 · Send.

curl -X POST https://api.dbrij.com/api/emails \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "jane@example.com",
        "subject": "Hello from Dbrij Send",
        "text": "It works." }'

Then watch it move: GET /emails/:id/events shows the timeline (queued, sent, delivered, opened), and a webhook endpoint (see Webhooks) tells your app the same story as it happens.

Authenticate every request with an API key from the Send dashboard, sent as a Bearer token.

Authorization: Bearer dbrij_live_xxxxxxxxxxxxxxxxxxxxxxxx

A key created with the emails:send scope is bound to one sender address, chosen at creation from the addresses your account can send as. Every send through that key goes out as that address, and from can be omitted entirely, so a leaked key is one identity, never a whole domain.

No email ever goes out as a bare address. The display name is, in order: the one in your from string ("Acme Billing <billing@acme.com>"), the sender name on your key, or the domain said like a name: hello@ricuit.com arrives as Ricuit <hello@ricuit.com>, never as "hello".

Test keys. A key created in the test environment (dbrij_test_…) runs the whole pipeline (validation, suppression, tracking, events, webhooks) but delivery is simulated: nothing is relayed, nothing counts against your plan. The email comes back with "sandbox": true and status delivered.

Send delivers from your own domain: each one gets its own DKIM key on our delivery network, and DMARC aligns because the mail really is yours. Add and verify domains on the Send dashboard's Domains page; a domain can also be granted to you by the company that owns it (from company email settings), which authorizes your keys without giving you the domain.

Each domain carries three switches on the dashboard: open tracking (a pixel per email), click tracking (links route through Send and record clicks, 302 only to the stored URL), and receiving (mail to unassigned addresses lands in your workspace, see Receiving). Tracking is applied before the message is DKIM signed, so signatures always verify.

curl -X GET https://api.dbrij.com/api/email-domains \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "d1a2…", "domain": "acme.com", "status": "active", "organizationId": "o3b4…" } ]
}

The transactional rail: one call, one email, a timeline and a webhook trail. Suppressed recipients are dropped before anything sends: an email whose every recipient is suppressed never relays and is never billed.

curl -X POST https://api.dbrij.com/api/emails \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "Acme <no-reply@acme.com>",
  "to": ["jane@example.com"],
  "subject": "Welcome to Acme",
  "html": "<h1>Welcome!</h1><p>Glad to have you.</p>",
  "text": "Welcome! Glad to have you."
}'

{
  "from": "Acme <no-reply@acme.com>",
  "to": ["jane@example.com"],
  "subject": "Welcome to Acme",
  "html": "<h1>Welcome!</h1><p>Glad to have you.</p>",
  "text": "Welcome! Glad to have you."
}

{
  "success": true,
  "data": {
    "id": "e5d3…",
    "from": "Acme <no-reply@acme.com>",
    "to": ["jane@example.com"],
    "cc": [],
    "bcc": [],
    "replyTo": null,
    "subject": "Welcome to Acme",
    "status": "sent",
    "scheduledAt": null,
    "sentAt": "2026-07-01T09:00:00.000Z",
    "deliveredAt": null,
    "messageId": "<a1b2…@acme.com>",
    "lastError": null,
    "sandbox": false,
    "createdAt": "2026-07-01T09:00:00.000Z"
  }
}

curl -X POST https://api.dbrij.com/api/emails/batch \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
  { "to": "jane@example.com", "subject": "Hi Jane", "text": "…" },
  { "to": "sam@example.com", "subject": "Hi Sam", "text": "…" }
]'

[
  { "to": "jane@example.com", "subject": "Hi Jane", "text": "…" },
  { "to": "sam@example.com", "subject": "Hi Sam", "text": "…" }
]

{
  "success": true,
  "data": [
    { "id": "e5d3…", "status": "sent" },
    { "error": "Invalid to recipient: bob@" }
  ]
}

curl -X GET https://api.dbrij.com/api/emails \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "e5d3…", "to": ["jane@example.com"], "subject": "Welcome to Acme", "status": "delivered", … } ]
}

curl -X GET https://api.dbrij.com/api/emails/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "id": "e5d3…", "status": "delivered", "deliveredAt": "2026-07-01T09:00:04.000Z", … }
}

curl -X DELETE https://api.dbrij.com/api/emails/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "id": "e5d3…", "status": "cancelled", … }
}

curl -X GET https://api.dbrij.com/api/emails/:id/events \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "ev1…", "type": "delivered", "recipient": "jane@example.com", "createdAt": "…" },
    { "id": "ev2…", "type": "opened", "createdAt": "…" } ]
}

Idempotency

Pass an Idempotency-Key header (max 190 chars) on POST /emails. Retrying with the same key returns the original email instead of sending a duplicate. On POST /emails/batch one key (max 180 chars) covers the whole batch, per item under the hood: a retried batch skips what already landed and finishes what did not.

curl -X POST https://api.dbrij.com/api/emails \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user-42" \
  -d '{ "to": "jane@example.com",
        "subject": "Welcome to Acme", "text": "Hi Jane!" }'

Scheduling

Set scheduledAt to a future ISO-8601 time and the email is queued instead of sent (status scheduled). Cancel it any time before it fires with DELETE /emails/:id. Scheduling is not available in /emails/batch, and send access is checked again at fire time: access revoked between scheduling and sending fails the send.

Attachments

Up to 10 attachments per email, 10MB total (decoded).

A template is a versioned body with {{variable}} merge tags. One template serves all three rails: transactional sends (templateId + variables on POST /emails), broadcasts, and automation steps. Contact fields (firstName, lastName, email, custom fields) fill the tags automatically on broadcasts and automations.

curl -X POST https://api.dbrij.com/api/templates \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Welcome", "subject": "Hello {{firstName}}", "html": "<p>Hi {{firstName}}, welcome aboard.</p>" }
// or, from the library:
{ "name": "Weekly", "subject": "This week at Acme", "design": { "layout": "weekly", "palette": "ocean", "typography": "modern", "header": "band", "content": { "companyName": "Acme", "title": "…" } } }'

{ "name": "Welcome", "subject": "Hello {{firstName}}", "html": "<p>Hi {{firstName}}, welcome aboard.</p>" }
// or, from the library:
{ "name": "Weekly", "subject": "This week at Acme", "design": { "layout": "weekly", "palette": "ocean", "typography": "modern", "header": "band", "content": { "companyName": "Acme", "title": "…" } } }

{
  "success": true,
  "data": { "id": "t1a2…", "name": "Welcome", "subject": "Hello {{firstName}}", "variables": ["firstName"], "currentVersion": 1, … }
}

curl -X GET https://api.dbrij.com/api/templates \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "t1a2…", "name": "Welcome", "variables": ["firstName"], "currentVersion": 3, … } ]
}

curl -X GET https://api.dbrij.com/api/templates/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "id": "t1a2…", "name": "Welcome", "html": "<p>…</p>", "text": null, … }
}

curl -X PATCH https://api.dbrij.com/api/templates/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Hello {{firstName}} 👋" }'

{ "subject": "Hello {{firstName}} 👋" }

{
  "success": true,
  "data": { "id": "t1a2…", "currentVersion": 4, … }
}

curl -X DELETE https://api.dbrij.com/api/templates/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

An audience is a contact list. Broadcasts send to one; automations can trigger on someone joining one. A contact who unsubscribes is marked across every audience in the workspace and suppressed, so nothing sends to them again.

curl -X POST https://api.dbrij.com/api/audiences \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter" }'

{ "name": "Newsletter" }

{
  "success": true,
  "data": { "id": "a1b2…", "name": "Newsletter", "contactCount": 0, … }
}

curl -X GET https://api.dbrij.com/api/audiences \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "a1b2…", "name": "Newsletter", "contactCount": 1240, … } ]
}

curl -X GET https://api.dbrij.com/api/audiences/:id/contacts \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "c1a2…", "email": "jane@example.com", "firstName": "Jane", "unsubscribed": false, … } ]
}

curl -X POST https://api.dbrij.com/api/audiences/:id/contacts \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe", "fields": { "plan": "pro" } }'

{ "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe", "fields": { "plan": "pro" } }

{
  "success": true,
  "data": { "id": "c1a2…", "email": "jane@example.com", "firstName": "Jane", … }
}

curl -X PATCH https://api.dbrij.com/api/audiences/:id/contacts/:contactId \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "plan": "scale" } }'

{ "fields": { "plan": "scale" } }

{
  "success": true,
  "data": { "id": "c1a2…", "fields": { "plan": "scale" }, … }
}

curl -X POST https://api.dbrij.com/api/audiences/:id/contacts/import \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contacts": [ { "email": "jane@example.com", "firstName": "Jane" }, { "email": "sam@example.com" } ] }'

{ "contacts": [ { "email": "jane@example.com", "firstName": "Jane" }, { "email": "sam@example.com" } ] }

{
  "success": true,
  "data": { "created": 1, "updated": 1, "skipped": 0 }
}

curl -X DELETE https://api.dbrij.com/api/audiences/:id/contacts/:contactId \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

One message to a whole audience, through the same pipeline as transactional mail, so every recipient gets a real email row with tracking and a timeline. The body freezes when sending starts; batches go out at a steady pace; and sending halts itself when bounce or complaint rates spike, because a burning list costs the domain more than the campaign is worth. Every message carries a working one click unsubscribe.

curl -X POST https://api.dbrij.com/api/broadcasts \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "August update", "audienceId": "a1b2…", "fromEmail": "news@acme.com", "subject": "What is new", "html": "<p>Hi {{firstName}},…</p>" }'

{ "name": "August update", "audienceId": "a1b2…", "fromEmail": "news@acme.com", "subject": "What is new", "html": "<p>Hi {{firstName}},…</p>" }

{
  "success": true,
  "data": { "id": "b1c2…", "status": "draft", "totals": { "recipients": 0, … }, … }
}

curl -X POST https://api.dbrij.com/api/broadcasts/:id/send \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduledAt": "2026-08-20T09:00:00.000Z" }'

{ "scheduledAt": "2026-08-20T09:00:00.000Z" }

{
  "success": true,
  "data": { "id": "b1c2…", "status": "scheduled", "scheduledAt": "2026-08-20T09:00:00.000Z", … }
}

curl -X GET https://api.dbrij.com/api/broadcasts/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "id": "b1c2…", "status": "sent", "totals": { "recipients": 1200, "sent": 1188, "opened": 480, … }, … }
}

curl -X POST https://api.dbrij.com/api/broadcasts/:id/cancel \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "id": "b1c2…", "status": "canceled", … }
}

A trigger and a straight line of steps. Someone joins an audience (or opens, clicks or receives an email), the automation waits a day, then sends the next template. Each address is enrolled at most once per automation, ever (triggering again never re enrolls), and a suppressed address's run is cancelled before it sends.

curl -X POST https://api.dbrij.com/api/automations \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Welcome series", "trigger": { "type": "contact.added", "audienceId": "a1b2…" },
  "steps": [ { "type": "send", "templateId": "t1a2…", "fromEmail": "hello@acme.com" },
             { "type": "wait", "durationMs": 86400000 },
             { "type": "send", "templateId": "t9z8…", "fromEmail": "hello@acme.com" } ] }'

{ "name": "Welcome series", "trigger": { "type": "contact.added", "audienceId": "a1b2…" },
  "steps": [ { "type": "send", "templateId": "t1a2…", "fromEmail": "hello@acme.com" },
             { "type": "wait", "durationMs": 86400000 },
             { "type": "send", "templateId": "t9z8…", "fromEmail": "hello@acme.com" } ] }

{
  "success": true,
  "data": { "id": "au1…", "status": "draft", "enrolledCount": 0, … }
}

curl -X POST https://api.dbrij.com/api/automations/:id/enable \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

{ "enabled": true }

{
  "success": true,
  "data": { "id": "au1…", "status": "active", … }
}

curl -X GET https://api.dbrij.com/api/automations \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "au1…", "name": "Welcome series", "status": "active", "enrolledCount": 214, … } ]
}

The workspace's do not email list, checked before every send on every rail. Hard bounces, spam complaints and unsubscribes are added automatically; you can add and remove addresses yourself. Suppression wins before quota: a dropped recipient is never billed.

curl -X POST https://api.dbrij.com/api/suppressions \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["gone@example.com"], "note": "asked to be removed" }'

{ "emails": ["gone@example.com"], "note": "asked to be removed" }

{
  "success": true,
  "data": { "added": 1 }
}

curl -X GET https://api.dbrij.com/api/suppressions \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "email": "gone@example.com", "reason": "manual", "note": "asked to be removed", "createdAt": "…" } ]
}

curl -X DELETE https://api.dbrij.com/api/suppressions/:email \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

Turn receiving on for a domain (Domains page) and mail sent to any address on it that has no company mailbox lands in your workspace: stored, listed here, and echoed to your app as an email.received webhook. Company mailboxes always resolve first, so receiving can never shadow a real inbox.

curl -X GET https://api.dbrij.com/api/inbound \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "in1…", "fromAddress": "customer@example.com", "to": ["anything@acme.com"], "subject": "Hi", … } ]
}

curl -X GET https://api.dbrij.com/api/inbound/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "id": "in1…", "fromAddress": "customer@example.com", "html": "<p>…</p>", "attachments": [ { "filename": "invoice.pdf", … } ], … }
}

The numbers behind the dashboard Metrics page: totals and rates over a window, plus a per day series for charts.

curl -X GET https://api.dbrij.com/api/stats \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "from": "2026-07-15", "to": "2026-08-14", "totals": { "sent": 12480, "delivered": 12333, … }, "deliveryRate": 0.988, "openRate": 0.41, …, "series": [ … ] }
}

Send POSTs a signed JSON envelope to your endpoints for each event. Register as many endpoints as your plan allows, each with its own secret and event filter. Deliveries are retried three times, logged, and replayable; an endpoint failing 20 deliveries in a row is paused (and the owner emailed) rather than silently dropped forever.

{
  "id": "evt_…",
  "type": "email.delivered",
  "createdAt": "2026-07-01T09:00:04.000Z",
  "data": { … }
}

curl -X POST https://api.dbrij.com/api/webhooks \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.yourapp.com/webhooks/dbrij", "events": ["email.delivered", "email.bounced"] }'

{ "url": "https://api.yourapp.com/webhooks/dbrij", "events": ["email.delivered", "email.bounced"] }

{
  "success": true,
  "data": { "id": "w1a2…", "url": "https://…", "secret": "whsec_…", "events": ["email.delivered", "email.bounced"], … }
}

curl -X GET https://api.dbrij.com/api/webhooks \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "w1a2…", "url": "https://…", "status": "enabled", "consecutiveFailures": 0, … } ]
}

curl -X GET https://api.dbrij.com/api/webhooks/deliveries \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": [ { "id": "d1…", "event": "email.delivered", "statusCode": 200, "ok": true, "attempts": 1, "durationMs": 84, … } ]
}

curl -X POST https://api.dbrij.com/api/webhooks/deliveries/:deliveryId/replay \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

{
  "success": true,
  "data": { "queued": true }
}

Events

{ "emailId": "e5d3…", "from": "Acme <no-reply@acme.com>", "to": ["jane@example.com"], "subject": "Welcome to Acme" }

{ "emailId": "e5d3…", "to": ["jane@example.com"], "subject": "…", "recipient": "jane@example.com" }

{ "emailId": "e5d3…", "to": ["jane@example.com"], "subject": "…", "reason": "550 mailbox unavailable", "recipient": "jane@example.com" }

{ "emailId": "e5d3…", "to": ["jane@example.com"], "subject": "…", "reason": "550 mailbox unavailable", "recipient": "jane@example.com" }

{ "emailId": "e5d3…", "to": ["jane@example.com"], "subject": "…" }

{ "emailId": "e5d3…", "to": ["jane@example.com"], "subject": "…" }

{ "emailId": "e5d3…", "to": ["jane@example.com"], "subject": "…", "url": "https://acme.com/x" }

{ "inboundId": "in1…", "from": "customer@example.com", "to": ["anything@acme.com"], "subject": "Hi" }

{ "contactId": "c1a2…", "audienceId": "a1b2…", "email": "jane@example.com", "unsubscribed": false }

{ "email": "jane@example.com" }

{ "broadcastId": "b1c2…", "name": "August update", "totals": { "recipients": 1200, "sent": 1188, … } }

{ "broadcastId": "b1c2…", "reason": "Stopped at 6% bounces…" }

Verify the signature

Each delivery carries X-Dbrij-Signature: sha256=…, an HMAC of the raw request body using the endpoint's whsec_ secret, and X-Dbrij-Signature-V2: t=…,sha256=…, an HMAC of `${t}.${body}` for replay protection. Verify one of them before trusting a payload.

import { createHmac } from 'crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return header === expected; // compare to X-Dbrij-Signature
}

function verifyV2(rawBody, header, secret, toleranceSec = 300) {
  const [tPart, sigPart] = header.split(',');            // "t=1690000000,sha256=…"
  const t = tPart.slice(2);
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = 'sha256=' + createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
  return sigPart === expected;
}

Send bills by monthly email volume, never per seat. Every account starts free; paid plans bill overage per extra thousand at renewal, from the closed month's usage. The free plan is a hard stop instead of a bill.

Rate limits

Every request counts toward your plan's per minute ceiling. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After in seconds. New paid workspaces also ramp daily volume for the first two weeks, because deliverability lost is months to win back.

Errors

{
  "success": false,
  "statusCode": 403,
  "message": "This key sends as billing@acme.com. Use that from address, or omit from entirely.",
  "error": "Forbidden",
  "path": "/api/v1/emails",
  "timestamp": "2026-08-14T22:56:17.969Z"
}