sending-emails

What this skill does

# 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": "[email protected]", "name": "Your App"},
    "to": [{"email": "[email protected]"}],
    "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": "[email protected]", "name": "Your App"},
    "to": [{"email": "[email protected]"}],
    "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":"[email protected]"},"to":[{"email":"[email protected]"}],"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": "[email protected]", "name":