mcpengine/servers/sendgrid/README.md

# SendGrid MCP Server

Complete MCP server for SendGrid email platform. Send transactional emails, manage contacts and lists, create marketing campaigns, and monitor email performance — all via AI.

## Features

- 📧 **Transactional Email** - Send single/bulk emails with templates, attachments, scheduling
- 📋 **Templates** - Create, manage, and deploy dynamic email templates
- 👥 **Contacts** - Full contact lifecycle management with custom fields
- 📜 **Lists & Segments** - Static lists and dynamic audience segmentation
- 📣 **Campaigns** - Marketing campaign creation and management
- 📊 **Statistics** - Comprehensive email analytics and deliverability metrics
- 🚫 **Suppressions** - Bounce, spam report, and unsubscribe management
- 👤 **Senders** - Verified sender identity management

## Installation

```bash
npm install
npm run build
```

## Environment Variables

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `SENDGRID_API_KEY` | ✅ | SendGrid API key with full permissions | `SG.abc123...` |

## Getting Your API Key

1. Log in to SendGrid: https://app.sendgrid.com/
2. Navigate to **Settings > API Keys**
3. Click **Create API Key**
4. Select **Full Access** or grant specific permissions:
   - Mail Send (for transactional emails)
   - Marketing Campaigns (for campaigns, lists, contacts, segments)
   - Template Engine (for templates)
   - Suppressions (for bounce/spam management)
5. Copy the API key and set environment variable:

```bash
export SENDGRID_API_KEY='your_key_here'
```

## Required API Scopes

- **Mail Send** - Send transactional emails
- **Marketing Campaigns** - Manage campaigns, lists, contacts, segments
- **Template Engine** - Create and manage templates
- **Suppressions** - View/manage bounces, spam reports, unsubscribes
- **Sender Identities** - Manage verified senders

## Usage

### Stdio Mode (Default)

```bash
npm start
# or
node dist/main.js
```

### With MCP Client

Add to your MCP settings:

```json
{
  "mcpServers": {
    "sendgrid": {
      "command": "node",
      "args": ["/path/to/servers/sendgrid/dist/main.js"],
      "env": {
        "SENDGRID_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools (21)

### Messages (2)
- `sendgrid_send_email` - Send transactional email with full customization
- `sendgrid_send_template_email` - Send email using dynamic template

### Contacts (5)
- `sendgrid_list_contacts` - List contacts with pagination (50 per page)
- `sendgrid_get_contact` - Get contact details by ID
- `sendgrid_create_contact` - Create/update contacts (upsert)
- `sendgrid_update_contact` - Update existing contact
- `sendgrid_delete_contact` - Delete contact permanently

### Lists (4)
- `sendgrid_list_lists` - List all contact lists
- `sendgrid_create_list` - Create new list
- `sendgrid_add_contacts_to_list` - Add contacts to list
- `sendgrid_delete_list` - Delete list (contacts remain)

### Templates (4)
- `sendgrid_list_templates` - List all templates
- `sendgrid_get_template` - Get template details
- `sendgrid_create_template` - Create new template
- `sendgrid_delete_template` - Delete template

### Campaigns (5)
- `sendgrid_list_campaigns` - List campaigns with pagination
- `sendgrid_get_campaign` - Get campaign details
- `sendgrid_create_campaign` - Create marketing campaign
- `sendgrid_get_campaign_stats` - Get campaign performance stats
- `sendgrid_delete_campaign` - Delete campaign

### Suppressions (4)
- `sendgrid_list_bounces` - List bounced emails
- `sendgrid_delete_bounce` - Remove email from bounce list
- `sendgrid_list_spam_reports` - List spam complaints
- `sendgrid_add_suppression` - Add email to suppression list

### Senders (4)
- `sendgrid_list_senders` - List verified sender identities
- `sendgrid_get_sender` - Get sender details
- `sendgrid_create_sender` - Create sender identity
- `sendgrid_delete_sender` - Delete sender identity

### Stats (1)
- `sendgrid_get_email_stats` - Get email statistics by date range

## Coverage Manifest

**Total SendGrid API endpoints:** ~80 (Mail Send, Marketing Campaigns, Contacts, Templates, Stats)  
**Tools implemented:** 21  
**Coverage:** ~26%

### Intentionally Skipped:
- **Subusers** - Multi-account management (enterprise feature)
- **IP Management** - Dedicated IP pools (enterprise feature)
- **Webhooks** - Event notification setup (better managed via UI)
- **API Keys Management** - Key CRUD (security-sensitive, UI-preferred)
- **Advanced Segmentation** - Complex query builder (better via UI)
- **A/B Testing** - Campaign variants (better managed via UI)
- **Custom Fields** - Field definitions (one-time setup via UI)

Focus is on high-value operations: sending emails, managing contacts/lists, creating campaigns, and monitoring performance.

## Architecture

- **main.ts** - Entry point with env validation and graceful shutdown
- **server.ts** - MCP server class with lazy-loaded tool modules
- **tools/** - Domain-organized tool files (messages, contacts, lists, templates, campaigns, suppressions, senders, stats)
- **client/sendgrid-client.ts** - Axios-based API client with rate limiting

## License

MIT