--- name: sending-emails-683c0390b9f8 description: >- Use when integrating, configuring, or troubleshooting Mailtrap live email sending (Email API or SMTP). Use when wiring outbound mail from an application or choosing how to send. --- # 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). ## 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:** `authorizing-api-requests` (tokens, env vars, auth headers), `using-email-templates` (template UUID and variables), `testing-with-sandbox` (safe testing), `setting-up-sending-domain` (verification before send). ## When not to use - **Sandbox only**—capturing mail without delivery, reading messages in a sandbox (`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. Full guidance (scope, storage, rotation) lives in skill `authorizing-api-requests`. ### 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"} }' ``` See skill `using-email-templates` and 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 `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**) | --- Source attribution: mailtrap Original project: https://github.com/mailtrap/mailtrap-skills/blob/ca365789c44012e7ac36623e63d0d223f5bdd35d/skills/sending-emails/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Railsware Products Studio LLC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: mailtrap Original project: https://github.com/mailtrap/mailtrap-skills/blob/ca365789c44012e7ac36623e63d0d223f5bdd35d/skills/sending-emails/SKILL.md Attribution basis: Source repository record Fields of work: Marketing Roles: Email Marketer, Growth Marketer, Content Marketer Specialties: API Tools: Mailtrap Country applicability: Country not specified Classification basis: Source category, role and specialization labels Instruction SHA-256: 14a9078c195386040d6bd98e596427c357fb26abca1e4113092ed9f58c903a4b