Get started

App mail

Apps send transactional mail – sign-up confirmations, password resets, receipts – with a sending key, over an HTTP API or SMTP. Delivery events (delivered, bounced, complained, …) arrive as event webhooks, and inbound routes post mail sent to an address of your domain to your app. App sending is enabled per workspace; ask support to enable it. There is no open- or click-tracking.

Price
App mails (per recipient) €0.40 per 1,000
Inbound route calls €0.10 per 1,000

App mails count against your plan: Hobby 50000 per month, Pro 500000 (more after a review). Newsletters and marketing mail are not allowed.

Sending keys

keel mail keys create --domain example.de --name shop

The key (keelmail_…) is shown once together with MAIL_API_URL and SMTP_URL. Store them as secret variables of your app. A key may only send from the verified domains or addresses it was created for.

HTTP API

curl https://send.mail.keel.run/v1/messages \
  -H "Authorization: Bearer $MAIL_API_KEY" \
  -H "Idempotency-Key: order-1234-receipt" \
  -H "Content-Type: application/json" \
  -d '{"from": "Shop <noreply@example.de>", "to": ["bob@example.com"], "subject": "Your order",
       "text": "Thanks for your order!", "tags": {"kind": "receipt"}}'

The answer (202) has the message ID (msg_…) and each recipient's status (queued or suppressed). GET /v1/messages/{id} shows the events. Up to 50 recipients per call; the same Idempotency-Key within 24 hours sends once. The OpenAPI description is at https://send.mail.keel.run/openapi.json.

SMTP relay

Use SMTP_URL (smtps://<key id>:<key>@smtp.mail.keel.run:465) with any SMTP library: user name is the key ID (mkey_…), password the key.

Message log and suppressions

keel mail log (or Mail → Log) lists app mail with each recipient's status – metadata only, never subjects or content. Addresses that bounced hard or complained land on the suppression list; mail to them is not attempted (suppressed). Remove an address only when its owner asked for it: keel mail suppressions remove bob@example.com. Mailboxes are never affected by suppressions.

Event webhooks

keel mail webhooks add https://shop.keelrun.app/hooks/mail-events --events delivered,bounced,complained

Events: queued, delivered, deferred, bounced (data.bounce is hard or soft), complained, rejected, suppressed, expired, route_delivered, route_failed. Payload:

{"type": "bounced", "timestamp": "2026-11-18T10:06:00Z",
 "data": {"event_id": "evt_…", "message_id": "msg_…", "recipient": "bob@example.com", "tags": {"kind": "receipt"}, "bounce": "hard", "code": 550}}

Answer with any 2xx within 10 seconds. Other answers are retried with backoff for 24 hours.

Inbound routes

keel mail routes add 'support+*@example.de' --url https://shop.keelrun.app/hooks/mail
keel mail routes test support@example.de

A route is an address like a mailbox: support@, support+*@ (every support+anything@) or *@ (every address without a mailbox, alias or list). Mail to it is checked like mailbox mail (spam, viruses, DMARC); spam is discarded or quarantined, never posted. Optionally a mailbox gets a copy.

The default mode parsed posts JSON with the envelope, headers, from, to, cc, subject, text and html (up to 1 MB each, truncated says so), auth (SPF, DKIM, DMARC, ARC results), spam and attachments with signed download links (valid 24 hours, like raw_url for the whole message). Mode raw posts the message itself as message/rfc822. After 24 hours of failed attempts the event route_failed is sent and the owners get an e-mail.

Route URLs must be https and public: internal addresses are refused on every call. Apps on keel.run are reached through their public URL.

Verify the signature

Every call (event webhooks and routes) is signed per Standard Webhooks: headers webhook-id, webhook-timestamp and webhook-signature (v1,<base64>). The signature is HMAC-SHA256 with the secret (the part after whsec_, base64-decoded) over <webhook-id>.<webhook-timestamp>.<body>. Check it on the raw body, refuse timestamps older than 5 minutes, and use webhook-id to ignore repeats.

import crypto from 'node:crypto';

export function verify(secret, headers, rawBody) {
  const id = headers['webhook-id'], ts = headers['webhook-timestamp'], sigs = headers['webhook-signature'] ?? '';
  if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return sigs.split(' ').some((s) => {
    const got = s.replace(/^v1,/, '');
    return got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
  });
}
func verify(secret string, h http.Header, body []byte) bool {
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	ts, err2 := strconv.ParseInt(h.Get("webhook-timestamp"), 10, 64)
	if err != nil || err2 != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
		return false
	}
	mac := hmac.New(sha256.New, key)
	fmt.Fprintf(mac, "%s.%d.", h.Get("webhook-id"), ts)
	mac.Write(body)
	want := "v1," + base64.StdEncoding.EncodeToString(mac.Sum(nil))
	for _, s := range strings.Fields(h.Get("webhook-signature")) {
		if hmac.Equal([]byte(s), []byte(want)) {
			return true
		}
	}
	return false
}

Libraries for Standard Webhooks (standardwebhooks for Node, Python, Go, Ruby, …) work as well. The secret is shown when the webhook or route is created; you can also bring your own for a route (secret: "whsec_…").

View as Markdown