@kody/agent-mail

@kody/agent-mail

Intent

Thin AgentMail API helpers for giving agents their own email inboxes: list and create inboxes, read messages and threads, send or reply with an explicit confirm / dryRun guard, register AgentMail webhooks, and handle inbound Svix deliveries on the package inbound webhook. Uses the user secret agentmailApiKey against api.agentmail.to (EU host api.agentmail.eu is also supported for secret host approval). Does not auto-send on inbox create.

What it does

• List and create AgentMail inboxes (optional clientId idempotency)
• Read messages and threads for an inbox
• Send or reply with dryRun preview or live confirm
• Register AgentMail-side webhooks and verify inbound Svix deliveries

Prerequisites / setup

1. Create an AgentMail API key, then save it at secrets/new with allowedHosts=api.agentmail.to (add api.agentmail.eu if you use the EU API).
2. Approve host api.agentmail.to if prompted.
3. Optional for verified inbound webhooks: save the AgentMail webhook signing secret (starts with whsec_) as agentmailWebhookSecret at secrets/new.
4. Agents: see AGENTS.md for import paths and smoke checks.

Webhooks

AgentMail delivers events over Svix (svix-id, svix-timestamp, svix-signature). Kody platform webhook verification only supports hmac-sha256, so this package declares the inbound webhook without platform verification and verifies Svix inside ./handle-webhook when agentmailWebhookSecret is present.

1. After publish, mint the package webhook URL with webhookUrlMint and webhookName: "inbound" (the URL is a credential — do not paste it into chat or commit it).
2. Create an AgentMail webhook pointing at that URL for event_types including message.received (and any other types you need). See Create Webhook.
3. Save the returned AgentMail secret (whsec_…) as user secret agentmailWebhookSecret.
4. Verification details: Webhook verification.

You can also register the AgentMail-side webhook via this package's create-webhook helper with confirm: true (or dryRun: true) once you have a minted ingress URL.

Done when

• agentmailApiKey is saved and api.agentmail.to is approved
• You can list inboxes (and optionally whoami) without errors
• Send / reply / create-webhook refuse live calls unless dryRun: true or confirm: true
• Creating an inbox does not auto-send mail
• Optional: inbound Svix verification works when agentmailWebhookSecret is set

Branding

Listing icons use the official AgentMail mark from the agentmail.to favicon (white fedora agent silhouette on black). The unmodified source is in brand/agentmail-favicon.png.