API Reference

Authentication

All requests must include a bearer token in the Authorization header. Tokens are workspace-scoped — a token can only see and act on its own workspace. There are no per-scope permissions; possession of the token grants full access to that workspace’s resources.

curl https://adbtd.com/api/v1/me \
  -H "Authorization: Bearer adbtd_live_4f8c…"

Errors

Conventional HTTP status codes; the body is always JSON with a stable code and a human message.

{
  "error": {
    "code": "conflict",
    "message": "no dedicated IP on this workspace yet — place your first order via the dashboard"
  }
}

Get current workspace

Returns the workspace the token belongs to, plus the API key’s own metadata. Useful as a token-validity ping.

{
  "data": {
    "workspace": {
      "id": "ws_4f8c",
      "slug": "acme-cold",
      "name": "Acme Cold Outreach",
      "currency": "USD"
    },
    "apiKey": {
      "id": "key_01HE…",
      "name": "production server"
    }
  }
}

List domains

All domains on the workspace, ordered by name. Each row carries the DNS-verification flags, the IP currently used for outbound mail on that domain (outboundIp), any staged IP switch waiting on SPF propagation (pendingOutboundIp), and a reputation sub-object with the latest Gmail Postmaster + 7-day Rspamd signals — handy for batch scoring loops against POST /v1/domains/assign-ip.

{
  "data": [
    {
      "id": "dom_a1b2",
      "name": "acme-hq.co",
      "mode": "byo",
      "status": "verified",
      "isPrimary": true,
      "spfOk": true, "dkimOk": true,
      "dmarcOk": true, "mxOk": true,
      "dkimSelector": "adbtd1",
      "outboundIp": { "id": "ip_d4e5", "address": "195.154.152.46", "label": "pristine" },
      "pendingOutboundIp": null,
      "reputation": {
        "gmail": "HIGH",  // HIGH | MEDIUM | LOW | BAD | UNKNOWN | null
        "userReportedSpamRate": 0.0008,  // 0–1. Gmail flags >0.003 as critical.
        "gmailLastFetchedAt": "2026-05-13T20:00:00Z",
        "sent7d": 4218,
        "avgSpamScore7d": 1.42  // rspamd score, lower is cleaner
      },
      "createdAt": "2025-09-12T08:14:00Z",
      "lastVerifiedAt": "2026-05-12T03:00:00Z"
    }
  ]
}

Add a domain

Attach a new domain to the workspace. The workspace must already have at least one dedicated IP (place the first order from the dashboard). The scheduler then provisions DNS records, DKIM keys, and MTA configuration; poll GET /v1/domains until status flips to active.

curl -X POST https://adbtd.com/api/v1/domains \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme-hq.co" }'

Bulk-assign outbound IPs

Bind one or more domains to specific outbound IPs in a single round-trip. Designed for agency-style customers who score their list periodically and re-route domains between their own “pristine / middle / trashy” IP tiers. Each row is processed independently — the response shape is { results: [{ domain, ok, ... }] }, so partial failures don’t abort the batch.

SPF gate. The target IP must already be in the domain’s published SPF record — otherwise the assignment would instantly break SPF on every receiver until DNS catches up. Update DNS in bulk first, then call this endpoint. Rows that fail the gate return code: "spf_missing_ip".

curl -X POST https://adbtd.com/api/v1/domains/assign-ip \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{
  "assignments": [
    { "domain": "acme.com",    "ipAddress": "1.2.3.4" },
    { "domain": "get-acme.io", "ipAddress": "5.6.7.8" }
  ]
}'

Per-row error codes: domain_not_found, ip_not_assigned, spf_missing_ip. Successful rows write the new outbound_ip_id immediately and any in-flight UI-staged switch on those domains is cleared. The tenant Postfix sender_transport map is re-rendered + reloaded once at the end of a batch with at least one success.

Delete a domain

Removes the domain and cascades to every mailbox under it. DKIM keys and mailbox-password rows are scrubbed from the tenant filesystem; the subscription is re-synced against the new mailbox count.

{
  "data": { "deletedMailboxes": 12 }
}

List dedicated IPs

All IPs currently assigned to the workspace, oldest first. Reputation flags surface the latest RBL / blocklist signals.

{
  "data": [
    {
      "id": "ip_d4e5",
      "address": "195.154.152.46",
      "label": "pristine, transactional",  // free-text, comma-separated multi-tags
      "status": "assigned",
      "allocatedAt": "2025-09-12T08:14:00Z",
      "lastReputationAt": "2026-05-12T03:00:00Z",
      "reputationFlags": []
    }
  ]
}

Allocate dedicated IPs

Adds count dedicated IPs to the workspace. The scheduler picks fresh /32s, RBL-sweeps them, and binds them to the workspace’s domains. Bills $19/mo per IP, prorated. The workspace must already have at least one domain.

curl -X POST https://adbtd.com/api/v1/ips \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{ "count": 2 }'

Update an IP (set labels)

Set or clear the customer-visible label on an assigned IP. Labels are free-text, comma- or space-separated multi-tags — an IP tagged "pristine, low-volume" matches either query at provision time via POST /v1/domains with ipLabel. The server normalises whitespace + dedupes; empty result (or explicit null) clears the label.

curl -X PATCH https://adbtd.com/api/v1/ips/ip_d4e5 \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{ "label": "pristine, transactional" }'

Errors: 404 not_found when the IP isn’t on this workspace (or has been released). 400 validation_error when the label exceeds 64 chars.

Release a dedicated IP

Releases the IP back to the pool. The IP enters a cooldown (rDNS neutralised) before it can be re-issued. You cannot release the workspace’s last IP while it still has active mailboxes — delete the mailboxes first, or 409 is returned.

{
  "data": {
    "released": "195.154.152.46",
    "cancelledSubscription": false
  }
}

List mailboxes

All mailboxes on the workspace with their SMTP / IMAP endpoints. Ordered by address. Passwords are never returned by listing or fetching — they are shown only once in the dashboard at provisioning time.

{
  "data": [
    {
      "id": "mb_8e2a",
      "email": "lena@acme-hq.co",
      "displayName": "Lena Park",
      "smtpHost": "195.154.152.46",
      "imapHost": "195.154.152.46",
      "submissionPort": 587,
      "imapPort": 993,
      "status": "active",
      "createdAt": "2025-09-12T08:14:00Z"
    }
  ]
}

Create mailboxes

Bulk-create mailboxes. Pass full email addresses; we group by domain and place a single order. Every referenced domain must already exist on the workspace — add domains via POST /v1/domains first. Provisioning is async; poll GET /v1/mailboxes for the new rows.

curl -X POST https://adbtd.com/api/v1/mailboxes \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["lena@acme-hq.co", "max@acme-hq.co"] }'

Get a mailbox

Returns the mailbox’s SMTP / IMAP host and ports. Use this when configuring an external mail client — pair it with the password shown once in the dashboard at creation.

{
  "data": {
    "id": "mb_8e2a",
    "email": "lena@acme-hq.co",
    "smtpHost": "195.154.152.46",
    "imapHost": "195.154.152.46",
    "submissionPort": 587,
    "imapPort": 993,
    "status": "active",
    "createdAt": "2025-09-12T08:14:00Z"
  }
}

Delete a mailbox

Deletes the mailbox and removes its Dovecot password row. The subscription is re-synced against the new mailbox count.

{
  "data": { "deleted": "lena@acme-hq.co" }
}

List messages in a mailbox

Reads the mailbox over IMAP and returns envelopes only. Sorted by UID descending (newest first). Use before for pagination — pass the previous page’s nextBefore.

{
  "data": {
    "folder": "INBOX",
    "total": 142,
    "messages": [
      {
        "uid": 14021,
        "messageId": "<CAJ…@bigco.io>",
        "subject": "Re: saw the launch",
        "from": ["Priya <priya@bigco.io>"],
        "to": ["lena@acme-hq.co"],
        "cc": [],
        "date": "2026-05-06T14:22:10Z",
        "flags": ["\\Seen"],
        "size": 4821,
        "seen": true
      }
    ],
    "nextBefore": 13996
  }
}

Get a single message

Fetches the full RFC-5322 message by UID, parses it, and returns the decoded text + HTML bodies and an attachment manifest (metadata only; raw bytes are not returned over the wire).

{
  "data": {
    "uid": 14021,
    "messageId": "<CAJ…@bigco.io>",
    "subject": "Re: saw the launch",
    "from": "Priya <priya@bigco.io>",
    "to": "lena@acme-hq.co",
    "cc": null,
    "date": "2026-05-06T14:22:10Z",
    "text": "Hey Lena, let's chat. Free Thurs?",
    "html": "<div>…</div>",
    "attachments": [{ "filename": "agenda.pdf", "contentType": "application/pdf", "size": 84211, "contentId": null }],
    "flags": ["\\Seen"],
    "seen": true
  }
}

Send a message

Sends through the mailbox’s own submission server (port 587, STARTTLS). Same code path as the dashboard test-send button — the message goes out on your dedicated IP, signed by your DKIM, from your domain. No central relay.

curl -X POST \
  https://adbtd.com/api/v1/mailboxes/mb_8e2a/send \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{ "to": "priya@bigco.io", "subject": "saw the launch", "text": "Hey Priya…" }'

Check a message with rspamd

Submits a message to the same rspamd scanner that scores real outbound traffic and returns the score, action, and per-symbol breakdown — without sending the mail. Useful for dry-running a draft before queueing a campaign or for catching a regression in your template before it lands in a recipient’s spam folder. Rate-limited to 30/min per token (burst 30); rspamd’s lua sandbox + RBL DNS lookups make each call non-trivial.

curl -X POST \
  https://adbtd.com/api/v1/check \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{ "from": "lena@acme-hq.co", "to": "priya@bigco.io", "subject": "saw the launch", "text": "Hey Priya…" }'

Webhook event payload

Every inbound message fires email.received at every webhook subscribed to one of the message’s recipient domains, filtered by mailbox scope (user / system / all). Set up webhooks from the dashboard’s API · Webhooks tab. Three transports are available: raw HTTPS (signed), Slack incoming-webhook (formatted message), Discord channel webhook (formatted embed).

// POST <your-url> — application/json
{
  "id": "evt_01HE…",
  "type": "email.received",
  "created": "2026-05-12T08:14:22.103Z",
  "workspace_id": "ws_…",
  "webhook_id": "wh_…",
  "data": {
    "message_id": "<CAJ…@mail.example.com>",
    "from": { "address": "alice@example.com", "name": "Alice" },
    "to": [{ "address": "bob@acme.com" }],
    "subject": "Re: invoice",
    "text": "Hey Bob — quick thought…",
    "html": "<div>…</div>",
    "attachments": [{ "filename": "invoice.pdf", "size": 84211 }],
    "triggered_by": "bob@acme.com"
  }
}

Signature (HTTPS transport)

The X-Adbtd-Signature header carries an HMAC-SHA256 over the request body, scoped by a timestamp to make replays inert. Same scheme as Stripe’s, same caveats: store the signing secret server-side, verify with constant-time comparison, reject events older than 5 minutes.

X-Adbtd-Signature: t=<unix-seconds>,v1=<hex>

<unix-seconds>.<raw-body>

import crypto from "node:crypto";

const sig = req.headers["x-adbtd-signature"];
const { t, v1 } =
  Object.fromEntries(
    sig.split(",").map(p => p.split("=")));

const expected = crypto
  .createHmac("sha256", process.env.SECRET)
  .update(`${t}.${rawBody}`)
  .digest("hex");

if (Math.abs(Date.now() / 1000 - Number(t)) >= 300)
  throw new Error("stale");
if (!crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(v1)))
  throw new Error("bad sig");

Retries, idempotency, retention