agent-email-inbox

Files (2)

• SKILL.md
• security-levels.md · references/

SKILL.md (first lines)

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

| Setting | Value |
|---------|-------|
| **Type** | MX |
| **Host** | Your domain or subdomain (e.g., `agent.yourdomain.com`) |
| **Value** | Provided in Resend dashboard |
| **Priority** | 10 (lowest number takes precedence) |

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

```typescript
// 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:

| Option | Persistent URL? | Cost |
|--------|----------------|------|
| **ngrok (paid)** | Yes (static subdomain) | $8/mo |
| **Cloudflare named tunnel** | Yes (your own domain) | Free |
| **ngrok (free)** | No (changes on restart) | Free |
| **VS Code Port Forwarding** | No (changes per session) | Free |

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.

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

From MoizIbnYousaf/marketing-cli, MIT.

More from MoizIbnYousaf/marketing-cli