canonical: https://jentic.com/apis/mailtrap.io/main

# Mailtrap API

Jentic publishes the only available OpenAPI specification for Mailtrap API, keeping it validated and agent-ready. The Mailtrap send API is a focused two-endpoint surface for delivering transactional email: a single send endpoint for one message and a batch endpoint for sending many in one call. It is built around the API-Token header and is the operational pair to Mailtrap's domain, suppression, and log management API.

## For AI agents

Send a single transactional email or a batch of messages through Mailtrap. Used by agents that deliver receipts, sign-up confirmations, password resets, and other one-off or batched messages.

## Scope

Does not manage sending domains, suppression lists, or delivery logs - use for sending single or batched transactional email only.

## Capabilities

- Send a single transactional email with HTML, text, attachments, and template variables
- Send a batch of personalised messages to many recipients in one call
- Attach files inline by base64-encoding them in the request body
- Reference a stored Mailtrap template by ID and pass per-recipient variables
- Track each send by category and custom variable for downstream analytics

## Use cases

### Single Transactional Email

Most user-triggered emails - receipts, password resets, sign-up confirmations - are individual messages with personalised content. The Mailtrap /send endpoint accepts the from, to, subject, HTML, text, and attachment fields and returns a sending message ID for downstream log lookup. Integration is a single POST per message and pairs naturally with template references for consistent formatting.

Example prompt: POST /send with from, to, subject, html, and a base64 PDF attachment, then capture the returned message_id for log lookup.

### Batched Personalised Send

Onboarding sequences and bulk notifications need per-recipient personalisation in a single call. The Mailtrap /batch endpoint accepts a list of recipients with their own template variables, sending each as an individual message while keeping the request count low. Each recipient gets a distinct message ID for downstream tracking.

Example prompt: POST /batch with a list of 100 recipients each carrying their own template variables, then store the per-recipient message IDs.

### Template-Driven Receipts

Storing email content in Mailtrap templates lets non-engineers update copy without redeploying. The send endpoints accept a template ID and a variables object, applying server-side rendering before delivery. Receipts, shipping confirmations, and other structured messages move from inline HTML in code to managed templates in the Mailtrap dashboard.

Example prompt: POST /send with template_uuid set to the receipt template and template_variables carrying order_total and tracking_number.

### AI Agent Outbound Email

Agents that close support tickets, confirm bookings, or notify users need a reliable send surface. Through Jentic the agent searches for the Mailtrap send operation, loads the schema, and executes the POST while the API-Token stays in the vault. The same flow underpins notification copilots and automated case-resolution agents.

Example prompt: Use Jentic to search 'send a transactional email', execute POST /send with the resolved customer details, and report the message_id back to the calling tool.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/send` | Send email |
| POST | `/batch` | Batch send emails |

## Key resources

- **Single Send** — Send a single transactional email with attachments and template variables.
- **Batch Send** — Send a list of personalised messages to many recipients in one request.

## Why Jentic

- **Setup:** Wiring the Mailtrap API by hand means sending your token in the API-token header, choosing between the send.api and bulk.api Mailtrap hosts, and building the email payload yourself. Through Jentic you install once, import Mailtrap from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Mailtrap carries the recipients in the request body for both /send and /batch, so limit the agent to the operations it needs, such as single-message send, and add batch sending only when you want it. The operation set is your choice.
- **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 'send a transactional email' or 'send a batch of emails', 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 Email Sending API** — Manages sending domains, suppressions, stats, and email logs that the send API generates.
- **SendGrid Alerts API** — SendGrid is a competing transactional email provider with similar send and management APIs.
- **Postmark Server API** — Postmark is a competing transactional email API with strong deliverability focus.
- **Mailsac API** — Mailsac receives messages at disposable inboxes for end-to-end testing of Mailtrap sends.

## FAQ

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

Mailtrap does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Mailtrap 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 API use?

Mailtrap requires an API-Token request header on each call. Through Jentic the token is stored encrypted in the vault and injected at execute time, so the raw value never enters the agent context.

### Can I send to multiple recipients in one call?

Yes. POST /batch accepts a list of recipients each with their own template variables and returns a per-recipient message ID. Use POST /send when you only need to deliver a single message.

### How do I attach a file to a Mailtrap send?

Include an attachments array on the POST /send body where each entry has the base64-encoded content, filename, and content_type. Inline images use the same shape with a content_id reference.

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

Rate limits are not declared in the spec and depend on the Mailtrap plan attached to the account. Check the Mailtrap dashboard before driving high-volume sends.

### How do I send a single email through Jentic?

Run pip install jentic, search 'send a transactional email through mailtrap', load the schema for POST /send, and execute with the from, to, subject, and html fields. Jentic injects the API-Token from the vault.

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

Yes. Because Jentic One is self-hosted, you decide which Mailtrap operations your agent can call, and the Mailtrap surface is just two operations: POST /send for a single message and POST /batch for many recipients in one call. You can allow only single-message send and add batch sending when you actually want it, since the operation set is your choice. Your Mailtrap API token is held by your own instance and injected at execution time, so the agent uses the credential without it entering the prompt or logs.