agent-email-inbox

An assistant that reads email will do what the email tells it, so anyone who learns the address can give it orders. This sets the inbox up with the checks in place before the first message ever arrives.

WHEN TO USE

SCOPE

USE FOR

Build an inbox that lets an AI agent receive email and reply to it automatically.
Restrict which senders your agent's inbox will act on with an allowlist of approved addresses.
Verify inbound webhook signatures so a spoofed email can't trick your agent into acting.
Route support requests into an automated handler that only acts on messages from trusted domains.

NOT FOR

Full email-sending documentation such as batches, templates, and broadcasts — see the resend skill.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (14)

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

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
Create webhook via API — Use the Resend Webhook API to register your endpoint programmatically. See references/webhook-setup.md
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:

Environment file method: Human creates .env file directly: echo "RESEND_API_KEY=re_xxx" >> .env
Password manager / secrets manager: Human stores key in 1Password, Vault, etc.
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:

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

Domain Setup

Option 1: Resend-Managed Domain (Recommended for Getting Started)

Use your auto-generated address: <anything>@<your-id>.resend.app

No DNS configuration needed. Find your address in Dashboard → Emails → Receiving → "Receiving address".

Option 2: Custom Domain

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)

Use a subdomain (e.g., agent.example.com) to avoid disrupting existing email services.

Tip: Verify DNS propagation at dns.email.

DNS Propagation: MX record changes can take up to 48 hours to propagate globally, though often complete within a few hours.

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.

Level 1: Strict Allowlist (Recommended)

Only process emails from explicitly approved addresses. Reject everything else.

const ALLOWED_SENDERS = [
  'you@youremail.com',
  'notifications@github.com',
];

async function processEmailForAgent(
  eventData: EmailReceivedEvent,
  emailContent: EmailContent
) {
  const sender = eventData.from.toLowerCase();

  if (!ALLOWED_SENDERS.some(allowed => sender === allowed.toLowerCase())) {
    console.log(`Rejected email from unauthorized sender: ${sender}`);
    await notifyOwnerOfRejectedEmail(eventData);
    return;
  }

  await agent.processEmail({
    from: eventData.from,
    subject: eventData.subject,
    body: emailContent.text || emailContent.html,
  });
}

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

// app/webhook/route.ts
import { Resend } from 'resend';
import { NextRequest, NextResponse } from 'next/server';

const resend = new Resend(process.env.RESEND_API_KEY);

export async function POST(req: NextRequest) {
  try {
    const payload = await req.text();

    const event = resend.webhooks.verify({
      payload,
      headers: {
        'svix-id': req.headers.get('svix-id'),
        'svix-timestamp': req.headers.get('svix-timestamp'),
        'svix-signature': req.headers.get('svix-signature'),
      },
      secret: process.env.RESEND_WEBHOOK_SECRET,
    });

    if (event.type === 'email.received') {
      // Webhook payload only includes metadata, not email body
      const { data: email } = await resend.emails.receiving.get(
        event.data.email_id
      );

      // Apply the security level chosen above
      await processEmailForAgent(event.data, email);
    }

    return new NextResponse('OK', { status: 200 });
  } catch (error) {
    console.error('Webhook error:', error);
    return new NextResponse('Error', { status: 400 });
  }
}

Express

import express from 'express';
import { Resend } from 'resend';

const app = express();
const resend = new Resend(process.env.RESEND_API_KEY);

const ALLOWED_SENDERS = (process.env.ALLOWED_SENDERS || '').split(',').filter(Boolean);
const isAllowedSender = (sender) =>
  ALLOWED_SENDERS.some(allowed => sender === allowed.toLowerCase());

app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const payload = req.body.toString();

    const event = resend.webhooks.verify({
      payload,
      headers: {
        'svix-id': req.headers['svix-id'],
        'svix-timestamp': req.headers['svix-timestamp'],
        'svix-signature': req.headers['svix-signature'],
      },
      secret: process.env.RESEND_WEBHOOK_SECRET,
    });

    if (event.type === 'email.received') {
      const sender = event.data.from.toLowerCase();

      if (!isAllowedSender(sender)) {
        console.log(`Rejected email from unauthorized sender: ${sender}`);
        res.status(200).send('OK'); // Return 200 even for rejected emails
        return;
      }

      const { data: email } = await resend.emails.receiving.get(event.data.email_id);
      await processEmailForAgent(event.data, email);
    }

    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(400).send('Error');
  }
});

app.get('/', (req, res) => res.send('Agent Email Inbox - Ready'));
app.listen(3000, () => console.log('Webhook server running on :3000'));

For webhook registration via API, tunneling setup, svix fallback, and retry behavior, see references/webhook-setup.md.

Sending Emails from Your Agent

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

async function sendAgentReply(to: string, subject: string, body: string, inReplyTo?: string) {
  if (!isAllowedToReply(to)) {
    throw new Error('Cannot send to this address');
  }

  const { data, error } = await resend.emails.send({
    from: 'Agent <agent@example.com>',
    to: [to],
    subject: subject.startsWith('Re:') ? subject : `Re: ${subject}`,
    text: body,
    headers: inReplyTo ? { 'In-Reply-To': inReplyTo } : undefined,
  });

  if (error) throw new Error(`Failed to send: ${error.message}`);
  return data.id;
}

For full sending docs, install the resend skill.

Environment Variables

# Required
RESEND_API_KEY=re_xxxxxxxxx
RESEND_WEBHOOK_SECRET=whsec_xxxxxxxxx

# Security Configuration
SECURITY_LEVEL=strict                    # strict | domain | filtered | sandboxed
ALLOWED_SENDERS=you@email.com,trusted@example.com
ALLOWED_DOMAINS=example.com
OWNER_EMAIL=you@email.com               # For security notifications

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-patterns.md
Processing HTML directly	Strip HTML or use text-only to reduce complexity and risk
No logging of rejections	Log all security events for audit
Using ephemeral tunnel URLs	Use persistent URLs (Tailscale Funnel, paid ngrok) or deploy to production
Using `express.json()` on webhook route	Use `express.raw({ type: 'application/json' })` — JSON parsing breaks signature verification
Returning non-200 for rejected emails	Always return 200 to acknowledge receipt — otherwise Resend retries
Old Resend SDK version	`emails.receiving.get()` and `webhooks.verify()` require recent SDK versions — see SDK Version Requirements

Testing

Use Resend's test addresses for development:

delivered@resend.dev — Simulates successful delivery
bounced@resend.dev — Simulates hard bounce

For security testing, send test emails from non-allowlisted addresses to verify rejection works correctly.

Quick verification checklist:

Server is running: curl http://localhost:3000 should return a response
Tunnel is working: curl https://<your-tunnel-url> should return the same response
Webhook is active: Check status in Resend dashboard → Webhooks
Send a test email from an allowlisted address and check server logs

Related Skills

For full sending and receiving docs, install the resend skill

Account or credentials required

3 FOR YOU

All items below are required.

01
Create a Resend account and API key
Sign up for Resend and create an API key. If the agent shares an existing account with other projects, scope the key to just the agent's sending domain instead of granting full account access.
You set: RESEND_API_KEY
02
Turn on inbound email receiving for a domain
In the Resend dashboard, use the auto-generated <id>.resend.app address to start immediately, or toggle on 'Enable Receiving' for a custom domain and add the MX record it provides at priority 10.
03
Choose a security level for incoming mail
Decide, before the webhook is written, whether incoming email will be checked against a strict sender allowlist, a domain allowlist, content filtering, sandboxed processing, or human approval — the webhook enforces whichever level is chosen.

Listed as free: Connected services may require an account or charge fees.
Setup details: Expect some account or credential setup.

This skill ships inside the Resend Skills plugin. Listed package contents include an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add resend/resend-skills --skill "agent-email-inbox" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Resend Skills plugin package selected for your AI tool.

PLUGIN MARKETPLACE

Add the marketplace, then install the plugin

Typed inside the agent's own prompt, not in a terminal. The marketplace is called resend-skills, which is the part after the @.

/plugin marketplace add resend/resend-skills

02
```
/plugin install resend@resend-skills
```

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub