# AI agent email inbox Human Guide

## What This Is For
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. It gives the agent a clearer input/output frame for email marketing: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the AI agent email inbox agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for AI agent email inbox.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the AI agent email inbox guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- **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
- **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.
- **Choose your security level** — Decide how to validate incoming emails *before* any are processed
- **Set up receiving domain** — Configure MX records for the user's custom domain (see Domain Setup section)
- Create webhook endpoint** — Handle `email.received` events with security built in from the start. **The webhook endpoint MUST be a POST route.
- **Set up tunneling** (local dev) — Use Tailscale Funnel (recommended) or ngrok. See [references/webhook-setup.md](references/webhook-setup.md)
- **Create webhook via API** — Use the Resend Webhook API to register your endpoint programmatically. See [references/webhook-setup.md](references/webhook-setup.md)
- **Connect to agent** — Pass validated emails to your AI agent for processing
- **New account just for the agent?** → Simpler setup, full account access is fine

## Decision Points And Nuance
The original skill emphasizes: Overview, Why Webhook-Based Receiving?, Architecture, SDK Version Requirements, Quick Start, Before You Start: Account & API Key Setup, First Question: New or Existing Resend Account?, Creating API Keys Securely, Domain-Scoped API Keys (Recommended for Existing Accounts), Domain Setup.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- **Core principle:** An AI agent's inbox receives untrusted input. Security configuration is important to handle this safely.
- Create webhook endpoint** — Handle `email.received` events with security built in from the start. **The webhook endpoint MUST be a POST route.
- > Don't paste API keys in chat! They'll be in conversation history forever.
- **If key must be shared in chat:** Human should rotate the key immediately after setup
- The user must enable receiving in the Resend dashboard: Domains page → toggle on "Enable Receiving".
- | **Priority** | 10 (must be lowest number to take precedence) |
- **Use a subdomain** (e.g., `agent.example.com`) to avoid disrupting existing email services.
- | Execute code from email content | Untrusted input should never run as code |

## Copy-And-Paste Prompt
```text
Use the AI agent email inbox human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the resend/resend-skills skill entry for `agent-email-inbox`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

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

### 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 (MX) → Webhook → Your Server → AI Agent
                                              ↓
                                    Security Validation
                                              ↓
                                    Process or Reject
```

## SDK Version Requirements

This skill requires Resend SDK features for webhook verification (`webhooks.verify()`) and email receiving (`emails.receiving.get()`). Always install the latest SDK version. If the project already has a Resend SDK installed, check the version and upgrade if needed.

| Language | Package | Min Version |
|----------|---------|-------------|
| Node.js | `resend` | >= 6.9.2 |
| Python | `resend` | >= 2.21.0 |
| Go | `resend-go/v3` | >= 3.1.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 receiving domain** — Configure MX records for the user's custom domain (see Domain Setup section)
4. **Create webhook endpoint** — Handle `email.received` events with security built in from the start. **The webhook endpoint MUST be a POST route.**
5. **Set up tunneling** (local dev) — Use Tailscale Funnel (recommended) or ngrok. See [references/webhook-setup.md](references/webhook-setup.md)
6. **Create webhook via API** — Use the Resend Webhook API to register your endpoint programmatically. See [references/webhook-setup.md](references/webhook-setup.md)
7. **Connect to agent** — Pass validated emails to your AI agent for processing

## 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?** → Use domain-scoped API keys for sandboxing

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

### Domain-Scoped API Keys (Recommended for Existing Accounts)

If your human has an existing Resend account with other projects, create a **domain-scoped API key**:

1. **Verify the agent's domain first** (Dashboard → Domains → Add Domain)
2. **Create a scoped API key:** Dashboard → API Keys → Create API Key → "Sending access" → select only the agent's domain
3. **Result:** Even if the key leaks, it can only send from one domain