--- name: mailtrap-sending-emails description: Configure or troubleshoot Mailtrap live email sending with Email API, SMTP, transactional streams, bulk streams, or batches. risk: safe source: community date_added: "2026-06-19" --- # Sending emails (Mailtrap) ## Overview Mailtrap sends live email over **Email API** (REST) or **SMTP**. Two **streams** apply for API/SMTP: **Transactional** (non-promotional, app-generated) and **Bulk** (**promotional** / marketing volume). **Batch** is not a third stream: it is how you submit **many messages in one request** on whichever stream matches the content. **Campaigns** are a separate product path for promotional mail to **Mailtrap contacts**. Pair this sheet with the [Transactional](https://docs.mailtrap.io/developers/email-sending/transactional.md) / [Bulk](https://docs.mailtrap.io/developers/email-sending/bulk.md) developer pages when building or debugging integrations (including with AI-assisted coding). ## When to Use Use when integrating, configuring, or troubleshooting Mailtrap live email sending with Email API, SMTP, transactional streams, bulk streams, or batch requests. ## How to integrate (preference order) **Preferred order:** 1. **Plugin or integration for the user's platform** (no-code or minimal-config) _where available_ 2. **Official SDK** for your language when one exists (maintained clients, typed helpers, less room for URL/auth mistakes). 3. **HTTP Email API** when there is no SDK or the SDK does not fit (direct `POST` to `/api/send` or `/api/batch` with JSON). 4. **SMTP** only when you **really need it** (legacy stack, host/platform that only speaks SMTP, or hard constraints that rule out HTTP). ## Choosing how to send | Approach | Use when | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Transactional, single message** | Email **generated by your app** (password resets, receipts, notifications, alerts). One logical message per `POST https://send.api.mailtrap.io/api/send` | | **Bulk** | **Promotional** email **to contacts that you manage on your side** and send at volume through Mailtrap. Not the same as "batch": bulk is the **stream**, not the batch endpoint. | | **Batch** | You have **multiple different messages** to hand off **at the same time** (up to 500 per request). Cuts HTTP overhead; can be applied to both transactional and bulk | | **Campaigns** | **Promotional** email to recipients stored as **Mailtrap contacts**, using Mailtrap **Campaigns** (audiences, scheduling, reporting in the product). **Recommended** to avoid implementing contact management and email sending logic; **requires UI setup** before sends flow—this skill does not replace that workflow. | **Before generating SDK code:** read the README of the relevant SDK repository linked in the **SDKs** section below for current method signatures, constructor options, and examples. Do not rely on memory. **Related skills:** `mailtrap-testing-with-sandbox` (safe testing) and `mailtrap-setting-up-sending-domain` (verification before send). ## When not to use - **Sandbox only**—capturing mail without delivery, reading messages in a sandbox (`mailtrap-testing-with-sandbox`). - The main ask is **webhooks**, **step-by-step Campaigns UI setup**, or **deliverability deep-dives**. - **Exhaustive API reference**—once the user's path is clear, link the official send docs for full schemas, optional fields, and edge cases. ## Quick reference ### Email API | Stream | Send Endpoint | Batch Endpoint | Authorization Header | | ------------------------------------- | -------------------------------------------- | --------------------------------------------- | ------------------------------------------ | | Transactional | `POST https://send.api.mailtrap.io/api/send` | `POST https://send.api.mailtrap.io/api/batch` | `Authorization: Bearer $MAILTRAP_API_TOKEN` | | Bulk (promotional / marketing volume) | `POST https://bulk.api.mailtrap.io/api/send` | `POST https://bulk.api.mailtrap.io/api/batch` | `Authorization: Bearer $MAILTRAP_API_TOKEN` | ### SMTP | Setting | Transactional | Bulk | | -------- | --------------------------------- | --------------------------------- | | Host | `live.smtp.mailtrap.io` | `bulk.smtp.mailtrap.io` | | Port | 587 (also 25, 2525, 465 with SSL) | 587 (also 25, 2525, 465 with SSL) | | Username | `api` | `api` | | Password | API token (`$MAILTRAP_API_TOKEN`) | API token (`$MAILTRAP_API_TOKEN`) | ### Tokens Use `$MAILTRAP_API_TOKEN` in either `Authorization: Bearer ...` or `Api-Token: ...`. The same token works on both `send.api.mailtrap.io` and `bulk.api.mailtrap.io` as long as its scope covers the stream. Store tokens in environment variables or a secrets manager and rotate them when access changes. ### Rate limits | Scope | Limit | Window | | ----------------------- | ------------ | ---------- | | Sending API (per token) | 150 requests | 10 seconds | Use backoff on `429`. ### JSON body (non-template) Typical fields include `from`, `to`, `subject`, and `text` and/or `html`. Optional: `category`, `custom_variables`. Exact request bodies: [Transactional send](https://docs.mailtrap.io/developers/email-sending/transactional.md#post-api-send) and [Bulk send](https://docs.mailtrap.io/developers/email-sending/bulk.md#post-api-send). ### Examples (`curl`) Transactional send (`send.api.mailtrap.io`): ```bash curl -X POST https://send.api.mailtrap.io/api/send \ -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "from": {"email": "hello@yourdomain.com", "name": "Your App"}, "to": [{"email": "user@example.com"}], "subject": "Hello", "text": "Plain text body" }' ``` Bulk stream uses the **same** path and JSON shape on the bulk host (same env var; the token only needs bulk-stream scope): ```bash curl -X POST https://bulk.api.mailtrap.io/api/send \ -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "from": {"email": "hello@yourdomain.com", "name": "Your App"}, "to": [{"email": "user@example.com"}], "subject": "Promotional", "html": "

HTML body

" }' ``` Batch (array of messages; up to 500 per request — see API docs for full schema): ```bash curl -X POST https://send.api.mailtrap.io/api/batch \ -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"messages":[{"from":{"email":"a@example.com"},"to":[{"email":"b@example.com"}],"subject":"One","text":"..."}]}' ``` ### JSON body (template) Use `template_uuid` and `template_variables` instead of raw `text`/`html` to use a template hosted by Mailtrap. Minimal example: ```bash curl -X POST https://send.api.mailtrap.io/api/send \ -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "from": {"email": "hello@yourdomain.com", "name": "Your App"}, "to": [{"email": "user@example.com"}], "template_uuid": "your-template-uuid", "template_variables": {"user_name": "Jane"} }' ``` Use the same API operations as non-template sends. ### SDKs - [Node.js](https://github.com/mailtrap/mailtrap-nodejs) - [Python](https://github.com/mailtrap/mailtrap-python) - [PHP](https://github.com/mailtrap/mailtrap-php) - [Ruby](https://github.com/mailtrap/mailtrap-ruby) - [Java](https://github.com/mailtrap/mailtrap-java) - [.NET](https://github.com/mailtrap/mailtrap-dotnet) - [CLI](https://github.com/mailtrap/mailtrap-cli) ## Suppressions Mailtrap automatically manages suppressions for addresses that hard bounce, report spam, or unsubscribe, and will not send emails to these suppressed recipients again. For details, see the [Suppressions documentation](https://docs.mailtrap.io/developers/email-sending/suppressions.md). ## Common mistakes | Mistake | Fix | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Confusing **batch** with **bulk** | **Batch** = many messages in one `/api/batch` request. **Bulk** = promotional stream/host and token | | Promotional API mail on transactional host | Use bulk base URL and bulk token for promotional content you generate in code | | Bulk traffic on `send.api.mailtrap.io` | Promotional/bulk stream uses `bulk.api.mailtrap.io` | | Using sandbox SMTP host for live sending | Live sending uses `live.smtp.mailtrap.io` or `bulk.smtp.mailtrap.io` | | SMTP username is an email address | Username is `api`; password is the API token | | Sending before domain is verified | Complete **Sending Domains** setup and compliance (see `mailtrap-setting-up-sending-domain`) | | Guessing SDK API from memory | Read the SDK README and OpenAPI-linked examples; do not invent constructors or method names | | Choosing **SMTP first** for a greenfield app | Prefer **platform integration** if one exists, then **SDK**, then **HTTP API**; SMTP only when necessary (see **How to integrate**) | ## Limitations - This skill summarizes Mailtrap sending choices; use Mailtrap's current API docs for exhaustive schemas and product limits.