# Twilio SendGrid MCP

> Twilio SendGrid MCP Server gives your AI agent direct API access to manage email campaigns, clean contact lists, and audit deliverability. Dispatch authenticated HTML emails, check suppression bounce records, or grow marketing directories using specific tools like `dispatch_email` and `create_marketing_contact`. It's full-cycle marketing automation right through the chat interface.

## Overview
- **Category:** talk-to-me
- **Price:** Free
- **Tags:** email-marketing, transactional-email, crm, bounce-management, template-management

## Description

Your AI agent gives you direct API access to manage every part of your email campaign lifecycle through Twilio SendGrid. You don't gotta export CSVs or stare at dashboards; your agent handles list hygiene, sending campaigns, and auditing bounces right from the chat interface. 

**Sending Campaigns**

You can run outbound HTML campaigns using `dispatch_email`. This tool sends authenticated emails via SendGrid’s SMTP relay straight to specified recipients. You dictate the message content and hit send; it queues up instantly for delivery.

**Auditing Delivery Status**

To check on failed deliveries, you'll run `list_bounces` to gather a complete list of every email address that bounced hard. If you know an address was wrongly suppressed, you use `delete_bounce` to remove it from the bounce suppression list after confirming it's active again. For compliance tracking, your agent can pull all records detailing emails reported as spam using `list_spam_reports`. You can also view every user who unsubscribed globally by calling `list_global_unsubscribes`, giving you a clear picture of your opted-out audience.

**Managing Contact Data**

When it comes to list hygiene, the agent lets you maintain your core directory using `list_marketing_contacts` to see every current subscriber record. Need to add someone new or update details? Use `create_marketing_contact`; this tool handles adding a new contact while making sure it merges data if that person already exists in your system. You can also pull a list of all segmented marketing groups you've set up by running `list_marketing_lists`.

**Inspecting Templates**

Before you fire off any major send, you need to check the template structure first. Your agent pulls every available dynamic transactional design stored in your account using `list_dynamic_templates`. Once you identify a specific ID, you use `get_template_details` to retrieve that exact template's structure and content details. This whole setup lets your AI client manage full-cycle marketing automation.

This server gives your agent the power to take action: **dispatching** emails with `dispatch_email`, cleaning up data with `delete_bounce`, growing lists with `create_marketing_contact`, viewing every detail with `get_template_details`, and pulling critical reports like bounce records using `list_bounces` or spam complaints via `list_spam_reports`.

## Tools

### create_marketing_contact
Adds a new contact to your marketing directory, merging data if the person already exists.

### delete_bounce
Removes a specific address from the bounce suppression list after validating it should be active again.

### delete_spam_report
Use with caution — sending to users who report spam can damage your sender reputation.

Remove an email from the spam report suppression list

### dispatch_email
Sends an authenticated outbound email campaign via SendGrid's SMTP relay to specified recipients.

### get_delivery_stats
Use YYYY-MM-DD format.

Get global email delivery statistics

### get_template_details
Retrieves the specific structure and content details for a single transaction template ID.

### list_blocked_emails
Different from bounces — blocks are typically temporary server-level rejections.

List all blocked email addresses

### list_bounces
Gathers a list of all email addresses that have recently failed delivery (hard bounces).

### list_dynamic_templates
Lists every available dynamic transactional template stored in your account.

### list_global_unsubscribes
Retrieves a full list of all users who have unsubscribed from marketing communications globally.

### list_marketing_contacts
Lists every current contact record in your primary marketing directory.

### list_marketing_lists
Retrieves a list of all segmented marketing contact groups you maintain.

### list_single_sends
List all marketing single-send campaigns

### list_spam_reports
Lists records detailing emails that have been reported as spam by users.

### list_verified_senders
Only verified senders can be used in the from_email field.

List all verified sender identities

### search_contact_by_email
Returns full contact profile including custom fields, lists, and segments.

Look up a marketing contact by email address

## Prompt Examples

**Prompt:** 
```
Using the SendGrid API, list emails that have bounced recently to audit our hygiene.
```

**Response:** 
```
I've invoked `list_bounces` spanning your latest transmissions. You have exactly 4 hard-bounced targets stored within suppression parameters. For instance, 'hello@fake-email-z.com' returned an error string: 550 Relay Denied. Do you want me to automatically execute the `delete_bounce` directive on any specific valid records to unblock them?
```

**Prompt:** 
```
Dispatch an HTML email from 'marketing@mybrand.com' to 'client@test.com' with subject 'Special Delivery'. Use standard <h1>.
```

**Response:** 
```
The transmission has been completed effectively. The `dispatch_email` tool received identical constraints, leveraging 'marketing@mybrand.com'. The SendGrid HTTP payload accepted your outbound message synchronously and queued it upon the global outgoing rail successfully.
```

**Prompt:** 
```
Audit the Dynamic Transactional Templates list. Summarize findings.
```

**Response:** 
```
I've engaged `list_dynamic_templates` surveying your internal dashboard environment. Your vault holds 7 different distinct design layouts. The most recently updated is the 'Welcome Onboarding Form' attached to template ID (d-f018x8axxx...). Would you like me to dive into `get_template_details` for that specific iteration to reverse-engineer its internal blocks?
```

## Capabilities

### Send authenticated emails
Use the `dispatch_email` tool to send outbound HTML campaigns from a verified sender address.

### Audit failed deliveries
Run `list_bounces` to view all bounced email records and use `delete_bounce` to remove specific addresses from the suppression list.

### Manage contact data
Use `create_marketing_contact` to add or update subscriber details, and `list_marketing_contacts` to view the entire directory.

### Inspect email templates
List all available transactional designs with `list_dynamic_templates`, then retrieve a specific template's structure using `get_template_details`.

## Use Cases

### Initial campaign send fails due to old addresses.
A large client needs to run a blast, but they suspect the list has junk data. They ask their agent: 'Audit our bounces and prep the list.' The agent runs `list_bounces`, finds 120 invalid records, prompts you for confirmation, and then executes `delete_bounce` on them before initiating the final `dispatch_email`.

### Building a new lead capture form.
A marketing team needs to integrate a sign-up widget. Instead of manual CSV imports, they ask their agent to run through the data flow: it uses `create_marketing_contact` for every submission and then runs `list_marketing_lists` to verify which segment the new contact belongs to.

### Debugging a template structure.
A developer is testing an HTML email layout. They first call `list_dynamic_templates` to see available designs, then use `get_template_details` on ID XYZ to verify that the `<h1 style='color:red'>` tags render correctly before sending a test via `dispatch_email`.

### Investigating list health after an outage.
The team notices delivery metrics dropped. They ask their agent to check for compliance issues, running both `list_spam_reports` and `list_global_unsubscribes`. The agent synthesizes the data, telling them if the drop was due to spam complaints or a mass opt-out.

## Benefits

- **Clean your list instantly.** Instead of manual auditing, use `list_bounces` to find dead addresses and then run `delete_bounce` on valid ones. This keeps your sender reputation healthy.
- **Automate contact growth.** Whenever a conversation generates an email address, the agent runs `create_marketing_contact`, ensuring every new lead is immediately added or updated in your CRM records.
- **Verify campaigns before sending.** Use `list_dynamic_templates` followed by `get_template_details`. You can check complex HTML structures against their rules without building a test email manually.
- **Know exactly who opted out.** The agent runs `list_global_unsubscribes`, giving you a single source of truth regarding compliance and unsubscribed users, preventing accidental sends.
- **Track deliverability issues.** Use `list_spam_reports` to see what complaints are coming in. This gives early warnings that your content or sender reputation is failing.

## How It Works

The bottom line is: Your AI client interacts with your SendGrid account using direct API calls, eliminating manual dashboard navigation for core marketing tasks.

1. Enable the SendGrid component in your client environment and supply an encrypted API Key with necessary permissions.
2. Ask your agent to perform a task (e.g., 'List all bounced emails').
3. The agent calls the specific tool (`list_bounces`), processes the data, and gives you actionable results or executes corrective actions.

## Frequently Asked Questions

**How do I check for bounce issues using list_bounces?**
Run `list_bounces`. The agent will show you a record of all failed emails, including the specific error code (e.g., 550 Relay Denied). From there, you can use `delete_bounce` if you confirm the address is valid.

**What's the difference between list_marketing_contacts and list_marketing_lists?**
The distinction is contacts vs. groups. `list_marketing_contacts` gives a raw list of every single person. `list_marketing_lists` shows you the segmented buckets (like 'Tier 1 Clients' or 'Q3 Leads') that contain those people.

**Can I use dispatch_email to send a test email?**
Yes, absolutely. You tell your agent to run `dispatch_email` with the target recipients and subject line. It sends the fully authenticated HTML email through SendGrid's relay.

**Do I need to worry about spam complaints? How does list_spam_reports help?**
Yes, you should check this regularly. Running `list_spam_reports` gives you a log of user-reported complaints. This is an early warning system that tells you when your content or sender reputation needs immediate attention.

**When sending an email with `dispatch_email`, what are the mandatory setup requirements?**
You must use a verified sender email in the "from_email" field. This step is required for deliverability and prevents emails from being flagged as spam, so always ensure your credentials are pre-verified.

**If I run `create_marketing_contact` multiple times with the same user data, what happens?**
The tool merges existing data if the contact ID already exists. It updates relevant fields rather than creating duplicate records, which keeps your marketing list clean and accurate.

**Before running `delete_bounce`, what should I know about suppressing records?**
Be careful; this action is destructive because it permanently removes the suppression record. Only use `delete_bounce` when you are absolutely certain a specific address needs to be unblocked from spam filters.

**What information does `get_template_details` provide about a template's internal code?**
It retrieves granular details, including the full structure and blocks of the chosen template. This lets you inspect the exact HTML markup before deciding to run an outbound campaign.

**Can the agent automatically send emails on my behalf?**
Yes. The integration natively wraps the `dispatch_email` mutation tool. If adequately prompted, the system will formulate HTML payloads and broadcast them assuming you explicitly provide the verified Sender Identity (from_email) corresponding to your account.

**How do I remove an email block suppressing one of my clients?**
You don't need to manually interact with the web app anymore. Dictate to the LLM: 'Unblock client@gmail.com from my bounce list'. The agent will instantly leverage `delete_bounce` removing the suspension logic behind the scenes.

**Can I query spam complaints regarding my outgoing templates?**
Absolutely. Utilize the command prompt sequence to call `list_spam_reports`. It retrieves detailed events pointing precisely to domains triggering those complaints, empowering you to adjust or purge bad contacts dynamically.