useSend MCP Server

An MCP (Model Context Protocol) server that enables LLMs to interact with the useSend email platform. Provides comprehensive tools for sending emails, managing contacts, running campaigns, and configuring domains.

Features

• Email Operations: Send single or batch emails, list and retrieve emails, cancel or reschedule scheduled emails
• Contact Book Management: Create, update, and manage contact books
• Contact Management: Full CRUD operations for contacts within contact books
• Campaign Management: Create, schedule, pause, and resume email campaigns
• Domain Configuration: List, create, verify, and manage sending domains

Quick Start

Install from npm

npm install -g usesend-mcp-server

Or clone and build

git clone https://github.com/flyingwebie/usesend-mcp-server.git
cd usesend-mcp-server
npm install
npm run build

Get Your API Key

Get your API key from the useSend dashboard. Keys start with us_.

IDE Integration Guides

Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "usesend": {
      "command": "npx",
      "args": ["-y", "usesend-mcp-server"],
      "env": {
        "USESEND_BASE_URL": "https://app.usesend.com/api/",
        "USESEND_API_KEY": "us_your_api_key_here",
        "USESEND_DEFAULT_FROM": "[email protected]"
      }
    }
  }
}

Or if installed locally:

{
  "mcpServers": {
    "usesend": {
      "command": "node",
      "args": ["/path/to/usesend-mcp-server/dist/index.js"],
      "env": {
        "USESEND_BASE_URL": "https://app.usesend.com/api/",
        "USESEND_API_KEY": "us_your_api_key_here",
        "USESEND_DEFAULT_FROM": "[email protected]"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "usesend": {
      "command": "npx",
      "args": ["-y", "usesend-mcp-server"],
      "env": {
        "USESEND_BASE_URL": "https://app.usesend.com/api/",
        "USESEND_API_KEY": "us_your_api_key_here",
        "USESEND_DEFAULT_FROM": "[email protected]"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "usesend": {
      "command": "npx",
      "args": ["-y", "usesend-mcp-server"],
      "env": {
        "USESEND_BASE_URL": "https://app.usesend.com/api/",
        "USESEND_API_KEY": "us_your_api_key_here",
        "USESEND_DEFAULT_FROM": "[email protected]"
      }
    }
  }
}

Or configure globally in Cursor Settings > MCP Servers.

VS Code with Cline Extension

Add to your VS Code settings.json:

{
  "cline.mcpServers": {
    "usesend": {
      "command": "npx",
      "args": ["-y", "usesend-mcp-server"],
      "env": {
        "USESEND_BASE_URL": "https://app.usesend.com/api/",
        "USESEND_API_KEY": "us_your_api_key_here",
        "USESEND_DEFAULT_FROM": "[email protected]"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "usesend": {
      "command": "npx",
      "args": ["-y", "usesend-mcp-server"],
      "env": {
        "USESEND_BASE_URL": "https://app.usesend.com/api/",
        "USESEND_API_KEY": "us_your_api_key_here",
        "USESEND_DEFAULT_FROM": "[email protected]"
      }
    }
  }
}

OpenAI Codex CLI

Set environment variables before running:

export USESEND_API_KEY="us_your_api_key_here"
export USESEND_BASE_URL= "https://app.usesend.com/api/"
export USESEND_DEFAULT_FROM= "[email protected]"
npx usesend-mcp-server

MCP Inspector (Testing)

USESEND_API_KEY=us_your_api_key USESEND_BASE_URL= "https://app.usesend.com/api/" USESEND_DEFAULT_FROM= "[email protected]" npx @modelcontextprotocol/inspector npx usesend-mcp-server

Example Prompts

Once configured, you can use natural language to interact with useSend:

Sending Emails

"Send an email to [email protected] with subject 'Meeting Tomorrow' and let them know the meeting is at 3pm"

"Send a batch of welcome emails to these addresses: [email protected], [email protected]"

Managing Contact Books

"List all my contact books"

"Create a new contact book called 'VIP Customers' with a star emoji"

"How many contacts are in my Newsletter Subscribers book?"

Managing Contacts

"List all contacts in my newsletter contact book"

"Add a new contact [email protected] with name Jane Smith to the marketing list"

"Update the contact [email protected] to set their company as Acme Inc"

Campaign Operations

"Create a new campaign called 'Summer Sale' with subject 'Big Discounts Inside'"

"Schedule the Summer Sale campaign to send tomorrow at 9am"

"Pause the active newsletter campaign"

"Show me the metrics for my last campaign"

Domain Management

"List all my verified sending domains"

"Add a new domain notifications.mycompany.com"

"Check the DNS verification status for mycompany.com"

"What DNS records do I need to add for my new domain?"

Available Tools

Email Tools (6)

| Tool | Description | | ------------------------------- | ----------------------------------------------- | | usesend_send_email | Send a single transactional email | | usesend_list_emails | List emails with filtering and pagination | | usesend_get_email | Get detailed information about a specific email | | usesend_batch_send_emails | Send up to 100 emails in one request | | usesend_cancel_email | Cancel a scheduled email | | usesend_update_email_schedule | Update the scheduled time for an email |

Contact Book Tools (5)

| Tool | Description | | ----------------------------- | ------------------------------ | | usesend_list_contact_books | List all contact books | | usesend_get_contact_book | Get contact book details | | usesend_create_contact_book | Create a new contact book | | usesend_update_contact_book | Update contact book properties | | usesend_delete_contact_book | Delete a contact book |

Contact Tools (6)

| Tool | Description | | ------------------------ | ------------------------------- | | usesend_list_contacts | List contacts in a contact book | | usesend_get_contact | Get a specific contact by ID | | usesend_create_contact | Create a new contact | | usesend_update_contact | Update an existing contact | | usesend_upsert_contact | Create or update a contact | | usesend_delete_contact | Delete a contact |

Campaign Tools (5)

| Tool | Description | | --------------------------- | -------------------------------- | | usesend_create_campaign | Create a new email campaign | | usesend_get_campaign | Get campaign details and metrics | | usesend_schedule_campaign | Schedule a campaign for sending | | usesend_pause_campaign | Pause an active campaign | | usesend_resume_campaign | Resume a paused campaign |

Domain Tools (5)

| Tool | Description | | ----------------------- | ----------------------------------- | | usesend_list_domains | List all configured domains | | usesend_get_domain | Get domain details with DNS records | | usesend_create_domain | Register a new sending domain | | usesend_verify_domain | Verify domain ownership | | usesend_delete_domain | Delete a domain |

Configuration

| Variable | Required | Description | | ---------------------- | -------- | ------------------------------------------------------- | | USESEND_API_KEY | Yes | Your useSend API key (starts with us_) | | USESEND_BASE_URL | No | Custom API URL (default: https://app.usesend.com/api) | | USESEND_DEFAULT_FROM | No | Default sender email address for sending emails |

Default Sender Address

Setting USESEND_DEFAULT_FROM allows you to send emails without specifying the from address each time. This is useful when you always send from the same address.

# Example: Set default sender
export USESEND_DEFAULT_FROM="[email protected]"

With this set, you can simply say:

"Send an email to [email protected] with subject 'Hello'"

Instead of:

"Send an email from [email protected] to [email protected] with subject 'Hello'"

Tool Parameters

Response Format

Most read operations support a response_format parameter:

• markdown (default): Human-readable formatted output
• json: Raw JSON for programmatic processing

Pagination

List operations support:

• page: Page number (default: 1)
• limit: Results per page (default: 50, max: 100)

API Examples

Send an Email

Tool: usesend_send_email
Parameters:
  to: "[email protected]"
  from: "[email protected]"
  subject: "Hello from useSend"
  html: "<h1>Welcome!</h1><p>This is a test email.</p>"
  text: "Welcome! This is a test email."

Create a Contact

Tool: usesend_create_contact
Parameters:
  contactBookId: "cb_123456"
  email: "[email protected]"
  firstName: "John"
  lastName: "Doe"
  properties: {"company": "Acme Inc", "role": "Developer"}

Schedule a Campaign

Tool: usesend_schedule_campaign
Parameters:
  campaignId: "cmp_123456"
  scheduledAt: "2024-01-15T09:00:00Z"
  batchSize: 1000

Check Domain Status

Tool: usesend_get_domain
Parameters:
  domainId: 123
  response_format: "markdown"

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Type check
npm run typecheck

# Test with MCP Inspector
USESEND_API_KEY=us_test npx @modelcontextprotocol/inspector node dist/index.js

Project Structure

usesend-mcp-server/
├── src/
│   ├── index.ts              # Server entry point
│   ├── constants.ts          # Configuration and enums
│   ├── types.ts              # TypeScript interfaces
│   ├── client/
│   │   └── usesend-client.ts # API client with auth
│   ├── tools/
│   │   ├── index.ts          # Tool registration
│   │   ├── emails.ts         # Email tools
│   │   ├── contactBooks.ts   # Contact book tools
│   │   ├── contacts.ts       # Contact tools
│   │   ├── campaigns.ts      # Campaign tools
│   │   └── domains.ts        # Domain tools
│   ├── schemas/
│   │   ├── emails.ts         # Email Zod schemas
│   │   ├── contactBooks.ts   # Contact book Zod schemas
│   │   ├── contacts.ts       # Contact Zod schemas
│   │   ├── campaigns.ts      # Campaign Zod schemas
│   │   └── domains.ts        # Domain Zod schemas
│   └── utils/
│       ├── error-handler.ts  # Error handling
│       └── formatters.ts     # Response formatting
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Error Handling

The server provides actionable error messages for common issues:

| Code | Description | Solution | | ---- | -------------------- | -------------------------- | | 401 | Invalid API key | Check USESEND_API_KEY | | 403 | Permission denied | Verify API key permissions | | 404 | Resource not found | Check the resource ID | | 409 | Idempotency conflict | Use a different key | | 429 | Rate limit exceeded | Wait and retry |

License

MIT