sending-emails

---
name: sending-emails
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": "<p>HTML body</p>"
  }'
```

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**) |