API reference

One call sends one transactional message. Two more read what became of it. Everything is JSON over HTTPS athttps://api.keelsend.com.

Authentication

Every call carries an API key: Authorization: Bearer ks_live_…. An owner of your organisation creates keys in thedashboard; a key is shown once and can be revoked at any time. Keep it on your server: never in a browser or an app.

Send a message

POST /v1/messages answers 202 as soon as the message is queued; it is handed over for delivery right after.

curl

curl https://api.keelsend.com/v1/messages \
  -H "Authorization: Bearer $KEELSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <billing@mail.acme.com>",
    "to": "jane@example.com",
    "subject": "Your invoice",
    "html": "<p>Thanks for your order.</p>",
    "text": "Thanks for your order.",
    "tag": "invoice",
    "metadata": { "order": "1042" },
    "idempotency_key": "invoice-1042"
  }'

Node

// Node 18+: fetch is built in.
const res = await fetch('https://api.keelsend.com/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEELSEND_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'Acme <billing@mail.acme.com>',
    to: 'jane@example.com',
    subject: 'Your invoice',
    html: '<p>Thanks for your order.</p>',
    text: 'Thanks for your order.',
    tag: 'invoice',
    metadata: { order: '1042' },
    idempotency_key: 'invoice-1042',
  }),
})
const body = await res.json()
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`)
console.log(body.message_id)

Java

// Java 11+: java.net.http is built in.
var body = """
    {"from": "Acme <billing@mail.acme.com>", "to": "jane@example.com",
     "subject": "Your invoice", "html": "<p>Thanks for your order.</p>",
     "text": "Thanks for your order.", "tag": "invoice",
     "metadata": {"order": "1042"}, "idempotency_key": "invoice-1042"}""";
var request = HttpRequest.newBuilder(URI.create("https://api.keelsend.com/v1/messages"))
    .header("Authorization", "Bearer " + System.getenv("KEELSEND_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 202) throw new IllegalStateException(response.body());
System.out.println(response.body()); // {"message_id":"msg_…"}

The answer

HTTP/1.1 202 Accepted

{ "message_id": "msg_k3m9q2x7a8b4c5d6" }

Fields

fromrequiredAn address on one of your verified sending domains, with an optional name.
torequiredExactly one recipient. One call, one message: campaigns go through the dashboard.
subjectrequiredOne line, 998 characters at most.
html, textone of themSend both when you can: the plain text is what some readers and filters look at.
reply_toWhere replies go, when not to from.
attachmentsUp to 20, 5 MB in total once decoded: filename, content_type, and content in Base64.
headersYour own X- headers, References and In-Reply-To. X-Keel- headers are ours.
tagA label of yours, 64 characters at most, echoed in every event.
metadataUp to 10 keys of your own, echoed in every event: the way to find your order again.
idempotency_keyThe same key within 24 hours returns the first message and sends nothing.

When a message is refused

An error is a status, a stable code to branch on, and a message written for a person.

HTTP/1.1 422 Unprocessable Entity

{ "error": { "code": "suppressed_recipient",
             "message": "This recipient is suppressed.",
             "reason": "hard_bounce" } }
400invalid_…The request is not what the contract asks for; the message says which field.
401unauthenticatedNo key, or a key that was revoked.
403sandbox_recipientYour organisation is in the sandbox: it sends only to its own members until approved.
403suspendedSending is suspended for your organisation.
413attachments_too_largeAttachments over 5 MB.
422unverified_domainfrom is not on one of your verified sending domains.
422suppressed_recipientThe recipient bounced hard or complained; reason says which. An unsubscribe does not block transactional mail.
429rate_limitedMore than 20 requests a second on one key. Retry-After says when.
429quota_exceededYour daily quota is used up. Retry-After says when.
503no_relay / unavailableNothing was accepted. Try again: with an idempotency key, a retry never sends twice.

Read a message

GET /v1/messages/{id} gives its status and every event so far, oldest first.

curl https://api.keelsend.com/v1/messages/msg_k3m9q2x7a8b4c5d6 \
  -H "Authorization: Bearer $KEELSEND_API_KEY"

{
  "id": "msg_k3m9q2x7a8b4c5d6",
  "status": "delivered",
  "stream": "transactional",
  "from": "Acme <billing@mail.acme.com>",
  "to": "jane@example.com",
  "subject": "Your invoice",
  "tag": "invoice",
  "metadata": { "order": "1042" },
  "created_at": "2026-10-07T09:15:00Z",
  "sent_at": "2026-10-07T09:15:01Z",
  "events": [
    { "id": "evt_…", "type": "queued",    "at": "2026-10-07T09:15:00Z", … },
    { "id": "evt_…", "type": "sent",      "at": "2026-10-07T09:15:01Z", … },
    { "id": "evt_…", "type": "delivered", "at": "2026-10-07T09:15:03Z", … }
  ]
}

status is one of queued, sent, deferred, delivered,bounced, complained, failed (it never left: nothing took it within 24 hours, or it was refused before leaving).

Events

queuedWe accepted the message.
sentIt was handed over for delivery.
deliveredThe recipient's mail server took it.
deferredThe mail server said "later"; it will be tried again. Carries smtp_code and diagnostic.
bouncedIt was refused. bounce_type is hard (the address is suppressed from now on), soft, or relay_rejected (it never left).
complainedThe recipient marked it as spam. The address is suppressed from now on.
unsubscribedThe recipient left your campaigns, by the footer link or their mail program’s button.
clickedA tracked link was followed (campaigns with click tracking). Carries url.

GET /v1/events is the feed of all your events in the order we recorded them. Keep the next_since of each answer and send it assince on the next call: you never miss one and never read one twice. limit is up to 500.

curl "https://api.keelsend.com/v1/events?since=evt_01hq3v9x2m7k4n8p5r6s0t1w2y&limit=100" \
  -H "Authorization: Bearer $KEELSEND_API_KEY"

{
  "events": [
    { "id": "evt_…", "type": "bounced", "message_id": "msg_…",
      "at": "2026-10-07T09:20:11Z", "to": "gone@example.com",
      "stream": "transactional", "tag": "invoice", "metadata": { "order": "1043" },
      "bounce_type": "hard", "smtp_code": 550,
      "diagnostic": "550 5.1.1 no such user" }
  ],
  "next_since": "evt_…"
}

Webhooks

Rather than polling, give us an HTTPS address in the dashboard and choose the event types you want. Each event is posted as the JSON object shown above. Answer 2xx within 10 seconds; anything else is retried with growing pauses for 24 hours. Delivery is at least once: use the event's id to ignore one you already have.

Every request is signed with your webhook secret: X-Keel-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of<t>.<raw body>. Check it before trusting the body, and refuse a timestamp older than five minutes.

Node

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: the request body exactly as received, before any JSON parsing.
export function isFromKeelSend(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false // older than five minutes
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}

Java

static boolean isFromKeelSend(String rawBody, String header, String secret) throws Exception {
    String t = null, v1 = null;
    for (String part : header.split(",")) {
        String p = part.trim();
        if (p.startsWith("t=")) t = p.substring(2);
        if (p.startsWith("v1=")) v1 = p.substring(3);
    }
    if (t == null || v1 == null || Math.abs(Instant.now().getEpochSecond() - Long.parseLong(t)) > 300) return false;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String expected = HexFormat.of().formatHex(mac.doFinal((t + "." + rawBody).getBytes(StandardCharsets.UTF_8)));
    return MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), v1.getBytes(StandardCharsets.UTF_8));
}

Limits and retention

  • 20 requests a second per key, and your organisation's daily quota (1,000 messages a day to start with).
  • In the sandbox: 50 messages a day, to your own members' addresses only, until your organisation is approved.
  • Message content is kept 72 hours, then deleted. Events, recipients and subjects are kept 90 days.
  • Everything is stored and processed in the European Union.