API reference

Base URL https://api.inboxar.com. JSON in, JSON out. All object ids are UUIDs. Invite-only beta: endpoints may still change; breaking changes will be announced to tenants.

Authentication

Two credentials work against /v1/*:

• API key — Authorization: Bearer ibx_…. Created by an operator at onboarding or by a tenant admin (API keys). Keys are shown once and stored hashed.
• Mailbox login (OAuth) — the access token a user gets from the mail server's OAuth flow (used by the web client). Accepted only for mailboxes flagged is_admin. Discovery: GET /auth/config (public).

curl https://api.inboxar.com/v1/me -H "Authorization: Bearer ibx_XXXXXXXX_…"

{ "tenant": { "id": "…", "slug": "acme", "name": "Acme", "status": "active",
             "daily_send_limit": 5000, "mailbox_daily_send_limit": 500 },
  "actor": { "kind": "api_key", "api_key_id": "…" },
  "mail_host": "mx1.inboxar.com" }

Domains

Records to publish (returned by POST/GET): MX 10 mx1.inboxar.com, two DKIM TXTs (Ed25519 + RSA, rotating selectors), TXT v=spf1 mx -all (add your other senders if any), _dmarc TXT v=DMARC1; p=none; rua=mailto:dmarc@inboxar.com, plus autoconfig/autodiscover CNAMEs for mail clients. Aggregate DMARC reports land in /v1/dmarc.

Mailboxes

Sending — POST /v1/messages

Sends from one of the tenant's mailboxes. The message is submitted through the mailbox itself (it shows up in its Sent folder), signed with your domain's DKIM, and queued. Delivery outcome arrives as message.delivered / message.bounced / message.deferred events.

curl https://api.inboxar.com/v1/messages \
  -H "Authorization: Bearer ibx_…" -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "hello@acme.com", "name": "Acme"},
    "to": ["ann@example.org", {"email": "bob@example.org", "name": "Bob"}],
    "cc": [], "bcc": [], "reply_to": ["support@acme.com"],
    "subject": "Your account is ready",
    "text": "Welcome aboard.",
    "html": "<p>Welcome aboard.</p>",
    "in_reply_to": "<prev-message-id@example.org>",
    "headers": {"X-Campaign": "welcome"}
  }'

202 { "id": "…", "status": "queued", "message_id": "<…@acme.com>", "from": "hello@acme.com", "to": ["ann@example.org","bob@example.org"], "created_at": "…" }

• from must be an active user mailbox of the tenant (groups cannot send). Up to 50 recipients across to/cc/bcc. text and/or html required. Only X-* custom headers.
• Limits: per tenant and per mailbox per rolling 24 h (see /v1/me). Over the limit → 429 daily_limit_reached.
• GET /v1/messages, GET /v1/messages/:id — the send log (no bodies).

Webhooks

Each delivery is a POST with headers X-Inboxar-Event, X-Inboxar-Delivery and X-Inboxar-Signature: sha256=<hex> — HMAC-SHA256 of the raw body with the webhook secret. Respond 2xx within 10 s. Retries: 1 m, 5 m, 30 m, 2 h, 12 h, 24 h; then the delivery is marked failed. Deliveries are at-least-once — dedupe on id.

// Node: verify the signature
import { createHmac, timingSafeEqual } from "node:crypto";
const expected = "sha256=" + createHmac("sha256", process.env.WEBHOOK_SECRET).update(rawBody).digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-inboxar-signature"] ?? ""));

Payload

{
  "id": "…",                        // event id (UUID)
  "type": "message.received",
  "created_at": "2026-09-17T10:00:00.000Z",
  "data": {
    "address": "support@acme.com",  // mailbox the event is about
    "domain": "acme.com",
    "occurred_at": "…",
    "spam": false,                  // message.received only
    "message": {                    // message.received only — the parsed email
      "id": "…", "blob_id": "…", "thread_id": "…",
      "message_id": ["<…>"], "in_reply_to": [], "references": [],
      "received_at": "…", "sent_at": "…",
      "from": [{"email":"ann@example.org","name":"Ann"}], "to": [...], "cc": [...], "reply_to": [...],
      "subject": "Order #1", "text": "…", "html": "…",
      "text_truncated": false, "html_truncated": false,   // bodies capped at 512 KB
      "has_attachment": true,
      "attachments": [{"name":"inv.pdf","type":"application/pdf","size":100,"blob_id":"…","cid":null}],
      "headers": [{"name":"List-Unsubscribe","value":"…"}]
    },
    "stalwart": { … }               // raw server event, for debugging
  }
}

Attachment contents are fetched through JMAP with the mailbox's own credentials (Mail protocols) using blob_id.

Events

GET /v1/events?type=…&limit=… lists recent events regardless of webhooks.

DMARC

Every domain's DMARC record points aggregate reports at us; we parse them for you.

API keys

Mail protocols

Web client: app.inboxar.com — sign in with the mailbox address and password.

Errors & limits

Errors are {"error": "code", "detail": "…"} with a matching HTTP status: 400 validation, 401 bad credentials, 403 not allowed (suspended tenant, foreign mailbox), 404, 409 conflict (name taken, already member), 413 body too large, 429 daily_limit_reached, 502 mail server refused, 503 not_configured. Every response carries X-Request-Id — include it when writing to hello@inboxar.com.