Name: agent-email-inbox
Author: resend

Use when building any system where email content triggers actions — AI agent inboxes, automated support handlers, email-to-task pipelines, or any workflow processing untrusted inbound email. Always use this skill when the user wants to receive emails and act on them programmatically, even if they do

AI Agent Email Inbox Overview This skill covers setting up a secure email inbox that allows your application or AI agent to receive and respond to emails, with content safety measures in place. Core principle: An AI agent's inbox receives untrusted input. Security configuration is important to handle this safely. The skill builds the agent on a Resend Inbox . An inbox groups email into threads, and your agent replies inside the thread with one call. Resend sets the recipients and the threading headers. If the user has no custom domain, or their plan has no inbox available, use [Receiving without an inbox]( receiving without an inbox) instead. The security levels are the same for both. Why Webhook Based Receiving? Resend uses webhooks for inbound email, meaning your agent is notified instantly when an email arrives. This is valuable for agents because: Real time responsiveness — React to emails within seconds, not minutes No polling overhead — No cron jobs checking "any new mail?" repeatedly Event driven architecture — Your agent only wakes up when there's actually something to process Lower API costs — No wasted calls checking empty inboxes Architecture SDK Version Requirements The inbox flow needs the Node.js SDK resend = 6.34.1, which has resend.inboxes. and the inbox. webhook event types. Always install the latest SDK version. If the project already has a Resend SDK installed, check the version and upgrade if needed. The Python SDK resend = 2.50.0 also has the inbox methods. For the other languages, call the [Inboxes API](https://resend.com/docs/api reference/inboxes/create inbox) over HTTP until their SDK has inbox methods, or use [Receiving without an inbox]( receiving without an inbox). The table below lists the minimums for the Receiving flow: webhook verification ( webhooks.verify() ) and email receiving ( emails.receiving.get() ). The resend skill lists higher minimums because it also covers newer features such as domain claims ( domains.claims. ). If both skills are loaded, use the higher version. Language Package Min Version Node.js resend = 6.9.2 Python resend = 2.21.0 Go resend go/v4 = 4.0.0 Ruby resend = 1.0.0 PHP resend/resend php = 1.1.0 Rust resend rs = 0.20.0 Java resend java = 4.11.0 .NET Resend = 0.2.1 Install the resend npm package: npm install resend (or the equivalent for your language). For full sending docs, install the resend skill. Quick Start 1. Ask the user for their email address. You need a real email address to send test emails to. Ask the user and wait for their response before proceeding. 2. Choose your security level. Decide how to validate incoming emails before any are processed 3. Set up the domain. Verify the user's custom domain for sending, and for receiving unless the inbox uses forwarding (see Domain Setup section) 4. Create the inbox. Create the agent's address with resend.inboxes.create() (see Create the Inbox section) 5. Create webhook endpoint. Handle inbox.email.received events with security built in from the start. The webhook endpoint MUST be a POST route. 6. Set up tunneling (local dev). Use Tailscale Funnel (recommended) or ngrok. See [references/webhook setup.md](references/webhook setup.md) 7. Create webhook via API. Use the Resend Webhook API to register your endpoint programmatically. See [references/webhook setup.md](references/webhook setup.md) 8. Connect to agent. Pass validated emails to your AI agent, and reply in the thread Before You Start: Account & API Key Setup First Question: New or Existing Resend Account? Ask your human: New account just for the agent? → Simpler setup, full account access is fine Existing account with other projects? → The agent needs a full access key, which reaches every project. Prefer a new account for the agent (see API Key Permissions) Creating API Keys Securely Don't paste API keys in chat! They'll be in conversation history forever. Safer options: 1. Environment file method: Human creates .env file directly: echo "RESEND API KEY=re xxx" .env 2. Password manager / secrets manager: Human stores key in 1Password, Vault, etc. 3. If key must be shared in chat: Human should rotate the key immediately after setup API Key Permissions The agent's server needs a full access API key. A "Sending access" key can only reply, forward, create drafts and send drafts. Reading inbox emails or registering webhooks with it returns 401 restricted api key . A sending access key limited to one domain returns 403 on an inbox of another domain. If your human has an existing Resend account with other projects, keep the risk contained: 1. Use a dedicated account for the agent when possible, so a leaked key cannot reach other projects 2. Keep the key on the server only. Never pass it to the AI model or put it in a prompt 3. Rotate the key if it was ever pasted in chat or committed Domain Setup An inbox address lives on a custom domain the user has added to Resend. The domain must be verified for sending (DKIM and SPF). To receive email on it, either enable receiving on the domain, or create the inbox with forwarding: true . Use a subdomain (e.g., agent.example.com ) to avoid disrupting existing email services. Option 1: Receiving on the Domain (Recommended) The user must enable receiving in the Resend dashboard: Domains page → toggle on "Enable Receiving". Then add an MX record: Setting Value Type MX Host Your domain or subdomain (e.g., agent.example.com ) Value Provided in Resend dashboard Priority 10 (must be lowest number to take precedence) Tip: Verify DNS propagation at [dns.email](https://dns.email). DNS Propagation: MX record changes can take up to 48 hours to propagate globally, though often complete within a few hours. Option 2: Forwarding Create the inbox with forwarding: true when the address already receives mail elsewhere (for example, Google Workspace) and the user cannot change its MX record. Resend gives the inbox a receiving address. The user sets up forwarding from their mailbox to it. Read the address from receiving address with resend.inboxes.get() . Create the Inbox Create one inbox for the agent's address: fromName is the name recipients see on the agent's replies. The part before the @ can contain only letters, numbers, . , , % and , so agent+test@ returns a 422. A 403 error means the plan has no inbox left; ask the user to upgrade or use [Receiving without an inbox]( receiving without an inbox). Security Levels Choose your security level before setting up the webhook endpoint. An AI agent that processes emails without security is dangerous — anyone can email instructions that your agent will execute. The webhook code you write next should include your chosen security level from the start. Ask the user what level of security they want, and ensure that they understand what each level means. Level Name When to Use Trade off 1 Strict Allowlist Most use cases — known, fixed set of senders Maximum security, limited functionality 2 Domain Allowlist Organization wide access from trusted domains More flexible, anyone at domain can interact 3 Content Filtering Accept from anyone, filter unsafe patterns Can receive from anyone, pattern matching not foolproof 4 Sandboxed Processing Process all emails with restricted agent capabilities Maximum flexibility, complex to implement 5 Human in the Loop Require human approval for untrusted actions Maximum security, adds latency For detailed implementation code for each level, see [references/security levels.md](references/security levels.md). Level 1: Strict Allowlist (Recommended) Only process emails from explicitly approved addresses. Reject everything else. InboxEmail is the email returned by resend.inboxes.threads.emails.get() . The webhook payload carries the same fields without html and text . agent and notifyOwnerOfRejectedEmail stand for your own code. Security Best Practices Always Do Practice Why Verify webhook signatures Prevents spoofed webhook events Log all rejected emails Audit trail for security review Use allowlists where possible Explicit trust is safer than filtering Rate limit email processing Prevents excessive processing load Separate trusted/untrusted handling Different risk levels need different treatment Never Do Anti Pattern Risk Process emails without validation Anyone can control your agent Trust email headers for authentication Headers are trivially spoofed Execute code from email content Untrusted input should never run as code Store email content in prompts verbatim Untrusted input mixed into prompts can alter agent behavior Give untrusted emails full agent access Scope capabilities to the minimum needed Webhook Endpoint After choosing your security level and setting up your domain, create a webhook endpoint. The webhook endpoint MUST be a POST route. Resend sends all webhook events as POST requests. Critical: Use raw body for verification. Webhook signature verification requires the raw request body. Next.js App Router: Use req.text() (not req.json() ) Express: Use express.raw({ type: 'application/json' }) on the webhook route Next.js App Router Express Resend signs inbox webhooks with the same svix headers as every other webhook. inbox.email.received fires for email the inbox receives. The agent's own replies fire inbox.email.sent instead, so subscribe to inbox.email.received only. For webhook registration via API, tunneling setup, svix fallback, and retry behavior, see [references/webhook setup.md](references/webhook setup.md). Replying from Your Agent Reply inside the thread. Resend addresses the reply and sets the In Reply To and References headers, so the sender's mail client shows it in the same conversation: The reply goes to the email's Reply To addresses, or to its sender when it has none. A sender on your allowlist can set Reply To to any address , so check email.reply to against the allowlist too before the agent replies with anything sensitive. Leave replyAll off unless the agent should copy every recipient of the original email. To start a new conversation, send from the inbox address with resend.emails.send() . For full sending docs, install the resend skill. Receiving without an Inbox Use Resend Receiving directly when the user has no custom domain, or their plan has no inbox available. The security levels above apply unchanged. What differs: Address: use the auto generated <anything @<your id .resend.app address (Dashboard → Emails → Receiving → "Receiving address"), or a custom domain with receiving enabled. No inbox is created. Webhook event: subscribe to email.received instead of inbox.email.received . The payload has email id , from , to and subject , but no body. Reading the email: fetch it with resend.emails.receiving.get(emailId) . Replying: send with resend.emails.send() and set the In Reply To header yourself. There are no threads. The webhook verification is the same as in the inbox examples. Environment Variables Common Mistakes Mistake Fix No sender verification Always validate who sent the email before processing Trusting email headers Use webhook verification, not email headers for auth Same treatment for all emails Differentiate trusted vs untrusted senders Verbose error messages Keep error responses generic to avoid leaking internal logic No rate limiting Implement per sender rate limits. See [references/advanced pattern