Let your inbox wake your agent.

Track outgoing mail too.

Opt into message.delivery_updated to learn about recipient acceptance, retries and bounces. Existing callbacks remain incoming-only until you enable these events. Outgoing delivery guide →

Private by default. Free to receive.

The callback receives a message reference. Sender, subject, body and attachments stay out of the notification. Reading requires your agent’s API key. Receiving, webhook delivery and reading cost no sending credits; replies use your usual balance and limits.

Connect a callback.

1. Register your HTTPS URLPOST to /api/v1/agent/webhooks with your Bearer key and {"url":"https://your-domain.example/mail"}. Store the returned id and one-time signingSecret securely.
2. Verify your receiverConfigure its signing secret, then POST to /api/v1/agent/webhooks/YOUR_ID/verify. Your receiver checks the signature and echoes the verification challenge as JSON.
3. Receive, acknowledge, then workSave each event ID before returning 2xx. Read the message using its folder, uidValidity and uid. Existing messages are not backfilled.

{
  "id": "<event-uuid>",
  "type": "message.received",
  "createdAt": "<observation-time>",
  "data": {"folder":"INBOX","uidValidity":"1758140000","uid":"42"}
}

Verify every notification.

Check webhook-signature against HMAC-SHA256 of ID.TIMESTAMP.RAW_BODY using your complete signing secret. The other headers are webhook-id and webhook-timestamp. Use a constant-time comparison, a five-minute timestamp tolerance and durable event deduplication. The example includes the verifier.

Callbacks require a public HTTPS hostname on port 443 with a valid certificate. Private network addresses and redirects are blocked. Return a small response within seven seconds.

Retries you can inspect.

Failed deliveries get up to eight attempts over 24 hours. Each retry keeps the same event ID and body. Delivery may repeat or arrive out of order. Inspect GET /api/v1/agent/webhooks/deliveries for 30 days of history; POST to a completed event’s URL to replay it, up to three times.

One callback per agent. Delete it to revoke delivery or replace a lost signing secret. An already-running HTTP request may still finish. If the mailbox identity changes, the endpoint pauses until you verify a new baseline.

Start with a draft you can review.

The working Node example saves incoming events, fetches the message privately and prepares a reply in the same conversation. Human approval is the default. Optional automatic sending is limited to one recipient you configure; email content never grants permission to change that recipient or spend beyond your account limits.

What this release observes.

KeyKeeper checks subscribed INBOXes about every 15 seconds. Messages moved or deleted before a check may not produce an event; copied or appended messages can. Other folders and historical backfill are not included. Keep the inbox API available for reconciliation. Events tell you a message was observed, not that a reply reached someone’s inbox.