Email API

Overview

The API is REST over HTTPS, returns JSON, and is versioned in the path. Everything lives under https://brainito.com/api/v1.

Authentication

Every request carries a bearer token:

Authorization: Bearer brn_live_XXXXXXXX.YOUR_SECRET

Keys are scoped and belong to exactly one workspace. The workspace is taken from the key and never from the request body, so a key cannot reach another workspace's data no matter what it sends.

Quick start

Send your first message:

curl -X POST https://brainito.com/api/v1/emails \
  -H "Authorization: Bearer brn_live_XXXXXXXX.YOUR_SECRET" \
  -H "Idempotency-Key: order-confirmation-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Orders <orders@yourdomain.com>",
    "to": "customer@example.com",
    "subject": "Your order is on its way",
    "html": "<p>Tracking: ABC123</p>"
  }'

HTTP/1.1 202 Accepted
X-Request-Id: req_9f2c1a4b7e3d

{
  "ids": ["msg_01J8ZQ4K7T"],
  "status": "queued"
}

202 means accepted, not delivered. The message is persisted and a background dispatcher sends it, so a slow provider never becomes a slow request for you. Poll GET /v1/emails/{id} or subscribe to a webhook for the outcome.

Before you can send from a domain, it has to be verified — identity and DKIM both. Sending from an unverified domain returns 403 domain_not_verified.

Node SDK

npm install @brainito/sdk

import { Brainito } from "@brainito/sdk";

const brainito = new Brainito({ apiKey: process.env.BRAINITO_API_KEY! });

const { ids } = await brainito.sendEmail({
  from: "Orders <orders@yourdomain.com>",
  to: "customer@example.com",
  subject: "Your order is on its way",
  html: "<p>Tracking: ABC123</p>",
  idempotencyKey: `order-confirmation-${order.id}`,
});

The SDK retries 429s and 5xx responses with exponential backoff and jitter, honours Retry-After, and never retries a 4xx — a malformed request does not become valid on the second attempt.

import { BrainitoError } from "@brainito/sdk";

try {
  await brainito.sendEmail({ /* ... */ });
} catch (err) {
  if (err instanceof BrainitoError) {
    console.error(err.code, err.message, err.requestId);

    if (err.retryable) {
      // 429 or 5xx — put it back on the queue
    } else {
      // 4xx — it will fail identically forever; dead-letter it
    }
  }
}

Log requestId wherever you handle failures. It is the only thing that identifies the call afterwards, and it is the first thing support will ask for.

Idempotency

Send an Idempotency-Key header on any POST that creates something. Retrying with the same key and the same body returns the original response, marked with Idempotent-Replay: true. Keys are retained for 24 hours.

Prefer a key derived from your own data — order-confirmation-4821 rather than a random one. A random key is lost when your process restarts mid-retry; a derived one survives it, which is exactly when the guarantee matters.

Contacts & consent

curl -X POST https://brainito.com/api/v1/contacts \
  -H "Authorization: Bearer brn_live_XXXXXXXX.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "first_name": "Sam",
    "consent": {
      "subscribed": true,
      "source": "form",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 ...",
      "evidence": { "form": "footer-signup", "page": "/pricing" }
    }
  }'

Record ip_address and user_agent at the moment consent is given. They are what a data-protection enquiry actually asks for, and they cannot be reconstructed later. The full trail is returned as consent_history on GET /v1/contacts/{id}.

Attributes merge shallowly on update. An omitted key is left alone; an explicit null clears it, which is the only way to remove one.

Audiences

An audience is a static list you control. Every one has a short public_id — six characters, drawn from an alphabet with 0, 1, i, l and o removed so it survives being read off a screen or dictated over a call.

It is the same id the dashboard puts in the URL, so a link you were sent and a call your script makes refer to the same list in the same words.

# List your audiences — each carries a public_id
curl https://brainito.com/api/v1/audiences \
  -H "Authorization: Bearer brn_live_XXXXXXXX.YOUR_SECRET"

# { "data": [ { "id": "aud_1837", "public_id": "rupzzr", "name": "Newsletter", ... } ] }

# Add contacts to it — by id, by email, or both
curl -X POST https://brainito.com/api/v1/audiences/rupzzr/contacts \
  -H "Authorization: Bearer brn_live_XXXXXXXX.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["customer@example.com"] }'

# Read who is in it
curl https://brainito.com/api/v1/audiences/rupzzr/contacts \
  -H "Authorization: Bearer brn_live_XXXXXXXX.YOUR_SECRET"

Adding contacts accepts ids, email addresses, or a mix — integrations rarely have only one to hand. A dynamic (segment-backed) audience rejects manual membership, because the next recompute would overwrite it.

Events

Events feed segment membership and can trigger automations. The taxonomy is yours — there is no fixed vocabulary.

curl -X POST https://brainito.com/api/v1/events \
  -H "Authorization: Bearer brn_live_XXXXXXXX.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "placed_order",
    "email": "customer@example.com",
    "value": 89.99,
    "properties": { "order_id": "4821", "items": 3 },
    "dedup_key": "order-4821"
  }'

Post a single event, or up to 500 at once as { "events": [...] }.

Webhooks

Register an endpoint with POST /v1/webhooks. The signing secret is returned once, in that response — store it then, because it cannot be read back.

Every delivery carries Brainito-Signature: t=…,v1=… — an HMAC-SHA256 of {timestamp}.{raw body}. Verify it on every request:

import crypto from "node:crypto";

// Verify BEFORE parsing the body — and use the RAW body, not a re-serialised
// object. Re-serialising changes the bytes and the signature will never match.
export function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=") as [string, string]),
  );
  const timestamp = Number(parts.t);

  // Reject anything old, or a captured delivery can be replayed forever.
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

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

  const a = Buffer.from(parts.v1 ?? "");
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Return a 2xx quickly. Anything else is retried with backoff; repeated failures disable the endpoint and we will tell you.

All endpoints

Generated from the OpenAPI spec, so it always matches what is deployed.

Errors

Every error has the same shape:

{
  "error": {
    "type": "permission_error",
    "code": "domain_not_verified",
    "message": "Verify yourdomain.com before sending from it.",
    "param": "from",
    "request_id": "req_9f2c1a4b7e3d"
  }
}

Branch on error.type for the class and error.code for the specific reason — code is stable across releases, wording is not. message is safe to show a person.

Sending to a suppressed address is not an error. It returns 200 with status: "suppressed", because honouring an unsubscribe is the correct outcome rather than a failure.

Rate limits

Limits are per workspace, not per key — issuing more keys does not raise them. A 429 carries Retry-After in seconds; respect it rather than retrying immediately, which only extends the window.

Your sending allowance is separate from the request rate limit and is set by your plan. Exceeding it returns 429 with a message explaining which limit was reached and how much of it is left.