Mailgun Email Sending & Deliverability
Send, schedule and trace transactional email through Mailgun: send from a verified domain with templates and tags, follow each message through the event log, query delivery and open rates with the Metrics API, and check bounce, unsubscribe and complaint lists before a resend.
Connect this API to an AI agent Browse all specs
What you can do with Mailgun Email Sending & Deliverability via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v4/domains |
listDomains | List sending domains and their verification state |
| GET | /v4/domains/{name} |
getDomain | Get a domain's DNS records and settings |
| POST | /v3/{domain_name}/messages |
sendMessage | Send an email (text, HTML or a stored template) from a domain |
| GET | /v3/{domain_name}/events |
listEvents | Search the event log: delivered, failed, opened, clicked, complained |
| POST | /v1/analytics/metrics |
queryMetrics | Query delivery, open and click metrics over a date range |
| POST | /v1/analytics/logs |
queryLogs | List message logs for the account with filters |
| GET | /v3/{domain_name}/bounces |
listBounces | List addresses that bounced on a domain |
| GET | /v3/{domain_name}/bounces/{address} |
getBounce | Check whether one address is on the bounce list and why |
| GET | /v3/{domain_name}/unsubscribes |
listUnsubscribes | List addresses that unsubscribed from a domain |
| POST | /v3/{domain_name}/unsubscribes |
addUnsubscribes | Add one or more addresses to the unsubscribe list |
| GET | /v3/{domain_name}/complaints |
listComplaints | List addresses that marked mail as spam |
| GET | /v3/lists |
listMailingLists | List mailing lists |
| GET | /v3/lists/{list_address}/members |
listListMembers | List members of a mailing list |
| POST | /v3/lists/{list_address}/members |
addListMember | Add or update a member on a mailing list |
Authentication
mailgunApiKey
HTTP Basic
HTTP Basic auth: username api, password = a Mailgun API key.
How to get a credential
- Sign in to Mailgun and open Settings > API Security (Account > API keys).
- Click Add new key, give it a description (e.g. "VX Agents") and create it.
- Copy the key now: Mailgun shows it only once.
- In VX Agents, use
apias the username and the key as the password. - Account on the EU region? Change the server to
https://api.eu.mailgun.net; keys only work in their own region.
Permissions used
Mailgun account API keys are not scoped: one key covers every operation below. Use a dedicated key so you can revoke it on its own.
| Access | Operations |
|---|---|
| Send | sendMessage |
| Read domains | listDomains, getDomain |
| Read events & analytics | listEvents, queryMetrics, queryLogs |
| Suppressions | listBounces, getBounce, listUnsubscribes, addUnsubscribes, listComplaints |
| Mailing lists | listMailingLists, listListMembers, addListMember |
Common errors
- 401 Unauthorized: wrong key, the username is not
api, or the key belongs to the other region (US vs EU). - 403 Forbidden: the domain is not verified yet, or the account is a sandbox sending to a recipient that is not authorized.
- 400 Bad Request: missing
from/to/subject, notext/html/template, or a malformed date or filter. - 429 Too Many Requests: sending or API rate limit reached; wait and retry.
Store the key as a VX Agents credential (basic auth) and never paste it into chat.
Usage guide
Setup
- Credential: HTTP Basic, username
api, password = Mailgun API key. - Region: the base URL is
https://api.mailgun.net(US). EU accounts must usehttps://api.eu.mailgun.net. - Preset worth pinning:
domain_name/name= your verified sending domain (e.g.mg.example.com). RunlistDomainsonce to find it (stateactive).
Send and trace an email
listBounces/getBounce,listUnsubscribesandlistComplaintsfor the recipient. Do not send to an address on these lists.- Show the user the draft (from, to, subject, body or template + variables) and get a yes.
sendMessageas form fields:from("Shop [email protected]", must be on the domain),to,subject, plustextand/orhtml, ortemplatewitht:variables(a JSON string). Addo:tagfor reporting ando:deliverytime(RFC 2822 date) to schedule it.o:testmode=yesvalidates without delivering.- Keep the returned
id(Message-ID). UselistEventswithmessage-id=<id without angle brackets>orrecipient=<email>to see accepted → delivered / failed → opened / clicked. - For trends, use
queryMetricswithstart,end(RFC 2822),resolution(hour/day/month),dimensions(e.g.["time"]),metrics(e.g.delivered_count,opened_rate,bounced_rate) and afilterondomainortag.
Lists and opt-outs
listMailingLists, thenlistListMembersfor a list address.addListMemberwithaddress,name,vars(JSON string) andupsert=yesto update an existing member.- When someone asks to stop receiving mail,
addUnsubscribeswith a JSON array such as[{"address":"[email protected]","tags":["*"]}].
Ask the user to confirm before sendMessage, addListMember and addUnsubscribes: they send email or change who gets it.
Good to know
- Events are kept for a limited time (at least 3 days, longer on paid plans). Page with the
paging.nextURL's token.begin/endtake RFC 2822 dates or Unix timestamps. queryLogsrequiresduration(e.g.1d), optionally withstart/end. It covers the whole account, so filter by domain.- Sandbox domains only deliver to authorized recipients.
- The legacy Stats and Tags endpoints are deprecated, so they are not included. Use
queryMetrics. - Source: Mailgun API reference (https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun), checked 2026-10-16.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Mailgun Email Sending & Deliverability” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.