One REST API for transactional email, batches, broadcasts and the mailbox. JSON in, JSON out, and if it can make an HTTPS request, it can send through KubeMail.

Base URL: https://api.kubemail.app. All endpoints below live under /v1, and times are ISO-8601 UTC strings.

curl -X POST https://api.kubemail.app/v1/emails \
  -H "Authorization: Bearer km_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up!</p>"
  }'

HTTP/1.1 202 Accepted
{ "id": "msg_2Hc9xTq4Lk", "status": "queued" }

Create an API key in the dashboard under Developers → API keys and send it as a bearer token. The token (km_live_…) is shown once, so store it in a secret manager.

Authorization: Bearer km_live_xxxxxxxxxxxx

Keys are either full_access (every /v1 route except account and billing) or sending_access (only POST /v1/emails* and POST /v1/broadcasts, optionally pinned to one domain).

Any non-2xx response has the same shape. Validation errors use 422 and may list the failing fields.

{
  "error": {
    "code": "validation_error",
    "message": "Human readable",
    "details": [{ "path": "to[0]", "message": "Invalid email" }]
  }
}

List endpoints take ?limit=50&cursor=… and return { data: [...], next_cursor }. Pass next_cursor back until it is null.

When you exceed your rate limit the API returns 429 with a Retry-After header. Send endpoints also return X-RateLimit-Limit and X-RateLimit-Remaining.

Send endpoints accept an Idempotency-Key header. Any retry with the same key within 24 hours returns the original response instead of sending again.

Add a domain, publish the DNS records we generate, then verify. A domain is verified once every required record checks out.

Records generated for acme.com:

The return-path CNAME gives you SPF and bounce alignment without touching your root SPF record, and your root MX is never changed.

type SendEmail = {
  from: string;                    // "Acme <hi@acme.com>", domain must be verified
  to: string | string[];           // up to 50 recipients
  cc?: string | string[];
  bcc?: string | string[];
  reply_to?: string | string[];
  subject: string;
  html?: string;                   // at least one of html / text
  text?: string;
  headers?: Record<string, string>;
  tags?: Record<string, string>;   // up to 10, used for filtering
  variables?: Record<string, string | number | boolean>; // {{ var }} substitution
};

Recipients on your suppression list are dropped with a rejected event.

Send one message to up to 100,000 recipients, each with their own variables.

POST /v1/broadcasts
{
  "from": "Acme <news@acme.com>",
  "subject": "October product update, {{ first_name }}",
  "html": "<h1>Hi {{ first_name }}</h1>…",
  "recipients": [
    { "email": "ada@example.com", "variables": { "first_name": "Ada" } }
  ]
}

202 { "id": "bc_…", "accepted": 1, "suppressed": 0, "status": "queued" }

Statuses: queued, sent, delivered, deferred, bounced, complained, rejected, opened, clicked, expired. Each event carries the SMTP code, enhanced code and raw response where there is one.

Each delivery is a POST of { type, created_at, data: { email_id, recipient, … } }, signed with the secret returned on creation (shown once):

// KubeMail-Signature: t=<unix>,v1=<hex hmac_sha256(secret, "<t>.<body>")>
import crypto from "node:crypto";

function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Hard bounces, complaints and unsubscribes are added automatically. You can also manage the list yourself.

With the inbound MX record in place, mail to <mailbox>@inbox.<domain> is stored and threaded per address. Replies you send go out from <mailbox>@<domain> with a reply-to on the inbox domain, so the conversation comes back.

Inbound HTML is untrusted, so render it in a sandboxed frame.

GET /v1/stats?range=24h|7d|30d returns totals, rates (fractions from 0 to 1), a time series (hourly for 24h, daily otherwise) and your usage for the current period.

Questions? Contact support.