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
| from | required | An address on one of your verified sending domains, with an optional name. |
| to | required | Exactly one recipient. One call, one message: campaigns go through the dashboard. |
| subject | required | One line, 998 characters at most. |
| html, text | one of them | Send both when you can: the plain text is what some readers and filters look at. |
| reply_to | Where replies go, when not to from. | |
| attachments | Up to 20, 5 MB in total once decoded: filename, content_type, and content in Base64. | |
| headers | Your own X- headers, References and In-Reply-To. X-Keel- headers are ours. | |
| tag | A label of yours, 64 characters at most, echoed in every event. | |
| metadata | Up to 10 keys of your own, echoed in every event: the way to find your order again. | |
| idempotency_key | The 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" } }| 400 | invalid_… | The request is not what the contract asks for; the message says which field. |
| 401 | unauthenticated | No key, or a key that was revoked. |
| 403 | sandbox_recipient | Your organisation is in the sandbox: it sends only to its own members until approved. |
| 403 | suspended | Sending is suspended for your organisation. |
| 413 | attachments_too_large | Attachments over 5 MB. |
| 422 | unverified_domain | from is not on one of your verified sending domains. |
| 422 | suppressed_recipient | The recipient bounced hard or complained; reason says which. An unsubscribe does not block transactional mail. |
| 429 | rate_limited | More than 20 requests a second on one key. Retry-After says when. |
| 429 | quota_exceeded | Your daily quota is used up. Retry-After says when. |
| 503 | no_relay / unavailable | Nothing 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
| queued | We accepted the message. |
| sent | It was handed over for delivery. |
| delivered | The recipient's mail server took it. |
| deferred | The mail server said "later"; it will be tried again. Carries smtp_code and diagnostic. |
| bounced | It was refused. bounce_type is hard (the address is suppressed from now on), soft, or relay_rejected (it never left). |
| complained | The recipient marked it as spam. The address is suppressed from now on. |
| unsubscribed | The recipient left your campaigns, by the footer link or their mail program’s button. |
| clicked | A 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.