agent-email-inbox

AI Agent Email Inbox

Set up a secure email inbox that lets an AI agent receive and respond to emails, with protection against prompt injection and email-based attacks.

Core principle: An AI agent's inbox is a potential attack vector. Malicious actors can email instructions that the agent might blindly follow. Security configuration is not optional — it's the first thing you implement, not the last.

This skill is context-independent — it does not use brand/ files and works identically in any project.

On Activation

1. Ask the user which agent needs an email inbox and what framework they're using (Next.js, Express, etc.).
2. Determine environment: local development or production deployment.
3. Walk through domain setup (Resend-managed or custom).
4. Set up webhook endpoint with signature verification.
5. If local dev: configure tunneling.
6. Implement security level — read references/security-levels.md and present options to the user.
7. Connect webhook to agent processing.

Output: A configured webhook handler file, environment variable checklist, and security configuration.

Architecture

Sender → Email → Resend (MX) → Webhook → Your Server → AI Agent
                                              ↓
                                    Security Validation
                                              ↓
                                    Process or Reject

Before You Start: Account & API Key Setup

Ask the user:

• New account just for the agent? → Simpler setup, full account access is fine
• Existing account with other projects? → Use domain-scoped API keys to limit what the agent can access. Even if the key leaks, it can only send from one domain.

Don't paste API keys in chat! They'll persist in conversation history. Have the user write directly to .env or use a secrets manager.

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.

Option 2: Custom Domain

The user enables receiving in the Resend dashboard, then adds an MX record:

Use a subdomain (e.g., agent.yourdomain.com) to avoid disrupting existing email services on your root domain — otherwise all email routes to Resend.

Webhook Setup

The user registers a webhook in Resend dashboard (Webhooks → Add Webhook → select email.received). They need the endpoint URL you'll create and the signing secret for verification.

// app/api/webhooks/email/route.ts (Next.js App Router)
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') {
      const { data: email } = await resend.emails.receiving.get(
        event.data.email_id
      );
      // Security validation happens here (see Security Levels)
      await processEmailForAgent(event.data, email);
    }

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

Resend retries failed deliveries with exponential backoff over ~6 hours. Emails are stored even if webhooks fail.

Local Development with Tunneling

Your local server isn't accessible from the internet. Use tunneling to expose it:

For webhooks, persistent URLs matter — otherwise you re-register the URL every time the tunnel restarts. See the tunneling docs for each tool for setup instructions.

# ngrok (paid - recommended for persistent dev)
ngrok http --domain=myagent.ngrok.io 3000

# Cloudflare named tunnel (free but more setup)
cloudflared tunnel run my-agent-webhook

Production Deployment

For a reliable agent inbox, deploy to production rather than relying on tunnels:

• Serverless (Vercel, Netlify, Cloudflare Workers) — zero server management, automatic HTTPS
• VPS/cloud — webhook handler runs alongside your agent, use nginx/caddy for HTTPS
• Existing infrastructure — add webhook route to your agent's existing web server

Security Levels

This is the most critical part of the setup. An AI agent that processes emails without security is dangerous.

There are 5 graduated security levels. Read references/security-levels.md for complete code examples and implementation details. Present the options to the user and help them choose:

Levels can be combined (e.g., Domain Allowlist + Content Filtering).

Security Best Practices

What to Avoid

Agent Integration

Connect your webhook to your AI agent:

async function processWithAgent(email: ProcessedEmail) {
  const message = `New Email\nFrom: ${email.from}\nSubject: ${email.subject}\n\n${email.body}`.trim();
  await sendToAgent(message);
}

Alternatively, the agent can poll the Resend API during heartbeats instead of using webhooks — simpler architecture but less immediate.

Complete Example

See references/security-levels.md for the complete secure agent inbox implementation with configurable security levels, rate limiting, content truncation, and rejection logging.

Environment Variables

RESEND_API_KEY=re_xxxxxxxxx
RESEND_WEBHOOK_SECRET=whsec_xxxxxxxxx
SECURITY_LEVEL=strict                    # strict | domain | filtered | sandboxed
[email protected],[email protected]
ALLOWED_DOMAINS=yourcompany.com
[email protected]             # For security notifications

Common Mistakes

Testing

• [email protected] — simulates successful delivery
• [email protected] — simulates hard bounce
• Send from non-allowlisted addresses to verify rejection works

Related Skills

• send-email — sending emails from your agent
• resend-inbound — detailed inbound email processing (domain setup, content retrieval, attachments)