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 / Bulk 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 and Bulk 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
• Python
• PHP
• Ruby
• Java
• .NET
• 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.

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)