Skip to content
← Public packages

@kody/agent-mail

AgentMail inboxes for agents: create/list inboxes, messages, threads, and Svix webhook ingress.

FollowFork

IntegrationsTopics: agentmail, email, inbox, webhooks, agents, integrations

Version
1.1.0
License
Published
October 14, 2026
Pinned commit
7bb6e71
Rating
No ratings yet
Forks
0
Adaptation effort
—

README

Agent docs

@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
  • Manage AgentMail allow and block lists (sender/recipient email addresses or domains) at organization, pod, or inbox scope

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.

Allow and block lists

AgentMail has native Lists, and AgentMail enforces them itself, so blocked mail never reaches the inbound webhook. This package wraps that API. It does not keep its own copy of the rules.

  • receive (the default direction) covers new inbound mail. reply covers inbound replies to mail you sent, and replies check only the reply lists. send covers outbound recipients.
  • An allow list with at least one entry switches that scope to allowlist-only: senders that don't match are rejected. A block list rejects the senders that match. Empty lists allow everything.
  • Entries are a full address (partner@example.com) or a domain (example.com).
  • Scope: pass inboxId for one inbox or podId for a pod. Omit both for the whole organization. The most specific scope that has a match wins.
  • add-rule and remove-rule need confirm: true, or dryRun: true for a preview.

To make an inbox accept mail only from your own harness inboxes, add a receive allow entry for each one with that inboxId.

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
  • list-rules returns allow/block entries; add-rule / remove-rule refuse live calls unless dryRun: true or confirm: true
  • 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.

Report this listing

Log in to report this listing.