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:

• Plugin or integration for the user's platform (no-code or minimal-config) _where available_
• Official SDK for your language when one exists (maintained clients, typed helpers, less room for URL/auth mistakes).
• HTTP Email API when there is no SDK or the SDK does not fit (direct POST to /api/send or /api/batch with JSON).
• 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):

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

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

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:

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