Mailtrap Sending Emails

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 skill with the official Transactional and Bulk developer pages when building or debugging integrations.

When to Use

Use when integrating, configuring, or troubleshooting Mailtrap live email sending with:

• Email API (REST POST /api/send or POST /api/batch)
• SMTP relay
• Transactional streams
• Bulk streams
• Batch requests (up to 500 messages per request)

Trigger keywords: mailtrap send, mailtrap api, mailtrap smtp, transactional email, bulk email, mailtrap batch, mailtrap token, mailtrap integration, send.api.mailtrap.io, bulk.api.mailtrap.io, live.smtp.mailtrap.io.

When NOT to Use

• Sandbox only — capturing mail without delivery, reading messages in a sandbox. Use mailtrap-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.
• Domain verification before sending — use mailtrap-setting-up-sending-domain.

Prerequisites

1. Mailtrap account with Email Sending enabled.
2. Sending domain verified in Mailtrap (SPF/DKIM/DMARC). Complete the Sending Domains setup and compliance first. See related skill mailtrap-setting-up-sending-domain.
3. API token with the correct stream scope. Store it in an environment variable:

   # PowerShell (Windows host — primary)
   $env:MAILTRAP_API_TOKEN = "YOUR_TOKEN"
   

   # Bash (if on Linux/macOS)
   export MAILTRAP_API_TOKEN="YOUR_TOKEN"
   

4. No live secrets in code. Always reference $MAILTRAP_API_TOKEN or a secrets manager. Rotate tokens when access changes.

Procedure

Step 1 — Choose integration approach (preference 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).

Step 2 — Identify the correct stream

HARD RULE: Promotional/bulk content must use the bulk host (bulk.api.mailtrap.io or bulk.smtp.mailtrap.io). Never send promotional content through send.api.mailtrap.io.

Step 3 — Send via Email API (REST)

Quick reference — API endpoints

The same token works on both hosts as long as its scope covers the stream. Api-Token: ... header is also accepted as an alternative to Authorization: Bearer ....

3a. Single message — Transactional (non-template)

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"
  }'

3b. Single message — Bulk (non-template)

Same JSON shape, different host:

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>"
  }'

3c. Batch (up to 500 messages per request)

Batch is not a stream — it is a submission method. Use on whichever stream matches content:

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":"..."}]}'

For bulk batch, use https://bulk.api.mailtrap.io/api/batch.

3d. Template-based send

Use template_uuid and template_variables instead of raw text/html:

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"}
  }'

JSON body fields

• Required: from, to, subject, and text and/or html (unless using a template).
• Optional: category, custom_variables.
• Template: template_uuid, template_variables.
• Full schemas: Transactional send and Bulk send.

Step 4 — Send via SMTP (only when necessary)

HARD RULE: SMTP username is api, not an email address. Password is the API token.

HARD RULE: Never use sandbox SMTP host for live sending. Live sending uses live.smtp.mailtrap.io or bulk.smtp.mailtrap.io.

Step 5 — Use an official SDK (if available)

Before generating SDK code: read the README of the relevant SDK repository for current method signatures, constructor options, and examples. Do not rely on memory.

• Node.js
• Python
• PHP
• Ruby
• Java
• .NET
• CLI

HARD RULE: Do not invent constructors or method names. Read the SDK README and OpenAPI-linked examples first.

Step 6 — Handle rate limits and errors

Implement exponential backoff on HTTP 429.

Step 7 — Suppressions

Mailtrap automatically manages suppressions for addresses that hard bounce, report spam, or unsubscribe. Mailtrap will not send emails to suppressed recipients again. See Suppressions documentation.

Examples

Choosing how to send

Pitfalls

Verification

1. Confirm token is set:

   echo $env:MAILTRAP_API_TOKEN
   

   Should print a non-empty token string (never commit this to source).

2. Send a test transactional email and check the HTTP response:

   curl -s -o response.json -w "%{http_code}" -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": "test@example.com"}],
       "subject": "Verification test",
       "text": "This is a test from Mailtrap."
     }'
   

   • Expected: HTTP 200 or 201 with a JSON response containing a message ID.
   • 429 = rate limited; implement backoff.
   • 401 / 403 = token missing, invalid, or lacks stream scope.
   • 422 = validation error (bad from domain, missing fields, etc.).

3. Verify SMTP connectivity (PowerShell):

   Test-NetConnection -ComputerName live.smtp.mailtrap.io -Port 587
   

   TcpTestSucceeded: True confirms the host/port is reachable.

4. Check Mailtrap dashboard:

   • Go to Email Sending → Email Logs in the Mailtrap UI.
   • Confirm the test message appears with a delivered status.
   • Check for suppressions if a recipient does not receive mail.

5. Batch verification: Send a 2-message batch and confirm the response includes per-message success/failure entries.

Related skills

• mailtrap-testing-with-sandbox — safe testing in a sandbox inbox without live delivery.
• mailtrap-setting-up-sending-domain — domain verification (SPF/DKIM/DMARC) before sending.

Limitations

• This skill summarizes Mailtrap sending choices; use Mailtrap's current API docs for exhaustive schemas and product limits.
• Campaigns UI setup is out of scope; link to Mailtrap product documentation for that workflow.