Use these tools to manage email contacts, segments, and send emails via Resend.

WORKFLOW:
1. find_contacts or segments(list) → discover existing data
2. upsert_contacts → add/update subscribers
3. send → individual email or broadcast to segment
4. campaigns(status) → track delivery

FORMATTING (for body):
- Use \n\n between paragraphs
- Use \n between list items
- Plain text is auto-converted to multipart (HTML + text) for proper rendering

IMPORTANT:
- Segment names are case-insensitive
- Templates must be published in Resend dashboard to use
- Broadcasts use segment name, not ID

cd resend-mcp
bun install
cp env.example .env

PORT=3000
AUTH_ENABLED=true
AUTH_STRATEGY=bearer

# Generate with: openssl rand -hex 32
BEARER_TOKEN=your-random-auth-token

# Resend credentials
RESEND_API_KEY=re_your_resend_api_key
RESEND_DEFAULT_FROM=newsletter@yourdomain.com

bun dev
# MCP: http://127.0.0.1:3000/mcp

{
  "mcpServers": {
    "resend": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp", "--transport", "http-only"],
      "env": { "NO_PROXY": "127.0.0.1,localhost" }
    }
  }
}

// Input
{
  contacts: [
    { email: "john@example.com", first_name: "John", last_name: "Doe" },
    { email: "jane@example.com", properties: { plan: "pro", company: "Acme" } }
  ],
  segments?: ["Newsletter", "Premium"],  // Add to these segments
  unsubscribed?: false                   // Set subscription status
}

// Output
{
  results: [{ email, ok, id, action: "created" | "updated", error? }],
  summary: { created: 1, updated: 1, failed: 0 }
}

// Input
{ emails: ["user@example.com", "other@example.com"] }

// Output
{ results: [{ email, ok, error? }], summary: { deleted: 2, failed: 0 } }

// Input
{
  segment?: "Newsletter",      // Filter by segment name
  email?: "user@example.com",  // Find specific contact
  unsubscribed?: false,        // Filter by status
  limit?: 50,                  // Max 100
  cursor?: "..."               // From previous response
}

// Output
{
  items: [{ id, email, first_name, last_name, unsubscribed, created_at, properties }],
  has_more: boolean,
  cursor?: string
}

// List all segments
{ action: "list" }
→ { items: [{ id, name, contact_count, created_at }] }

// Create segment
{ action: "create", name: "VIP Customers" }
→ { id, name, ok: true }

// Delete segment (contacts remain in system)
{ action: "delete", name: "Old Segment" }

// Add contacts to segment
{ action: "add_contacts", name: "Newsletter", contacts: ["a@x.com", "b@x.com"] }

// Remove contacts from segment
{ action: "remove_contacts", name: "Newsletter", contacts: ["a@x.com"] }

// Individual email
{
  to: "user@example.com",        // or array up to 50
  subject: "Welcome!",
  body: "Hello {{{FIRST_NAME}}}!\n\nWelcome to our newsletter.",
  from_name?: "Alice Newsletter",
  reply_to?: "support@example.com",
  schedule_for?: "2024-12-25T10:00:00Z"
}

// Broadcast to segment
{
  segment: "Newsletter",         // Segment name (case-insensitive)
  subject: "Weekly Update",
  name?: "Week 42 Newsletter",   // Dashboard display name
  body: "HEADLINE\n\nFirst paragraph.\n\nSecond paragraph.",
  schedule_for?: "in 2 hours"    // Natural language supported
}

// Using template
{
  to: "user@example.com",
  template: "welcome-email",     // Template alias or ID
  variables: { CTA_TEXT: "Get Started", DISCOUNT: "20%" }
}

// List recent campaigns
{ action: "list", limit?: 20 }
→ { items: [{ id, name, subject, segment_name, status, sent_at, recipients_count }] }

// Get detailed status
{ action: "status", campaign_id: "bc123..." }
→ { id, status, sent_count, delivered_count, opened_count, failed_count }

// Cancel scheduled campaign
{ action: "cancel", campaign_id: "bc123..." }
→ { id, cancelled: true }

// Subscribe to topic
{ emails: "user@example.com", action: "subscribe", topic: "Product Updates" }

// Unsubscribe from topic
{ emails: ["a@x.com", "b@x.com"], action: "unsubscribe", topic: "Newsletter" }

// Global unsubscribe (from all emails)
{ emails: "user@example.com", action: "unsubscribe_all" }

// Input
{ limit?: 50, cursor?: "..." }

// Output
{
  items: [{ id, alias, name, subject, from, variables: [{ key, type, fallback }] }],
  has_more: boolean
}

// Add contacts to Newsletter segment
{
  "name": "upsert_contacts",
  "arguments": {
    "contacts": [
      { "email": "alice@example.com", "first_name": "Alice" },
      { "email": "bob@example.com", "first_name": "Bob" }
    ],
    "segments": ["Newsletter"]
  }
}

Added 2 contact(s). Created: 2, Updated: 0, Failed: 0.
Next: Use 'find_contacts' to verify or 'send' to email them.

{
  "name": "send",
  "arguments": {
    "segment": "Newsletter",
    "subject": "This Week in AI",
    "name": "Week 42 Newsletter",
    "body": "HIGHLIGHTS\n\nClaude 4 was released this week with impressive new capabilities.\n\nKEY FEATURES\n\n• Extended context window\n• Improved reasoning\n• Better code generation\n\nREAD MORE\n\nCheck out the full announcement on our blog."
  }
}

Broadcast to segment "Newsletter" queued for sending (Campaign ID: abc123).
Use 'campaigns' tool to track delivery.

{
  "name": "campaigns",
  "arguments": { "action": "status", "campaign_id": "abc123" }
}

Campaign abc123: sent
- Sent: 1,234
- Delivered: 1,198
- Opened: 456 (38%)
- Failed: 36

{
  "name": "subscriptions",
  "arguments": {
    "emails": "unhappy@example.com",
    "action": "unsubscribe_all"
  }
}

Updated 1 contact(s). Success: 1, Failed: 0.

┌─────────────────────────────────────────────────────────────────┐
│  Client (Alice App, Claude Desktop)                             │
│      │                                                          │
│      │ Authorization: Bearer <BEARER_TOKEN>                     │
│      ▼                                                          │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  MCP Server (Node.js / Cloudflare Worker)                   ││
│  │                                                             ││
│  │  1. Validate BEARER_TOKEN (client auth)                     ││
│  │  2. Use RESEND_API_KEY internally                           ││
│  │                                                             ││
│  │  RESEND_API_KEY ──────────► Resend API                      ││
│  │  RESEND_DEFAULT_FROM ─────► (api.resend.com)                ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

bun dev
# Endpoint: http://127.0.0.1:3000/mcp

# Create .dev.vars with secrets
echo "BEARER_TOKEN=your_token" >> .dev.vars
echo "RESEND_API_KEY=re_xxx" >> .dev.vars
echo "RESEND_DEFAULT_FROM=newsletter@yourdomain.com" >> .dev.vars

bun x wrangler dev --local | cat
# Endpoint: http://127.0.0.1:8787/mcp

# Set secrets
bun x wrangler secret put BEARER_TOKEN
bun x wrangler secret put RESEND_API_KEY
bun x wrangler secret put RESEND_DEFAULT_FROM

# Deploy
bun x wrangler deploy
# Endpoint: https://<worker>.<account>.workers.dev/mcp

src/
├── index.ts                    # Node.js entry point
├── worker.ts                   # Cloudflare Workers entry point
├── config/
│   ├── env.ts                  # Environment parsing
│   └── metadata.ts             # Server & tool descriptions
├── core/
│   └── mcp.ts                  # McpServer builder
├── shared/
│   └── tools/
│       └── resend/             # Tool definitions
│           ├── upsert-contacts.ts
│           ├── remove-contacts.ts
│           ├── find-contacts.ts
│           ├── segments.ts
│           ├── send.ts
│           ├── campaigns.ts
│           ├── subscriptions.ts
│           └── templates.ts
├── services/
│   └── resend/
│       └── client.ts           # Resend API client
├── schemas/
│   └── outputs.ts              # Zod output schemas
└── http/
    ├── app.ts                  # Hono HTTP app
    └── routes/
        └── mcp.ts              # MCP endpoint handler

bun dev           # Start with hot reload (note: sessions clear on reload)
bun start         # Production mode (stable sessions)
bun run typecheck # TypeScript check
bun run lint      # Lint code
bun run build     # Production build

bunx @modelcontextprotocol/inspector
# Connect to: http://localhost:3000/mcp
# Add header: Authorization: Bearer <your-BEARER_TOKEN>