Mailtrap Email Logs & Sending Stats
Did that password-reset email reach the customer, and why are Outlook opens down this week? Search Mailtrap email logs by recipient, read a message's delivery events, break sending stats down by day, domain, category or mailbox provider, and suppress addresses that bounce.
Connect this API to an AI agent Browse all specs
What you can do with Mailtrap Email Logs & Sending Stats 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 | /api/domains |
listDomains | List sending domains with DNS verification and compliance status |
| GET | /api/domains/{domain_id} |
getDomain | Get a sending domain's DNS records and settings |
| GET | /api/stats |
getSendingStats | Get delivery, bounce, open, click and spam totals for a date range |
| GET | /api/stats/date |
getSendingStatsByDate | Get sending stats per day |
| GET | /api/stats/domains |
getSendingStatsByDomain | Get sending stats per sending domain |
| GET | /api/stats/categories |
getSendingStatsByCategory | Get sending stats per email category |
| GET | /api/stats/email_service_providers |
getSendingStatsByMailboxProvider | Get sending stats per mailbox provider (Gmail, Outlook, Yahoo) |
| GET | /api/email_logs |
listEmailLogs | Search sent emails by recipient, sender, subject, status or date |
| GET | /api/email_logs/{sending_message_id} |
getEmailLog | Get one sent email with its delivery, open and bounce events |
| GET | /api/suppressions |
listSuppressions | List suppressed addresses (bounces, spam complaints, unsubscribes) |
| POST | /api/suppressions |
createSuppression | Stop sending to an email address |
Authentication
apiToken
API key — sent as the Api-Token header
Mailtrap API token sent in the Api-Token header.
How to get a credential
- Sign in to Mailtrap and open Settings > API Tokens (mailtrap.io/api-tokens).
- Click Add Token, name it (e.g.
VX Agents) and give it access to your sending domains (Domain Admin or Viewer). - Copy the token; it is shown in full only once.
Permissions used
| Token access | Operations |
|---|---|
| Viewer on the account or domains | listDomains, getDomain, getSendingStats, getSendingStatsByDate, getSendingStatsByDomain, getSendingStatsByCategory, getSendingStatsByMailboxProvider, listEmailLogs, getEmailLog, listSuppressions |
| Admin on the account or domains | createSuppression |
Common errors
- 401 Unauthorized: missing or wrong token. Check the header name is
Api-Tokenand the token was not deleted. - 403 Forbidden: the token has no access to that domain or account; widen its permissions in Settings > API Tokens.
- 400 / 422: a required parameter is missing or malformed, e.g.
start_date/end_datenot inYYYY-MM-DD. - 429 Too Many Requests: the account API allows about 150 requests per 10 seconds; wait and retry.
Store the token as a VX Agents credential so it is never pasted into chat.
Usage guide
Setup
- Add an API key credential: a Mailtrap API token (Settings > API Tokens), sent in the
Api-Tokenheader. The token decides which account and domains you see. - Run
listDomainsonce and note theidof the sending domain you care about; pin it asdomain_id(and indomain_ids[]for stats) if you only work with one domain.
Find out what happened to an email
listEmailLogswith filters in deep-object form, e.g.filters[to][operator]=ci_equal,filters[to][value][email protected], plusfilters[sent_after]/filters[sent_before](ISO 8601). Other filters:from,subject,status(delivered,not_delivered,enqueued,opted_out),category,domain_id,sending_stream.getEmailLogwith themessage_idfrom step 1 to read its status, open/click counts and theeventslist (delivery, open, click, bounce, spam) with their details.- If the address keeps bouncing or complained, check
listSuppressionswithemail. To stop sending to it, show the user the address and wait for confirmation, thencreateSuppressionwithemail,domain_idandsending_stream(transactional,bulkorany).
Report on deliverability
getSendingStatswithstart_dateandend_date(YYYY-MM-DD, both required) for delivered, bounced, opened, clicked and spam counts and rates.- Break it down with
getSendingStatsByDate(trend),getSendingStatsByDomain,getSendingStatsByCategoryorgetSendingStatsByMailboxProvider(Gmail vs Outlook vs Yahoo). Narrow withdomain_ids[],categories[],sending_streams[]. getDomainto check DNS records (SPF, DKIM, DMARC) when one domain's numbers drop.
Good to know
- Email logs are newest first; page with
search_after= the previous response'snext_page_cursor. - Message ids are UUIDs; domain ids are integers.
- Only messages sent through Mailtrap Email API/SMTP appear here (not Sandbox test emails).
- Sending itself is a separate API (
send.api.mailtrap.io) and is not in this spec, nor are domain changes or deletes.
Source: Mailtrap API reference (https://docs.mailtrap.io/developers), checked 2026-10-21.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Mailtrap Email Logs & Sending Stats” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.