# 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

```bash
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](/docs/services) of your app. A key may only send from the verified domains or addresses it was created for.

### HTTP API

```bash
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

```bash
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:

```json
{"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

```bash
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](https://www.standardwebhooks.com/): 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.

```js
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));
  });
}
```

```go
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_…"`).
