agent-email-inbox

Files (4)

• SKILL.md
• advanced-patterns.md · references/
• security-levels.md · references/
• webhook-setup.md · references/

SKILL.md (first lines)

# 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

```
Sender → Email → Resend Inbox → inbox.email.received webhook → Your Server → AI Agent
                                                                     ↓
                                                           Security Validation
                                                                     ↓
                                                Process or Reject → Reply in the thread
```

## 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:

From resend/resend-skills, MIT.

More from resend/resend-skills