csh
/
playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
playbook/antigravity-awesome-skills/skills/mailtrap-sending-emails/SKILL.md

168 lines
11 KiB
Markdown
Raw Blame History

---
name: mailtrap-sending-emails
description: Configure or troubleshoot Mailtrap live email sending with Email API, SMTP, transactional streams, bulk streams, or batches.
risk: critical
source: community
date_added: "2026-06-19"
---
# 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).
## When to Use
Use when integrating, configuring, or troubleshooting Mailtrap live email sending with Email API, SMTP, transactional streams, bulk streams, or batch requests.
## 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:** `mailtrap-testing-with-sandbox` (safe testing) and `mailtrap-setting-up-sending-domain` (verification before send).
## When not to use
- **Sandbox only**—capturing mail without delivery, reading messages in a sandbox (`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.
## 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. Store tokens in environment variables or a secrets manager and rotate them when access changes.
### 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"}
}'
```
Use 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 `mailtrap-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**) |
## Limitations
- This skill summarizes Mailtrap sending choices; use Mailtrap's current API docs for exhaustive schemas and product limits.
Reference in New Issue View Git Blame Copy Permalink