canonical: https://jentic.com/apis/mailtrap.io/mailtrap-api

# Mailtrap Email Sending API

Jentic publishes the only available OpenAPI specification for Mailtrap Email Sending API, keeping it validated and agent-ready. The Mailtrap Email Sending API manages the operational surface around transactional email: sending domains, suppression lists, account-level sending statistics, and detailed email-log lookup. It pairs naturally with the Mailtrap send endpoint and is used to keep deliverability healthy by removing bounced or complained recipients and inspecting per-message delivery status.

## For AI agents

Manage Mailtrap sending domains, suppressions, and email logs. Useful for agents that automate deliverability hygiene, troubleshoot bounces, and check sending statistics for an account.

## Scope

Does not send the email itself, manage marketing contact lists, or run the Mailtrap inbox sandbox - use for sending domain, suppression, stats, and log management only.

## Capabilities

- Register a new sending domain on a Mailtrap account and retrieve its DNS records
- Remove a recipient from the suppression list to allow future sends
- Pull per-account sending statistics over a chosen window for reporting
- Look up the delivery log for a specific outbound message by its sending ID
- List every sending domain configured on the account for audit purposes
- Delete a stale sending domain that is no longer in use

## Use cases

### Sending Domain Onboarding

Adding a new domain to a transactional email provider is a multi-step DNS workflow. The Mailtrap sending-domain endpoint creates the domain record and returns the SPF, DKIM, and ownership values that need to land in DNS. Agents and onboarding scripts can create the domain, surface the records to the user, and then poll for verification status before enabling sends.

Example prompt: Call POST `/api/accounts/{account_id}/sending_domains` with example.com, return the DNS records to the user, and verify status with GET `/api/accounts/{account_id}/sending_domains/{sending_domain_id}.`

### Suppression List Hygiene

Hard bounces and spam complaints are added to a suppression list to protect domain reputation. Some addresses end up there in error and need to be removed. The Mailtrap suppression endpoints list every suppressed recipient and delete a single suppression by ID, supporting both bulk audits and one-off remediations triggered from a help-desk workflow.

Example prompt: List suppressions for the account, find the entry matching user@example.com, and DELETE the matching suppression so future sends are allowed.

### Delivery Log Investigation

Support and engineering teams need to know exactly what happened to a specific outbound email. The email-logs endpoints list recent messages and return a detailed log entry by sending message ID - including delivery status, response codes, and event timestamps - so agents can answer 'did this customer get the receipt?' without context-switching to the Mailtrap dashboard.

Example prompt: Call GET `/api/accounts/{account_id}/email_logs/{sending_message_id}` for the message in question and return the delivery status, recipient, and timestamps.

### AI Agent Deliverability Assistant

An agent acting as a deliverability assistant can pull sending stats, check suppression status, and verify domain configuration on demand. Through Jentic the agent searches by intent, loads the schema, and executes the right operation while the API token stays in the vault. The same flow plugs into Slack bots, internal copilots, and on-call runbooks.

Example prompt: Use Jentic search 'get mailtrap sending statistics', execute GET `/api/accounts/{account_id}/stats` for the last 7 days, and summarise the bounce rate for the on-call channel.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/accounts/{account_id}/sending_domains` | Create sending domain |
| GET | `/api/accounts/{account_id}/sending_domains` | List sending domains |
| GET | `/api/accounts/{account_id}/sending_domains/{sending_domain_id}` | Get sending domain |
| GET | `/api/accounts/{account_id}/suppressions` | List suppressions |
| DELETE | `/api/accounts/{account_id}/suppressions/{suppression_id}` | Delete suppression |
| GET | `/api/accounts/{account_id}/stats` | Get sending statistics |
| GET | `/api/accounts/{account_id}/email_logs/{sending_message_id}` | Get an email log message by ID |

## Key resources

- **Sending Domains** — Create, list, fetch, and delete sending domains on an account.
- **Suppressions** — List and delete suppression entries for hard bounces and complaints.
- **Stats** — Retrieve account-level sending statistics over time.
- **Email Logs** — List recent messages and look up a specific delivery log by ID.

## Why Jentic

- **Setup:** Wiring the Mailtrap Email Sending API by hand means sending your token in the API-token header or as a bearer JWT, targeting the mailtrap.io host, and tracking its domain, suppression, stats, and log endpoints yourself. Through Jentic you install once, import Mailtrap from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Mailtrap puts the account, domain, and suppression ids in the URL path (`/accounts/{account_id}/sending_domains/{sending_domain_id}`, `/accounts/{account_id}/suppressions/{suppression_id}`), so a rule can pin your agent to one account. You choose the operations it may call, so deleting a suppression is not included unless you add it.
- **Credential handling:** Your Mailtrap API token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list sending domains' or 'read email logs', and Jentic returns the matching Mailtrap operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Mailtrap API** — The Mailtrap send endpoint pairs with this management API to actually deliver email.
- **SendGrid Alerts API** — SendGrid offers competing transactional sending and deliverability management surfaces.
- **Postmark Server API** — Postmark provides similar domain, suppression, and message-event management for transactional sending.
- **Brevo API** — Brevo (formerly Sendinblue) covers transactional sending plus marketing automation in one API.

## FAQ

### Why is there no official OpenAPI spec for Mailtrap Email Sending API?

Mailtrap does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Mailtrap Email Sending API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Mailtrap Email Sending API use?

Mailtrap accepts either an API-Token request header or an HTTP bearer token. Through Jentic the credential is stored encrypted in the vault and injected at execute time so the agent never sees the raw token.

### Can I add a sending domain through the API?

Yes. POST `/api/accounts/{account_id}/sending_domains` creates the domain on the account and the GET endpoint returns the SPF and DKIM records you need to publish in DNS for verification.

### How do I look up the delivery status of a specific email?

Call GET `/api/accounts/{account_id}/email_logs/{sending_message_id}` with the sending message ID returned at send time. The response includes recipient, status, and event timestamps.

### What are the rate limits for the Mailtrap Email Sending API?

Rate limits are not declared in the spec - they depend on the Mailtrap plan tied to the account. Check your Mailtrap dashboard before automating high-frequency log lookups.

### How do I remove a suppression entry through Jentic?

Run pip install jentic, search 'remove mailtrap suppression', load the schema for DELETE `/api/accounts/{account_id}/suppressions/{suppression_id}`, and execute with the account and suppression IDs. The API-Token is injected from your Jentic One instance.

### Can I limit what my agent is allowed to do with the Mailtrap Email Sending API?

Yes. Because you run Jentic One yourself, your own rules decide which Mailtrap operations and credentials the agent may use, so you can allow read-only calls like GET `/api/accounts/{account_id}/sending_domains`, GET `/api/accounts/{account_id}/stats`, and GET `/api/accounts/{account_id}/email_logs/{sending_message_id}` while withholding write operations. Mailtrap places the account, sending-domain, and suppression IDs in the URL path, so a rule can pin the agent to a single account and its resources. Destructive actions such as DELETE `/api/accounts/{account_id}/suppressions/{suppression_id}` or deleting a sending domain are only callable if you explicitly add them to the agent's allowed set. The API token is injected at execution time by your own instance, so the agent never handles the raw credential.