# SparkPost MCP

> SparkPost MCP Server gives your AI client native access to your email platform. You can manage templates, send campaigns, and audit deliverability directly from your code editor. Instead of logging into the Web UI repeatedly, you use tools like `create_template` or `get_deliverability_metrics` to run complex operations—from sending test emails via `send_email` to parsing old HTML layouts.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** email-delivery, smtp-api, inbox-placement, email-templates, transactional-email, deliverability

## Description

You've got native access to your SparkPost account right in your AI client. This server gives you all the tools needed to manage email campaigns and check deliverability metrics without ever leaving your code editor. Forget logging into the Web UI or running manual API calls—your agent handles complex operations directly.

When you write code, you're not just using a generic messaging tool; you're talking directly to your live email platform. You can run everything from sending simple test emails right up through parsing and registering massive HTML layouts.

**Sending Emails:** To send a plain text message, use `send_email`. Just give it the recipients, the subject line, and the body content, and you're good to go. This is perfect for quick transactional tests or confirming that your system is working with defined 'from' addresses.

**Managing Templates:** Building out campaign layouts is simple. Start by listing everything available in the account using `list_templates`; this gives you a full roster of every draft and published template. Need to know what a specific template looks like? Grab its details with `get_template_details`. If you're writing something new, use `create_template` to register it; you just need to provide the unique ID, the display name, the subject line, and the valid HTML content. Remember, if you mess up a template, you can wipe it out permanently using `delete_template`, but be careful—that action is irreversible.

**Monitoring Deliverability:** You gotta know if your emails are landing in the inbox or the spam folder. To get a full picture of account health, pull all current performance numbers with `get_deliverability_metrics`. If you need to dig into why things failed, run `list_bounce_events` to see a list of recent failures and figure out exactly what went wrong with delivery. You can also check your setup by running `list_webhooks`, which shows every active event webhook configured on the SparkPost instance.

**Handling Compliance & Lists:** Managing who gets spammed is crucial, so you need access to the compliance lists. To see who opted out of emails, use `list_suppression_list`; this gives you a list of all addresses currently blocked due to spam complaints or unsubscribes. If you know an address was wrongly added to that block, you can permanently remove it from the global suppression list using `delete_suppression_record`. This action is serious; once you delete that record, it's gone for good.

This setup means your AI client understands the entire context of your Email API. You don't have to juggle multiple interfaces or write boilerplate code just to test a subject line or check an opt-out status. You can give commands or write logic that directly affects your live campaigns, making testing and deployment faster than ever.

## Tools

### create_template
Registers a new email template with a unique ID, display name, subject, and valid HTML content.

### delete_suppression_record
Permanently removes one specific email address from the global suppression list. This action cannot be undone.

### delete_template
Deletes an existing email template permanently. Use this with caution, as the action is irreversible.

### get_deliverability_metrics
Pulls all current account-wide performance metrics related to email delivery and overall health.

### get_template_details
Retrieves the full structure, content, and metadata for a specific existing template ID.

### list_bounce_events
Lists recent email bounce events, allowing you to see exactly why messages failed delivery.

### list_suppression_list
Retrieves a list of all addresses currently blocked due to spam complaints or unsubscribes.

### list_templates
Returns a full listing of every draft and published email template available in the account.

### list_webhooks
Lists all active event webhooks configured on your SparkPost instance.

### send_email
Sends a plain text email to specified recipients using the 'from' address, subject, and body content.

## Prompt Examples

**Prompt:** 
```
Check SparkPost metrics and tell me how our overall deliverability looked for the recent period.
```

**Response:** 
```
I've pulled stats via `get_deliverability_metrics`. Your account is looking healthy:
**Total Accepted**: 42,150
**Total Bounced**: 204
**Total Deferred**: 18
**Rejection Rate**: 0.48%

Your bounce rate falls well below the standard 2% danger threshold. Would you like a deeper dump of your `list_bounce_events` nonetheless?
```

**Prompt:** 
```
Create a new HTML template titled 'Holiday Promo' using ID 'promo_2025' that features a large header table.
```

**Response:** 
```
I generated a responsive HTML snippet utilizing properly structured centered table bodies. Then, I invoked `create_template` mapping attributes ID `promo_2025` with Name `Holiday Promo` successfully. 

**Result:** The template is now published in your SparkPost account and available for trigger operations immediately.
```

**Prompt:** 
```
Send a plain text email to compliance@domain.com saying 'Your account review is ready for audit'.
```

**Response:** 
```
I've invoked `send_email` dynamically setting the headers appropriately to send textual metadata.

**Transmission Result**: SUCCEEDED ✅
Recipient: compliance@domain.com
Subject: Account Review

SparkPost acknowledged the request and the payload is now actively pushing to ISP delivery paths.
```

## Capabilities

### Send Emails
Run `send_email` to send a plain text email using simple prompts and defined recipients.

### Manage Templates
Use `create_template`, `get_template_details`, or `list_templates` to build, read, and manage your HTML campaign layouts.

### Monitor Deliverability
Execute `get_deliverability_metrics` to pull account-wide performance data, or use `list_bounce_events` for a list of recent failures.

### Handle Compliance Lists
Access who unsubscribed using `list_suppression_list`, and remove addresses from the block via `delete_suppression_record`.

## Use Cases

### Fixing a sudden bounce spike
A postmaster notices an unusual drop in delivery performance. They ask their agent to run `get_deliverability_metrics` first, which confirms the issue is high bounces. The agent then uses `list_bounce_events` to filter and categorize the failures by error code, identifying a pattern of hard bounces from a specific domain.

### Creating a new promotional newsletter
A marketing engineer needs a holiday template. They ask their agent to generate the HTML content for 'Holiday Sale' and then run `create_template` with the required ID, name, and subject. The agent publishes the template instantly for use in campaigns.

### Debugging a signup form email
A developer builds a new user onboarding flow. They ask their agent to run `send_email` with placeholder content. This immediately tests the full send path, confirming that the correct headers and plain text body reach the target inbox without needing an external testing tool.

### Cleaning up old templates
A marketing team finds dozens of unused HTML files. They ask their agent to run `list_templates` for a comprehensive inventory, then systematically use `get_template_details` on the older ones and confirm if they can safely delete them using `delete_template`.

## Benefits

- Audit campaign health instantly. Instead of downloading a CSV report, run `get_deliverability_metrics` through your agent to get real-time KPI data right in your chat window. You see accepted counts, bounce totals, and rejection rates without leaving your IDE.
- Build complex templates with ease. Use the LLM to generate HTML for new campaigns, then invoke `create_template`, mapping the ID, name, subject, and raw content into SparkPost automatically.
- Stop manually checking lists. Run `list_suppression_list` to see exactly who unsubscribed or hit spam. You can even use `delete_suppression_record` if you need to unblock a specific user address.
- Test sends without friction. Use `send_email` to fire off test transactions instantly via natural prompts, perfect for verifying forms or new signup flows before going live.
- Troubleshoot failures systematically. If your open rate drops, run `list_bounce_events`. Your agent can then filter that list data and tell you if the issue is IP-based or content-related.

## How It Works

The bottom line is, your agent treats the entire SparkPost platform like a native library, allowing complex operations without needing to jump through multiple vendor UIs.

1. Subscribe to this AI integration server on Vinkius.
2. Provide your SparkPost API Key in the connection settings.
3. Query your language model with specific instructions about which mailing webhooks you need data from.

## Frequently Asked Questions

**How do I check my email deliverability using get_deliverability_metrics?**
Your agent runs `get_deliverability_metrics` to pull all current performance data. The result shows accepted counts, bounce totals, and rejection rates instantly, allowing you to judge overall campaign health.

**Can I use create_template to update an existing template?**
No. `create_template` registers a new layout with unique attributes. If you need to modify an old one, first run `get_template_details` to retrieve the current content, then use your agent's capabilities to write the updated HTML before re-running `create_template`.

**What is the difference between list_bounce_events and get_deliverability_metrics?**
`get_deliverability_metrics` gives you high-level KPI summaries (totals). `list_bounce_events` provides a granular, chronological feed of every specific bounce incident that occurred.

**How do I send a test email using the send_email tool?**
You simply prompt your agent to 'send a plain text email' and provide the recipient address. The agent executes `send_email`, which sends the message instantly via SparkPost transmissions.

**What happens if my SparkPost API Key changes or expires while I'm using tools like `send_email`?**
You must provide your current, active API key in the client configuration. If the key fails authentication, the tool will return an explicit HTTP 401 Unauthorized error code. Always verify credentials before running any live transmissions.

**I need to remove a user from the suppression list; what is the risk of using `delete_suppression_record`?**
This action is irreversible, so proceed with caution. Running `delete_suppression_record` removes an address permanently from SparkPost's global blocklist. Only do this if you are certain the user was incorrectly filtered.

**How does using `list_webhooks` help me debug my email sending setup?**
`list_webhooks` shows every active event listener configured for your account. This lets you check which endpoints receive data when an event (like a bounce or open) occurs, helping pinpoint broken connections.

**If I want to audit all my existing email layouts, should I use `list_templates` or `get_template_details`?**
`list_templates` gives you an overview of every template (published or draft) with basic metadata. Use `get_template_details` when you need the full HTML content and structure for one specific template ID.

**Can the AI rewrite an old HTML email template and import it straight into SparkPost?**
Yes! The bot reads your existing content using `get_template_details`, uses its intelligence to fully redesign the HTML block recursively (e.g. updating tables to modern styling natively), and finally invokes `create_template` to overwrite or deploy the modernized file safely to the cloud.

**How easy is it to send a test email from the IDE without a UI interface?**
It takes one sentence. You can type: 'Send via SparkPost a test email to admin@test.com titled Server OK'. The LLM gathers the keys, utilizes `send_email`, structures the JSON transmission array natively, and confirms back to you upon a 2xx HTTP delivery success.

**Can it search for specifically why emails are bouncing from a certain provider?**
Yes. While the `list_bounce_events` gets the core list, prompting the LLM to 'diagnose our latest bounces' lets the AI digest all textual rejection codes (e.g., SMTP 550 spam blocks vs 421 rate limits) and present a structured summary of where and why deliverability is faltering.