# Documentation
Complete email infrastructure for developers. Send production emails, test in sandbox, and run email campaigns - all in one platform.
Build, test, and send emails with confidence using Mailtrap's comprehensive email platform designed for developers and product teams.
## Official SDKs
Get started quickly with our official SDKs for your favorite programming language.
{% columns %}
{% column %}
**Get started in 5 Minutes**
Setting up Mailtrap should be the easiest part of your email journey. With clear endpoints, copy-paste-ready examples, and instant authentication, you'll send your first email in minutes — not hours.
No guesswork, no complexity — just your first successful email, fast.
[Get started](/getting-started/email-api-smtp) [API reference](https://docs.mailtrap.io/developers)
{% endcolumn %}
{% column %}
{% code title="index.js" overflow="wrap" %}
```javascript
// Send your first email
const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({
token: "YOUR_API_TOKEN"
});
await client.send({
from: { email: "hello@example.com" },
to: [{ email: "user@example.com" }],
subject: "Hello from Mailtrap!",
text: "Welcome to Mailtrap Email API"
});
```
{% endcode %}
{% endcolumn %}
{% endcolumns %}
## Quick start guides
Choose your product and get up and running quickly with our step-by-step guides.
:paper-plane:Email API/SMTP
Send Production Emails
Deliver transactional emails reliably with our API or SMTP service. Get detailed analytics and ensure high deliverability.
## Ready to get started?
{% hint style="info" %}
**New to Mailtrap?** Start with our [Email Sandbox](/getting-started/email-sandbox) to test your emails in a safe environment, then move to [Email API/SMTP](/getting-started/email-api-smtp) for production sending.
{% endhint %}
:rocket-launch:Start with a Free plan
Get started with Mailtrap's free plan. No credit card required. Test emails, send up to 4000 emails/m, and explore all features.
# AI Onboarding
Easy-to-follow documentation to onboard your AI agent to Mailtrap.
Building with AI? Mailtrap provides several resources to make your life easier:
* [Mailtrap MCP server](#mailtrap-mcp-server)
* [Mailtrap docs for agents](#mailtrap-docs-for-agents)
* [Mailtrap CLI app](#mailtrap-cli-app)
* [Mailtrap skills](#mailtrap-skills)
{% content-ref url="/pages/ixuwtffMIHRUC2AEwtOX" %}
[Email API/SMTP](/getting-started/email-api-smtp)
{% endcontent-ref %}
{% content-ref url="/pages/kUZPOczjlPDqtc17WDgZ" %}
[Email Sandbox](/email-sandbox/overview)
{% endcontent-ref %}
{% content-ref url="/pages/V3u4qiAblbvKfyv8G2fn" %}
[Email Marketing](/email-marketing/overview)
{% endcontent-ref %}
### Getting started
Before you start, keep in mind that we require a human to:
* Sign up for a [free Mailtrap account](https://mailtrap.io/register/signup)
* Create an [API Token](https://docs.mailtrap.io/email-api-smtp/setup/api-tokens)
### Mailtrap MCP server
With the[ Mailtrap MCP server](https://github.com/mailtrap/mailtrap-mcp), you can perform various email operations through your favorite AI IDE (e.g., VS Code, Cursor, etc.) or your AI assistant (e.g., Claude). Some of the use cases include sending transactional emails, testing emails in your sandbox, managing templates, getting sending statistics, and more.
The Mailtrap MCP server is implemented as a Node.js command line utility and comes with quick-install buttons and pre-made code snippets for easy installation:
{% tabs %}
{% tab title="Claude or Cursor" %}
```json
{
"mcpServers": {
"mailtrap": {
"command": "npx",
"args": ["-y", "mcp-mailtrap"],
"env": {
"MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
"DEFAULT_FROM_EMAIL": "your_sender@example.com",
"MAILTRAP_ACCOUNT_ID": "your_account_id",
"MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
}
}
}
}
```
{% endtab %}
{% tab title="VS Code" %}
```json
{
"mcp": {
"servers": {
"mailtrap": {
"command": "npx",
"args": ["-y", "mcp-mailtrap"],
"env": {
"MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
"DEFAULT_FROM_EMAIL": "your_sender@example.com",
"MAILTRAP_ACCOUNT_ID": "your_account_id",
"MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
}
}
}
}
}
```
{% endtab %}
{% tab title="Claude (asdf)" %}
```json
{
"mcpServers": {
"mailtrap": {
"command": "/Users//.asdf/shims/npx",
"args": ["-y", "mcp-mailtrap"],
"env": {
"PATH": "/Users//.asdf/shims:/usr/bin:/bin",
"ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
"ASDF_DATA_DIR": "/Users//.asdf",
"ASDF_NODEJS_VERSION": "20.6.1",
"MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
"DEFAULT_FROM_EMAIL": "your_sender@example.com",
"MAILTRAP_ACCOUNT_ID": "your_account_id",
"MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
}
}
}
}
```
{% endtab %}
{% tab title="MCP Bundle (MCPB)" %}
```json
# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack
# Inspect bundle metadata
npm run mcpb:info
# Sign the bundle for distribution (optional)
npm run mcpb:sign
```
{% endtab %}
{% endtabs %}
{% content-ref url="/spaces/gkNigAKiqQtQub1GOdjY/pages/Zc2hzutZptTaPF3PE9rx" %}
[Mailtrap MCP Server](/guides/ai-powered-integrations/mcp-server)
{% endcontent-ref %}
### Mailtrap docs for agents
To give your agent more context regarding Mailtrap you can share the following docs:
Markdown
To fetch a markdown version of any page from Mailtrap documentation, simply add `.md` to the end of the page URL. For instance:
> AI onboarding documentation Full llms.txt
Or, you can also give your agent to all of our docs in a single llms.txt file:
> Full Mailtrap documentation
### Mailtrap CLI app
With [Mailtrap’s CLI app](https://github.com/mailtrap/mailtrap-cli), you can send emails, inspect sandbox, monitor deliverability stats, and administer domains, templates, contacts, and more – all from your terminal.
To install, you can download the latest release from [GitHub Releases](https://github.com/mailtrap/mailtrap-cli/releases) and add it to your PATH, or use either Homebrew:
```
brew install mailtrap/cli/mailtrap
```
or Go:
```
go install github.com/mailtrap/mailtrap-cli@latest
```
Here’s some examples:
```json
# Send a transactional email
mailtrap send transactional \
--from "app@yourdomain.com" \
--to "user@example.com" \
--subject "Order confirmed" \
--html "
Thanks for your order
"
# Check spam score on a sandbox message
mailtrap messages spam-score --sandbox-id 12345 --id 67890
# Pull sending stats by mailbox provider
mailtrap stats by-esp --domain-id 111 --period 30
# Bulk import contacts from JSON
mailtrap contacts import --file contacts.json
```
### Mailtrap skills
Mailtrap skills allow you to give your AI coding assistant accurate Mailtrap context for tasks such as sending emails, testing with sandbox, using email templates, setting up a sending domain, and managing contacts.
To install, simply copy the [skills folders](https://github.com/mailtrap/mailtrap-skills) into the directory your agent reads. For example, for Cursor, that’s `.cursor/skills/`. Or, you can install via npx:
```
npx skills add mailtrap/mailtrap-skills
```
And here's a table with each skill and a brief description
| Skill | Description |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [`sending-emails`](https://github.com/mailtrap/mailtrap-skills/tree/main/skills/sending-emails) | Use when integrating, configuring, or troubleshooting Mailtrap (Email API or SMTP). |
| [`testing-with-sandbox`](https://github.com/mailtrap/mailtrap-skills/tree/main/skills/testing-with-sandbox) | Use when capturing outbound email in development or staging in a fake inbox. |
| [`using-email-templates`](https://github.com/mailtrap/mailtrap-skills/tree/main/skills/using-email-templates) | Use when creating, managing, and sending Mailtrap-hosted email templates. |
| [`setting-up-sending-domain`](https://github.com/mailtrap/mailtrap-skills/tree/main/skills/setting-up-sending-domain) | Use when adding or verifying a Mailtrap sending domain. |
| [`managing-contacts`](https://github.com/mailtrap/mailtrap-skills/tree/main/skills/managing-contacts) | Use when using Mailtrap Contacts API or UI to add, update, bulk import, list, segment marketing contacts, custom fields, or custom events. |
# Email API/SMTP
Send transactional and bulk emails from your app using the Mailtrap Email API
Send transactional and bulk emails from your app using the Mailtrap Email API. This guide walks you through complete setup — from choosing your SDK to sending your first email.
AI-assisted setup checklist — give your AI assistant this page and your tech stack
AI assistants: follow these steps in order, completing each one before moving to the next. Pause and confirm with the user before proceeding at steps marked with ⏸️.
Page URL for context: `https://docs.mailtrap.io/getting-started/email-api-smtp.md`
1. Install the right SDK for your stack
2. Create your API token — go to [API Tokens](https://mailtrap.io/settings/api-tokens), create one with Admin access, and paste it to your assistant. This is the only manual step.
3. Add your sending domain via the API and fetch the required DNS records
4. Add DNS records at your registrar (your assistant can do this via the registrar's API if you provide credentials)
5. Verify DNS propagation with `dig` and check domain status via the API. You can also click **Verify DNS Records** in [Sending Domains](https://mailtrap.io/domains). If after your domain has been verified compliance stays at `awaiting_questionnaire`, check for a **Fill in Compliance Form** button in your domain details.
6. ⏸️ **DNS takes time. Test with Sandbox now?** Send a test email to your Sandbox so you can see Mailtrap working while DNS propagates. No domain verification needed for Sandbox.
7. ⏸️ **Domain verified. Switch to live sending?** Generate live sending code using your actual verified domain.
8. ⏸️ **Create a Mailtrap-hosted email template?** Generate the HTML for your use case, create it via the API, and wire up sending code that references it by UUID
9. Set up Sandbox for your staging/CI environment
For complete API details: [llms.txt](https://docs.mailtrap.io/llms.txt) | [llms-full.txt](https://docs.mailtrap.io/llms-full.txt)
## Prerequisites
* A [Mailtrap account](https://mailtrap.io/signup)
* A domain you own (you'll set it up in Step 3)
* Your app's technology stack decided (language/framework)
## Step 1: Choose Your SDK
Mailtrap provides official SDKs for all major languages. Pick the one that matches your stack:
| Language | Package | Install |
| -------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Node.js | `mailtrap` | `npm install mailtrap` |
| Python | `mailtrap` | `pip install mailtrap` |
| PHP | `railsware/mailtrap-php` | `composer require railsware/mailtrap-php` |
| Ruby | `mailtrap` | `gem install mailtrap` |
| Go | `github.com/railsware/mailtrap-go` | `go get github.com/railsware/mailtrap-go` |
| Java | `com.mailtrap:mailtrap-java` | See [Maven/Gradle setup](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/java.md) |
| .NET | `Mailtrap` | `dotnet add package Mailtrap` |
| Elixir | `mailtrap` | `{:mailtrap, "~> 1.0"}` |
Full SDK documentation: [Node.js](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/nodejs.md) | [Python](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/python.md) | [PHP](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/php.md) | [Ruby](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/ruby.md) | [Go](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/go.md) | [Java](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/java.md) | [.NET](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/dotnet.md) | [Elixir](https://github.com/mailtrap/mailtrap-docs/blob/main/guides-and-tips/sdks/elixir.md)
{% hint style="info" %}
**No SDK for your stack?** Use the [REST API directly](https://github.com/mailtrap/mailtrap-docs/blob/main/api-docs/README.md) with any HTTP client.
{% endhint %}
## Step 2: Get Your API Token
You need an API token to authenticate all Mailtrap API calls — sending emails, managing domains, creating templates.
Go to [API Tokens](https://mailtrap.io/settings/api-tokens) → create a new token with **Admin** access to your account → copy the token value.
{% hint style="info" %}
**Using an AI assistant?** Paste the token to your assistant — it can handle everything else via API.
{% endhint %}
## Step 3: Verify Your Sending Domain
You need a verified domain to send live emails. This can be done through the UI or entirely programmatically.
### Option A: UI
Go to [Sending Domains](https://mailtrap.io/domains) → **Add Domain** → enter your domain → add the DNS records shown to your domain provider.
Check our [Sending Domain Setup Guide](/email-api-smtp/setup/sending-domain) for detailed instructions on adding and verifying your domain.
### Option B: Programmatically / with AI tools
Your AI assistant can handle the entire domain setup flow. Here's the complete workflow:
**1. Add your domain to Mailtrap**
```bash
curl -X POST "https://mailtrap.io/api/accounts/{account_id}/sending_domains" \
-H "Authorization: Bearer $MAILTRAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sending_domain": {"domain_name": "yourdomain.com"}}'
```
The response includes all DNS records you need to add:
```json
{
"id": 12345,
"domain_name": "yourdomain.com",
"dns_verified": false,
"compliance_status": "initial",
"dns_records": [
{
"key": "spf",
"type": "TXT",
"name": "yourdomain.com",
"value": "v=spf1 include:_spf.mailtrap.io ~all",
"status": "unchecked"
},
{
"key": "dkim1",
"type": "CNAME",
"name": "rwmt1._domainkey.yourdomain.com",
"value": "rwmt1.dkim.mailtrap.io",
"status": "unchecked"
},
{
"key": "dkim2",
"type": "CNAME",
"name": "rwmt2._domainkey.yourdomain.com",
"value": "rwmt2.dkim.mailtrap.io",
"status": "unchecked"
},
{
"key": "dmarc",
"type": "TXT",
"name": "_dmarc.yourdomain.com",
"value": "v=DMARC1; p=none;",
"status": "unchecked"
}
]
}
```
**2. Add DNS records at your registrar**
Most domain registrars have APIs your AI assistant can use to add these records automatically. Provide your registrar's API credentials and let it handle the rest.
{% tabs %}
{% tab title="Cloudflare" %}
```bash
# Add DKIM CNAME record
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "CNAME",
"name": "rwmt1._domainkey.yourdomain.com",
"content": "rwmt1.dkim.mailtrap.io",
"ttl": 3600,
"proxied": false
}'
# Add SPF TXT record
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "TXT",
"name": "yourdomain.com",
"content": "v=spf1 include:_spf.mailtrap.io ~all",
"ttl": 3600
}'
# Add DMARC TXT record
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "TXT",
"name": "_dmarc.yourdomain.com",
"content": "v=DMARC1; p=none;",
"ttl": 3600
}'
```
{% endtab %}
{% tab title="AWS Route 53" %}
```bash
aws route53 change-resource-record-sets \
--hosted-zone-id $HOSTED_ZONE_ID \
--change-batch '{
"Changes": [
{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": "rwmt1._domainkey.yourdomain.com",
"Type": "CNAME",
"TTL": 3600,
"ResourceRecords": [{"Value": "rwmt1.dkim.mailtrap.io"}]
}
},
{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": "rwmt2._domainkey.yourdomain.com",
"Type": "CNAME",
"TTL": 3600,
"ResourceRecords": [{"Value": "rwmt2.dkim.mailtrap.io"}]
}
},
{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": "yourdomain.com",
"Type": "TXT",
"TTL": 3600,
"ResourceRecords": [{"Value": "\"v=spf1 include:_spf.mailtrap.io ~all\""}]
}
},
{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": "_dmarc.yourdomain.com",
"Type": "TXT",
"TTL": 3600,
"ResourceRecords": [{"Value": "\"v=DMARC1; p=none;\""}]
}
}
]
}'
```
{% endtab %}
{% tab title="GoDaddy" %}
```bash
# Add DKIM CNAME record
curl -X PATCH "https://api.godaddy.com/v1/domains/yourdomain.com/records" \
-H "Authorization: sso-key $GODADDY_API_KEY:$GODADDY_API_SECRET" \
-H "Content-Type: application/json" \
-d '[
{
"type": "CNAME",
"name": "rwmt1._domainkey",
"data": "rwmt1.dkim.mailtrap.io",
"ttl": 3600
}
]'
```
{% endtab %}
{% endtabs %}
**3. Check DNS propagation**
Use `dig` to verify records have propagated before triggering verification in Mailtrap:
```bash
# Check DKIM CNAME records
dig CNAME rwmt1._domainkey.yourdomain.com +short
# Expected: rwmt1.dkim.mailtrap.io.
dig CNAME rwmt2._domainkey.yourdomain.com +short
# Expected: rwmt2.dkim.mailtrap.io.
# Check SPF TXT record
dig TXT yourdomain.com +short | grep mailtrap
# Expected: "v=spf1 include:_spf.mailtrap.io ~all"
# Check DMARC TXT record
dig TXT _dmarc.yourdomain.com +short
# Expected: "v=DMARC1; p=none;"
```
{% hint style="info" %}
DNS propagation usually takes minutes but can take up to 48 hours. If `dig` returns the expected values, records are ready. You can also click **Verify DNS Records** on your domain in [Sending Domains](https://mailtrap.io/domains) to trigger a check from Mailtrap's side.
{% endhint %}
**4. Check verification status via API**
Poll the domain until `dns_verified` is `true`:
```bash
curl "https://mailtrap.io/api/accounts/{account_id}/sending_domains/{domain_id}" \
-H "Authorization: Bearer $MAILTRAP_API_KEY"
```
Each record in the `dns_records` array has a `status` field: `pass`, `fail`, or `unchecked`. When all records show `pass`, your domain is verified.
{% hint style="warning" %}
After DNS verification, newly added domains undergo a compliance check. Your domain's `compliance_status` will progress from `under_review` → `awaiting_questionnaire` → `compliant`. If the status stays at `awaiting_questionnaire`, check your domain details in [Sending Domains](https://mailtrap.io/domains) — you may need to click **Fill in Compliance Form** and provide additional information about your sending practices.
{% endhint %}
{% hint style="info" %}
**Want to test before your domain is verified?** Skip ahead to [Optional: Test with Email Sandbox](#optional-test-with-email-sandbox) — no domain needed.
{% endhint %}
## Step 4: Send Your First Email
With your SDK installed, API token set, and domain verified, you're ready to send. The examples below use inline HTML for simplicity — for real applications, use [Mailtrap-hosted templates](#step-5-use-email-templates-recommended) instead (see Step 5).
{% tabs %}
{% tab title="Node.js" %}
```typescript
import { MailtrapClient } from "mailtrap";
const client = new MailtrapClient({
token: process.env.MAILTRAP_API_KEY!,
});
await client.send({
from: { email: "hello@yourdomain.com", name: "Your App" },
to: [{ email: "user@example.com" }],
subject: "Welcome!",
text: "Thanks for signing up.",
html: "
"
}'
```
{% endtab %}
{% endtabs %}
## Step 5: Use Email Templates
Use Mailtrap-hosted templates with dynamic variables. Your team can access and edit templates directly in the Mailtrap UI — no code deployments needed. Templates can also be managed via the API.
### Create a template
You can create templates in the Mailtrap UI under [Email API/SMTP → Templates](https://mailtrap.io/email-templates), or via the API:
```bash
curl -X POST "https://mailtrap.io/api/accounts/{account_id}/email_templates" \
-H "Authorization: Bearer $MAILTRAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email_template": {
"name": "Welcome Email",
"subject": "Welcome, {{name}}!",
"category": "Onboarding",
"body_html": "
",
"body_text": "Welcome, {{name}}! Visit {{action_url}} to get started."
}
}'
```
Templates use [Handlebars syntax](https://handlebarsjs.com/) for variables — `{{variable_name}}`.
### Send using a template
To send with a template, you need its UUID:
* **In the UI:** Go to [Email API/SMTP → Templates](https://mailtrap.io/email-templates) and click a template — the UUID is shown in the template details.
* **Via AI / API:** List all templates and their UUIDs with `GET https://mailtrap.io/api/accounts/{account_id}/email_templates`. Your AI assistant can create a template and immediately use the returned UUID to send.
{% tabs %}
{% tab title="Node.js" %}
```typescript
await client.send({
from: { email: "hello@yourdomain.com", name: "Your App" },
to: [{ email: "user@example.com" }],
template_uuid: "your-template-uuid",
template_variables: {
name: "Jane",
action_url: "https://yourdomain.com/activate",
},
});
```
{% endtab %}
{% tab title="cURL" %}
```bash
curl -X POST "https://send.api.mailtrap.io/api/send" \
-H "Authorization: Bearer $MAILTRAP_API_KEY" \
-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": {
"name": "Jane",
"action_url": "https://yourdomain.com/activate"
}
}'
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**AI tip:** Your AI assistant should proactively create a template for your use case at this point — generating the HTML, creating it via the API, and wiring up the sending code that references the template UUID.
{% endhint %}
## Optional: Test with Email Sandbox
Before sending to real users, test your integration with Email Sandbox. Emails go to a virtual inbox instead of real recipients — no domain verification needed. This is useful while waiting for DNS propagation, or as a permanent Sandbox setup for staging/CI.
### Why use the Sandbox?
* Inspect rendered HTML and check responsive design
* Run spam score analysis
* Validate email headers
* Test your integration without risking real deliveries
### Find your Sandbox inbox
Every Mailtrap account comes with a Sandbox inbox. Find your inbox ID:
* **In the UI:** Go to [Sandboxes](https://mailtrap.io/sandboxes) — your inbox ID is shown next to each inbox.
* **Via API:** List your inboxes:
```bash
curl "https://mailtrap.io/api/accounts/{account_id}/inboxes" \
-H "Authorization: Bearer $MAILTRAP_API_KEY"
```
### Use the API for Sandbox (recommended)
The API makes it explicit when you're in Sandbox mode vs. live — reducing the risk of accidentally sending test emails to real users or live emails to your Sandbox.
{% tabs %}
{% tab title="Node.js" %}
```typescript
const client = new MailtrapClient({
token: process.env.MAILTRAP_API_KEY!,
sandbox: true,
testInboxId: Number(process.env.MAILTRAP_INBOX_ID),
});
// Same .send() call — emails land in your Sandbox inbox
await client.send({
from: { email: "hello@yourdomain.com", name: "Your App" },
to: [{ email: "user@example.com" }],
subject: "Test email",
text: "This will go to the Sandbox, not real recipients.",
});
```
{% endtab %}
{% tab title="Python" %}
```python
client = mt.MailtrapClient(
token=os.environ["MAILTRAP_API_KEY"],
sandbox=True,
test_inbox_id=int(os.environ["MAILTRAP_INBOX_ID"]),
)
# Same send call — emails land in Sandbox
client.send(mail)
```
{% endtab %}
{% tab title="cURL" %}
```bash
# Sandbox uses a different base URL
curl -X POST "https://sandbox.api.mailtrap.io/api/send/{inbox_id}" \
-H "Authorization: Bearer $MAILTRAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": {"email": "hello@yourdomain.com", "name": "Your App"},
"to": [{"email": "user@example.com"}],
"subject": "Test email",
"text": "This will go to the Sandbox."
}'
```
{% endtab %}
{% endtabs %}
### View your test emails
* **In the UI:** Go to [Sandboxes](https://mailtrap.io/sandboxes) → click your Sandbox → see all received emails with HTML preview, spam analysis, and headers.
* **Via API:** List messages in your Sandbox:
```bash
curl "https://mailtrap.io/api/accounts/{account_id}/inboxes/{inbox_id}/messages" \
-H "Authorization: Bearer $MAILTRAP_API_KEY"
```
### Safe environment switching
Use an environment variable to control Sandbox vs. live mode. This prevents hardcoding `sandbox: true` in your codebase.
```typescript
// Node.js — environment-based switching
const isSandbox = process.env.MAILTRAP_USE_SANDBOX === "true";
const client = new MailtrapClient({
token: process.env.MAILTRAP_API_KEY!,
sandbox: isSandbox,
testInboxId: isSandbox
? Number(process.env.MAILTRAP_INBOX_ID)
: undefined,
});
```
```bash
# .env.development
MAILTRAP_USE_SANDBOX=true
MAILTRAP_INBOX_ID=12345
# .env.live
MAILTRAP_USE_SANDBOX=false
```
{% hint style="warning" %}
**Avoid common mistakes:**
* Use the **API** (not SMTP) for Sandbox testing — the API uses a distinct base URL (`sandbox.api.mailtrap.io` vs. `send.api.mailtrap.io`) making the environment explicit. With SMTP, you'd need to swap credentials entirely, which is error-prone.
* **Never hardcode** `sandbox: true` in live code. Use environment variables.
* The Sandbox inbox ID is visible in the Mailtrap UI under **Email Sandbox**.
{% endhint %}
{% hint style="info" %}
Full Sandbox guide: [Getting Started with Email Sandbox](/getting-started/email-sandbox)
{% endhint %}
## What's Next?
Now that you're sending emails, explore these capabilities:
* [Tracking Settings](/email-api-smtp/setup/sending-domain#optional-tracking-settings-ffi49) — Enable open and click tracking
* [Webhooks](/email-api-smtp/setup/sending-domain#optional-webhooks-4hmes) — Get real-time delivery event notifications
* [Suppressions](/email-api-smtp/deliverability/suppressions-list) — Manage bounces and unsubscribes automatically
* [Email Logs](https://github.com/mailtrap/mailtrap-docs/blob/main/documentation/email-api-smtp/email-logs.md) — Inspect delivery status for every email
* [Email Templates](https://github.com/mailtrap/mailtrap-docs/blob/main/documentation/email-api-smtp/email-templates.md) — Create and manage templates
* [Email Sandbox](/getting-started/email-sandbox) — Set up Sandbox for your staging environment
{% hint style="info" %}
**Migrating from another provider?** See our migration guides for [SendGrid](https://mailtrap.io/sendgrid-migration/), [Mailchimp](https://mailtrap.io/mandrill-migration/), and [Mailgun](https://mailtrap.io/mailgun-migration/).
{% endhint %}
# Email Sandbox
Learn how to inspect and debug emails with Mailtrap Email Sandbox
Learn how to inspect and debug emails with sandbox functionality.
**What you can do:**
1. Catch testing emails from staging.
2. Preview and analyze content for spam.
3. Validate HTML/CSS before sending emails.
### Good to know
* Your emails won't reach your users as you use our Sandbox SMTP.
* You don't need to verify a domain to use sandbox.
### Overview
{% @arcade/embed url="" flowId="GOawR3yCP4Qi9CT9nkM6" %}
{% stepper %}
{% step %}
**Navigate to Email Sandbox**
Go to [your first Sandbox](https://mailtrap.io/sandboxes) by clicking **Sandboxes**, then My **Sandbox**.
{% hint style="info" %}
By default, we created a sandbox for you and called it "My Sandbox". The Edit button on the far right allows you to rename either a project or a sandbox.
{% endhint %}
Once inside My **Sandbox**, copy the credentials from the **Integration** tab to your clipboard.
Or, use one of the pre-made code snippets for major programming languages and frameworks:
{% endstep %}
{% step %}
**Send your first test email**
After sending the first test email, you can immediately find it in your Mailtrap sandbox.
Click on the email, and proceed to inspect and debug it by selecting the HTML Check tab.
Lastly, you can automate the QA flow with [API](https://docs.mailtrap.io/developers/email-sandbox/send-test-emails) if you need it.
{% endstep %}
{% step %}
**Bonus: Invite your colleagues**
Mailtrap is a collaborative tool. Starting from the [Team Plan](https://mailtrap.io/settings/billing/plans/sandboxes), you can create different sandboxes and projects and share them with your colleagues.
This allows you to organize all testing-related workflows among different people, from user management with different permissions to SSO.
{% endstep %}
{% endstepper %}
### What else you can do with Email Sandbox
* [Enable email per sandbox feature](/email-sandbox/setup/email-address-per-sandbox)
* [HTML or RAW format preview](/email-sandbox/testing/email-template)
* [HTML Check](/email-sandbox/testing/email-html)
* [Automatic Forwarding](/email-sandbox/management/automatic-email-forwarding) and [Manual Forwarding](/email-sandbox/management/manual-email-forwarding) to view emails in real sandboxes
* [Test Bcc and email headers](/email-sandbox/testing/email-headers-and-bcc)
# Email Marketing
Learn how to set up and send email marketing campaigns with Mailtrap
Make sure you've added and [verified a domain](/email-api-smtp/setup/sending-domain), or you won't be able to send a campaign.
### How to set up and send a campaign
{% @arcade/embed url="" flowId="K6tN0H7X2QFnrfLcQeTq" %}
{% stepper %}
{% step %}
Go to **Email Marketing** and click **Create New Campaign**.
{% endstep %}
{% step %}
Choose a domain from the **Select domain** dropdown, then set the **Campaign name**, **Subject**, and **From** email address. Optionally, set the From name, Reply-To name, and Reply-To email. If you have only one domain, no need to choose anything, it's selected for you by default. Click **Continue**.
{% endstep %}
{% step %}
You'll be taken to the Design step, where you can choose between Drag & Drop and HTML editors. If you have templates stored, you'll see them here. You can use them in your campaigns. Read more about creating templates [here](https://github.com/mailtrap/mailtrap-docs/blob/main/documentation/email-api-smtp/email-templates.md).
{% endstep %}
{% step %}
Create your campaign design, click **Save**, and then **Continue**.
{% hint style="info" %}
Instead of continuing to the next step, you can click **Send Test** to send a test to one email address to check the design in your email client or click **Finish Later** to return to the campaign **Details**, where you can change any of the parameters you set in previous steps.
{% endhint %}
{% endstep %}
{% step %}
If you've already imported your contacts, select your audience by including or excluding specific lists. Then, click **Confirm Audience**.
{% hint style="success" %}
With **Including** and **Excluding** features, you can easily send campaigns to specific audience groups only.
{% endhint %}
{% hint style="warning" %}
If you didn't upload your contacts before creating a campaign, you'll be prompted to import contacts at this stage. Simply click **Import Contacts** and follow the steps ([refer to this section](https://github.com/mailtrap/mailtrap-docs/blob/main/documentation/email-marketing/contacts.md#how-to-upload-contacts-nag8y) in our Contacts guide for more details). **Important**: you should create Fields beforehand to be able to assign variables to the fields (map fields) when importing contacts.
{% endhint %}
{% endstep %}
{% step %}
Choose whether to send all emails **at once** or send them **gradually (throttling)** by setting how many emails are sent per hour. For more details, refer to the [email throttling guide.](https://docs.mailtrap.io/email-marketing/campaigns/email-throttling)
{% endstep %}
{% step %}
At this point, you can click **Send Test** to send a test email to one email address, choose **Send now** to send the campaign immediately, or select **Schedule campaign** to send it at a specific date and time.
{% hint style="info" %}
To schedule the campaign, click **Schedule Campaign**, select the date, and choose the time. Then, confirm the action by clicking **Schedule Sending**.
{% endhint %}
{% endstep %}
{% endstepper %}
### What's next?
Once your campaign has been sent, you can check the campaign deliverability data and stats. Here's how to do it:
{% stepper %}
{% step %}
Click **Email Marketing** in the left navigation panel, and you'll have a quick preview of all the campaign data. If we're still collecting the data, you'll be notified accordingly.
{% endstep %}
{% step %}
If you want more details for a particular campaign, click the campaign name, then select the **Reports** tab, where you'll see the full [Statistics report](/email-marketing/campaigns/statistics).
{% endstep %}
{% endstepper %}
# Overview
Overview of Mailtrap Email API and SMTP service: key features, use cases, and target audience.
Mailtrap Email API/SMTP is a reliable email delivery service designed for developers and businesses to send transactional and bulk emails at scale. Whether you're sending password resets, order confirmations, or marketing campaigns, we ensure your emails reach the inbox.
## What is Email API/SMTP?
Email API/SMTP provides two powerful methods for sending emails:
* **RESTful API**: Modern, flexible API for programmatic email sending
* **SMTP Service**: Traditional protocol compatible with any email client or library
Both methods offer the same features, deliverability, and analytics - choose based on your technical requirements.
## Key Features
#### Reliable Delivery
* Enterprise-grade infrastructure: Built for reliability and scale
* Automatic Failover: Redundant systems ensure delivery
* Smart Routing: Optimal rules selection for each email depending on recipient MX
#### Analytics & Monitoring
* Real-Time Analytics: Track opens, clicks, bounces instantly
* Detailed Email Logs: Full visibility into email journey
* Custom Categories: Organize and analyze by type/templates/etc
* Webhook Events: Real-time notifications for email events
#### Deliverability + Support
* Deliverability and Support teams: helps with migration, monitoring and all questions you might have
* [Complete Deliverability Guide](https://mailtrap.io/email-deliverability-guide/): Best practices for optimal inbox placement
* Domain Authentication: SPF, DKIM, DMARC setup
* Dedicated IP + Warmup: Gradual reputation building
* Suppressions Management: Automatic bounce handling
* Feedback Loops: ISP complaint processing
#### Developer-Friendly
* Official SDKs: Node.js, PHP, Python, Ruby, and more
* RESTful API: Simple JSON-based communication
* SMTP Integration: Works with existing email libraries
* Sandbox Testing: Test before production
## Use Cases
#### Transactional Emails
Perfect for critical user communications:
* Password resets and account verification
* Order confirmations and shipping notifications
* Appointment reminders and alerts
* System notifications and updates
* Two-factor authentication codes
#### Bulk Emails
Dedicated infrastructure for marketing:
* Newsletters and announcements
* Promotional campaigns
* Product updates and releases
* Event invitations
* Customer surveys
## Quick Start Guide
{% stepper %}
{% step %}
**Choose Your Integration Method**
{% tabs %}
{% tab title="API" %}
```bash
curl -X POST "https://send.api.mailtrap.io/api/send" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": {"email": "hello@example.com"},
"to": [{"email": "user@example.com"}],
"subject": "Hello from Mailtrap!",
"text": "Welcome to Mailtrap Email API"
}'
```
{% endtab %}
{% tab title="SMTP" %}
```
Host: live.smtp.mailtrap.io
Port: 587
Username: YOUR_USERNAME
Password: YOUR_PASSWORD
Encryption: STARTTLS
```
{% endtab %}
{% tab title="Node.js SDK" %}
```javascript
const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({
token: "YOUR_API_TOKEN"
});
await client.send({
from: { email: "hello@example.com" },
to: [{ email: "user@example.com" }],
subject: "Hello from Mailtrap!",
text: "Welcome to Mailtrap Email API"
});
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Verify Your Domain**
Add DNS records to authenticate your sending domain and improve deliverability.
{% endstep %}
{% step %}
**Start Sending**
Begin with transactional emails, then expand to bulk campaigns as needed.
{% endstep %}
{% endstepper %}
## Two Streams Architecture
Mailtrap separates email traffic for optimal deliverability:
| Stream | Purpose | Features |
| --------------------------------------------- | --------------------- | --------------------------------------------------------------------- |
| **Transactional** | Triggered user emails | High priority, immediate delivery |
| [**Bulk**](/email-api-smtp/setup/bulk-stream) | Marketing campaigns | Built-in compliance, unsubscribe management, separate suppresion list |
## Getting Started
{% columns %}
{% column %}
**Setup & Configuration**
* [Sending Domain Setup](/email-api-smtp/setup/sending-domain)
* [API Integration](/email-api-smtp/setup/api-integration)
* [SMTP Integration](/email-api-smtp/setup/smtp-integration)
* [IP Warmup](/email-api-smtp/deliverability/ip-warmup)
{% endcolumn %}
{% column %}
**Essential Features**
* [Deliverability Guide](https://mailtrap.io/email-deliverability-guide/)
* [Email Templates](/email-api-smtp/email-templates)
* [Analytics & Reports](/email-api-smtp/analytics)
* [Deliverability Features](/email-api-smtp/deliverability)
{% endcolumn %}
{% endcolumns %}
## Why Choose Mailtrap?
**For Developers**
* Clean, well-documented APIs
* Multiple integration options
* Comprehensive SDKs
* Sandbox environment for testing
**For Businesses**
* High deliverability rates
* Detailed analytics and reporting
* Scalable infrastructure
* Enterprise-grade reliability
**For Teams**
* Multi-user access control
* Shared resources and templates
* Collaborative workflows
* Activity logging
## Support & Resources
Need help getting started or have questions?
API ReferenceFAQsTroubleshootingContact Support
## Next Steps
{% stepper %}
{% step %}
[Setup & Configuration](/email-api-smtp/setup)
*Authenticate your sending domain*
{% endstep %}
{% step %}
[API Integration](/email-api-smtp/setup/api-integration)
*Choose integration method - API or SMTP*
{% endstep %}
{% step %}
[Email Templates](/email-api-smtp/email-templates)
*Design reusable emails*
{% endstep %}
{% step %}
[Analytics & Reports](/email-api-smtp/analytics)
*Track your email metrics*
{% endstep %}
{% endstepper %}
# Setup & Configuration
Set up and configure Mailtrap email API and SMTP service and start sending emails in minutes.
Complete guide to setting up and configuring Mailtrap Email API/SMTP for your application. Follow these steps to start sending emails in production.
### Quick start checklist
Get up and running with this essential setup checklist:
* [ ] Create your Mailtrap account
* [ ] Verify your sending domain
* [ ] Choose integration method (API or SMTP)
* [ ] Configure authentication
* [ ] Send your first email
### Configuration steps
Sending Domain Setup
the foundation of email delivery. Verify your domain ownership and configure authentication records (SPF, DKIM, DMARC) for optimal deliverability.
### Choose your integration method
#### When to use API
**Best for:**
* Modern web applications
* Microservices architecture
* Cloud-native applications
* Real-time sending needs
* Advanced analytics requirements
**Advantages:**
* Faster performance
* Better error handling
* Detailed response data
* Webhook support
* Easier debugging
**Example:**
```bash
curl -X POST "https://send.api.mailtrap.io/api/send" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": {"email": "hello@example.com"},
"to": [{"email": "user@example.com"}],
"subject": "Test Email",
"text": "This is a test email"
}'
```
#### When to use SMTP
**Best for:**
* Legacy applications
* Email clients
* CMS platforms
* Standard libraries
* Minimal code changes
**Advantages:**
* Universal compatibility
* No code changes required
* Works with any language
* Familiar protocol
* Easy migration
# Sending Domain Setup
Set up your sending domain in Mailtrap. Add DNS records, verify SPF/DKIM/DMARC, pass compliance, and start sending emails in minutes.
For use with AI assistants
AI-readable resources:
This page as Markdown —
API reference as Markdown —
llms.txt —
llms-full.txt —
For setup with AI assistant follow these steps. Pause and confirm with the user before proceeding at steps marked with ⏸️.
1. Add a sending domain via the Mailtrap API (POST [https://mailtrap.io/api/accounts/{account\_id}/sending\_domains](https://mailtrap.io/api/accounts/%7Baccount_id%7D/sending_domains)) with my domain name.
2. Retrieve the DNS records from the API response — expect 4 CNAME records (domain verification, 2× DKIM, tracking) and 1 TXT record (DMARC).
3. Add the DNS records at my domain registrar. If I give you API credentials for my registrar (Cloudflare, AWS Route 53, etc.), configure them programmatically.
4. Check DNS propagation using dig CNAME \ or a DNS checker tool. DNS can take 15 minutes to 24 hours.
5. Verify the domain via the API (GET [https://mailtrap.io/api/accounts/{account\_id}/sending\_domains/{sending\_domain\_id}](https://mailtrap.io/api/accounts/%7Baccount_id%7D/sending_domains/%7Bsending_domain_id%7D)) or tell me to click Verify DNS Records in Sending Domains ().
6. ⏸️ DNS takes time — test with Sandbox now? While waiting, send a test email to Mailtrap Sandbox so we validate the integration code.
7. ⏸️ Domain verified — send a live email? Once verified, generate sending code using my domain and send a test email.
My domain: \[tell the assistant your domain]
My registrar: \[tell the assistant your DNS provider]
Need help adding DNS records for your specific provider? Check out our detailed step-by-step guides:
### Setting up your domain
{% @arcade/embed url="" flowId="39p36H3XvIxXKeKthmsd" %}
{% stepper %}
{% step %}
**Add domain**
Go to *Sending Domains* in the left navigation panel and click *Add Domain*.
Type in the domain from which you want to send emails and click Add. Remember that you should be the domain owner with access to its DNS records/have someone with access to DNS records.
After this step, you’ll see the Domain Verification page.
{% endstep %}
{% step %}
**Domain verification**
At this stage, you need to verify the domain. You have two options:
* Send domain verification instructions to your admin or developer;
* Or verify the domain yourself if you have access to your domain’s DNS records (your domain provider account).
{% hint style="success" %}
To send instructions to your admin or developer, enter their email address and click Send Instructions.
{% endhint %}
{% endstep %}
{% step %}
**Company / personal information**
After adding your DNS records, click on “Fill in Compliance Form” to complete a short form where you’ll be asked to provide either business or personal information.
Please keep in mind that it’s crucial to provide correct information corresponding to your company registration details. It is important in order to comply with international regulations. This information may also be automatically added to the email footer of promotional emails sent from your domain.
{% hint style="success" %}
Tip: If you've provided this information before, you won't be asked to fill it in again.
{% endhint %}
You can switch between personal and business information only once, meaning that you cannot change it after the form is submitted.
{% endstep %}
{% step %}
**Compliance check**
Compliance check is a process of checking every new domain added to Mailtrap.
Once all the DNS records are successfully verified, your domain will undergo an automatic review. This usually takes a couple of minutes. If your domain is verified at this stage, you’ll see the Verified badge next to your domain and below Compliance Check, and you’ll be able to start sending the emails. You’ll also receive an email informing you that your domain is ready for sending emails.
Some domains may be selected for additional checks. If so, we’ll ask you to fill out a simple Compliance Form and answer a few questions about your business, sending goals, etc. You’ll see a notification under Compliance Check and a link to the form.
We’ll email you if we need additional information from you. If all the checks are successful at this stage, your domain will be verified.
In some cases, your domain may be selected for manual verification. This is the final check before your domain is verified. The length of the manual verification depends on how fast you reply to our emails. If successful, you'll see Verified status. If not, you'll see a Rejected badge next to your domain and a message under Compliance Check. In case of any questions about the reasons for rejection, please contact our support team at .
{% endstep %}
{% endstepper %}
### To verify the domain yourself
{% hint style="info" %}
In the example below, we'll be using GoDaddy.
{% endhint %}
{% stepper %}
{% step %}
Go to your domain provider and locate the domain you've added to Mailtrap.
{% endstep %}
{% step %}
Open the DNS settings and click Add New Record.
{% endstep %}
{% step %}
Return to Mailtrap. On the Domain Verification page, you'll see the DNS records you need to add to your domain provider. These are **Domain Verification**, **DKIM**, **DMARC**, and **Domain Tracking**. You'll need the values under **Type**, **Name**, and **Value**. The naming of these records in Mailtrap is the same as in most domain providers but may differ slightly depending on the provider.
Make sure you check the type next to each record in Mailtrap and choose a relevant one in your domain provider. There are **four CNAME type records** (Domain Verification, DKIM (2), and Custom Tracking Domain) and **one TXT type record** (DMARC).
{% endstep %}
{% step %}
Copy the Name and Value for each record one by one. You can do this by hovering and clicking each record.
{% endstep %}
{% step %}
Paste them into your domain provider.
{% endstep %}
{% step %}
Click Save after adding each record in your domain provider.
{% endstep %}
{% step %}
Repeat the process of copying and pasting for each record until you've added all the Mailtrap DNS records to your domain provider.
{% endstep %}
{% step %}
Then, return to Mailtrap. Some records may be verified immediately, while some may take more time. Mailtrap will check the DNS records automatically every hour, but you can force a check by clicking the Re-check DNS Records button.
{% endstep %}
{% step %}
If you add all the required DNS records correctly, the Status of DNS records will change from Missing to Verified, and the red dots will turn green.
{% endstep %}
{% step %}
Once the DNS records are verified, you’ll be taken to the next step, which is Compliance Check.
**Notes:**
* Some domain providers require a postfix format of the DKIM record. If that’s the case, replace `rwmt1._domainkey` with `rwmt1._domainkey.yourdomain.com` . Repeat the process for `rwmt2._domainkey` , changing the name to `rwmt2._domainkey.yourdomain.com` .
* If you’re asked to set TTL, use the default value as indicated under the TTL field on the Domain Verification page in Mailtrap.
{% endstep %}
{% endstepper %}
### DNS propagation time
After you add or update DNS records, it may take **15 minutes to a few hours** for Mailtrap to detect them.
DNS changes are not applied instantly because:
* DNS records are cached by DNS resolvers according to their TTL (Time To Live).
* There are multiple DNS servers worldwide, and updates need time to propagate across them.
* Even if you can see the updated record using one DNS checker or resolver, it doesn’t necessarily mean that Mailtrap (or other services) can already resolve it from their location.
In most cases, propagation completes within a few hours, but in rare cases it may take up to 24 hours.
#### How to check if your DNS records have propagated
To check if your DNS records have propagated, you have two options:
DNS Checker (automatic)
An easy way to verify whether your DNS records are publicly available is to use [DNS Checker](https://dnschecker.org/), which queries DNS servers worldwide and shows DNS propagation of 6 continents.
To use DNS Checker:
* Go to dnschecker.org and enter your domain name
* Select the record type (e.g., TXT, MX, CNAME, etc.)
* Click **Search**
And here's what your results should look like:
dig command (manual)
You can also verify your DNS records manually with the `dig` command. The `dig` command is a DNS lookup tool available on macOS and Linux (and on Windows via BIND tools) that queries DNS servers and returns the current records for a domain.
To use it, open a terminal and run dig followed by the record type and your domain name. You can also add `+short` for a concise output.
For instance, here's what you can run if you want to check:
* A TXT record (for SPF or domain verification):
```
dig TXT yourdomain.com +short
```
* A specific selector (e.g., DKIM):
```
dig TXT selector._domainkey.yourdomain.com +short
```
* MX records:
```
dig MX yourdomain.com +short
```
* CNAME records:
```
dig CNAME track.yourdomain.com +short
```
**If the correct value is returned in the response**, the record has likely propagated.
**If you see no result or an old value**, the record may still be propagating.
You can also check propagation using different public DNS resolvers:
```
dig TXT yourdomain.com @8.8.8.8 +short # Google DNS
dig TXT yourdomain.com @1.1.1.1 +short # Cloudflare DNS
```
**If the record appears across multiple public resolvers**, it should soon be visible to Mailtrap as well.
**If the records are correctly configured and still not verified after several hours**, double-check:
* Record type (TXT, CNAME, MX, etc.)
* Host/name field (e.g., using `selector._domainkey` instead of the full domain)
* That there are no duplicate or conflicting records
If everything looks correct, please allow additional time for propagation before contacting support.
### (Optional) Tracking settings
An optional step is to change the tracking settings. By default, Mailtrap tracks email opens for each email sent. You can also enable click tracking.
{% hint style="info" %}
*Click tracking* and *custom domain for clicks tracking* are available only for paid accounts.
{% endhint %}
With tracking enabled, you will find the open and click rates in the Analytics reports. [Read this article](https://github.com/mailtrap/mailtrap-docs/blob/main/documentation/statistics/README.md) for a detailed breakdown of Statistics.
1. Navigate to the Tracking Settings tab.
2. Toggle the switch next to Track Opened Emails to enable or disable tracking opens. Mailtrap tracks email opens via an invisible pixel. It’s added to each message sent from your account. When an email is opened, a pixel is loaded, and an ‘open’ event is recorded. Each of these events will be visible in [Email Logs](https://docs.mailtrap.io/email-api-smtp/analytics/logs).
{% hint style="info" %}
Some mailbox providers, browsers, and extensions block invisible pixels. Users can also choose not to display images, or a solution they use to retrieve emails may not support images by default. In each of these cases, an 'open' event won't be recorded even if an email is opened.
{% endhint %}
3. If you're a paid user, toggle the switch next to Track Clicks to enable or disable tracking clicks. If you enable click tracking, the toggle for Custom Domain for Clicks Tracking will be switched on automatically. That way, all links will be redirected through your domain (mt-link.yourdomain.com). And if you verified all the records correctly in Step 2, Domain Tracking will also be verified and ready to use.
### Unsubscribe settings
You can also configure unsubscribe settings.
Unsubscribe links are mandatory for bulk emails as per privacy laws. If your emails don't include an unsubscribe link, Mailtrap will add an Unsubscribe Footer automatically. This is what it will look like:
To add an unsubscribe link anywhere in your template, include this tag in your HTML template: `unsubscribe` . Mailtrap will render a clickable link in your email.
Unsubscribe Footer and Links are optional for transactional emails and are switched off by default.
However, if you want to, you can still add an Unsubscribe Footer to your transactional emails by toggling the switch On under Unsubscribe Footer for Transactional emails or adding an HTML tag mentioned above.
If you’d like, you can mix both approaches: automatically add a footer to emails sent from one domain and do it manually (when applicable) for emails sent from another domain.
If an end-user uses an unsubscribe link, Mailtrap will reject any future emails sent to this address from this particular domain. You can quickly find all such emails in the Email Logs by filtering for the “reject” event.
You will still be able to email them using other domains or subdomains added to your Mailtrap account.
For that reason, it's worth having different domains or subdomains for different types of emails. This way, users can, for example, unsubscribe from your bulk or marketing messages while still receiving vital transactional messages.
### (Optional) Webhooks
Lastly, you can set up webhooks to receive event information almost real-time.
Click the Add New Webhook button, choose the Sending Stream, paste the webhook URL (your endpoint) into the designated field, select the events you want to listen to, and then test the setup.
Mailtrap also allows you to batch up to 500 events within a webhook. That is, group all events under one object, and thus save on computing power.
### Useful tips
After completing the setup process, you can always return to the Sending Domains tab to add any additional domains or subdomains. If you, for example, misspelled a domain, you’ll need to delete it and re-add it with the correct spelling.
{% hint style="info" %}
You can't create any additional demo domains, but you can delete an existing one if needed.
{% endhint %}
Remember that the domain with the Demo badge can be used to send emails only to the email address you registered with.
You can send emails to your recipients only from domains that have a Verified status. If the status is Pending or Rejected, you won't be able to send emails.
From the Sending Domains menu, you can also delete the domains, subdomains, or the demo domain you no longer use. Just press the bin icon next to the domain. This will remove the domain from the list, and you won't be able to send any further emails until you add and verify it again.
Note that removing a domain won't remove it from your Mailtrap account completely. It will still appear, for example, in analytics, and will be displayed with the (deleted) suffix, just like in the example below:
We do this to preserve your historical stats that would otherwise be lost.
# AWS Route 53
Verify your Mailtrap sending domain in AWS Route 53. Add DNS records for DKIM/DMARC verification, pass compliance, and start sending emails.
To start sending emails with Mailtrap, you need to own a domain (e.g., `yourcompany.com`) and then verify your ownership over it. For this, you'll need access to your domain provider account, more specifically, the DNS records management page.
In this guide, you'll learn how to add and verify a domain from AWS Route 53.
This guide assumes your domain uses Route 53's nameservers (e.g., `ns-123.awsdns-12.com` or `ns-456.awsdns-34.net`). This applies whether you registered your domain directly with AWS or just pointed your DNS to Route 53 from another registrar. Not sure? Check your domain registrar's settings or look for where you manage your DNS records. If it's in the AWS Management Console, you're in the right place.
### Step-by-step guide
{% stepper %}
{% step %}
Go to the **AWS Management Console**, type **Route 53** in the search bar, and click on it.
{% endstep %}
{% step %}
Navigate to **Hosted Zone** settings for the domain you've added to Mailtrap.
{% endstep %}
{% step %}
Click the domain you've added to Mailtrap.
{% endstep %}
{% step %}
Return to Mailtrap. On the Domain Verification page, you'll see the DNS records you need to add to AWS Route 53. These are **Domain Verification**, **DKIM**, **DMARC**, and **Domain Tracking**. You'll need the values under **Type**, **Name**, and **Value**.
Make sure you check the type next to each record in Mailtrap and choose a relevant one in AWS Route 53. There are **four CNAME type records** (Domain Verification, DKIM (2), and Custom Tracking Domain) and **one TXT type records** (DMARC).
{% hint style="info" %}
The SPF check for your mail is covered by the domain verification record. There is no need to add a separate SPF record on your sending domain.
{% endhint %}
{% endstep %}
{% step %}
Copy the **Name** and **Value** for each record one by one. You can do this by hovering and clicking each record.
{% endstep %}
{% step %}
Paste the **Name** and **Value** into AWS Route 53. The namings of the records are the same in AWS Route 53 as in Mailtrap.
Use the default value for TTL as indicated in Mailtrap. Click Add another record after adding each record in AWS Route 53.
{% endstep %}
{% step %}
Repeat the process of copying and pasting for each record until you've added all the Mailtrap DNS records to AWS Route 53. Click **Create Records**.
{% endstep %}
{% step %}
Some records may be verified immediately, while some may take more time. Mailtrap will check the DNS records automatically every hour, but you can force a check by clicking the Re-check DNS Records button.
{% endstep %}
{% step %}
If you add all the required DNS records correctly, the **Status** of DNS records will change from Missing to **Verified**, and the red dots will turn green.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
If you have additional questions, [consult AWS documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html) or contact us at .
{% endhint %}
# Cloudflare
Verify your Mailtrap sending domain in Cloudflare. Add DNS records for DKIM/DMARC verification, pass compliance, and start sending emails.
To start sending emails with Mailtrap, you need to own a domain (e.g., `yourcompany.com`) and then verify your ownership over it. For this, you'll need access to your domain provider account, more specifically, the DNS records management page.
In this guide, you'll learn how to add and verify a domain from Cloudflare.
This guide assumes your domain uses Cloudflare's nameservers (e.g., `anna.ns.cloudflare.com` or `bob.ns.cloudflare.com`). This applies whether you registered your domain directly with Cloudflare or just pointed your DNS to Cloudflare from another registrar. Not sure? Check your domain registrar's settings or look for where you manage your DNS records. If it's in Cloudflare's dashboard, you're in the right place.
### Step-by-step guide
{% stepper %}
{% step %}
Open the **Cloudflare dashboard** and select the domain you've added to Mailtrap.
{% endstep %}
{% step %}
Click on the **DNS button** in the left navigation panel. This will open DNS records.
{% endstep %}
{% step %}
Click on the **Add Record** button.
{% endstep %}
{% step %}
On the **Domain Verification page** in Mailtrap, you'll see the DNS records you need to add to Cloudflare. These are **Domain Verification**, **DKIM**, **DMARC**, and **Domain Tracking**. You'll need the values under **Type**, **Name**, and **Value**.
Pay attention to the Type next to each record in Mailtrap and choose a relevant one in Cloudflare. There are **four CNAME type records** (Domain Verification, DKIM (2), and Custom Tracking Domain) and **one TXT type record** (DMARC).
{% hint style="info" %}
The SPF check for your mail is covered by the domain verification record. There is no need to add a separate SPF record on your sending domain.
{% endhint %}
{% endstep %}
{% step %}
Copy the **Name** and **Value** for each record one by one. You can do this by hovering and clicking each record.
{% endstep %}
{% step %}
Paste the the values into Cloudflare. Remember that Cloudflare refers to the Value field as **Target** for **CNAME records** and **Content** for **TXT records**.
{% endstep %}
{% step %}
If you're not using a proxy, make sure you disable it. By default, it will be enabled.
{% endstep %}
{% step %}
Use the default value for **TTL**.
Click **Save** and repeat the process for all the remaining DNS records.
{% endstep %}
{% step %}
Then, **return to Mailtrap**. Some records may be verified immediately, while some may take more time. Mailtrap will check the DNS records automatically every hour, but you can force a check by clicking the Re-check DNS Records button.
{% endstep %}
{% step %}
If you add all the required DNS records correctly, the Status of DNS records will change from **Missing** to **Verified**, and the red dots will turn green.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
If you have additional questions, consult the official [Cloudflare documentation](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/) or contact us at
{% endhint %}
# DigitalOcean
Verify your Mailtrap sending domain in Digital Ocean. Add DNS records for DKIM/DMARC verification, pass compliance, and start sending emails.
To start sending emails with Mailtrap, you need to own a domain (e.g., `yourcompany.com`) and then verify your ownership over it. For this, you'll need access to your domain provider account, more specifically, the DNS records management page.
In this guide, you'll learn how to add and verify a domain from DigitalOcean.
This guide assumes your domain uses DigitalOcean's nameservers (e.g., `ns1.digitalocean.com`, `ns2.digitalocean.com`, or `ns3.digitalocean.com`). This applies whether you registered your domain directly with DigitalOcean or just pointed your DNS to DigitalOcean from another registrar. Not sure? Check your domain registrar's settings or look for where you manage your DNS records. If it's in the DigitalOcean control panel, you're in the right place.
### Step-by-step guide
{% stepper %}
{% step %}
Choose **Networking** in the main menu of the control panel and click the domain you've added to Mailtrap.
You'll see the Create new record heading.
{% endstep %}
{% step %}
On the Domain Verification page in Mailtrap, you'll see the DNS records you need to add to DigitalOcean. These are **Domain Verification**, **DKIM**, **DMARC**, and **Domain Tracking**. You'll need the values under **Type**, **Name**, and **Value**.
{% endstep %}
{% step %}
Check the type next to each record in Mailtrap and choose a relevant one in DigitalOcean (CNAME or TXT). Mailtrap has **four CNAME type records** (Domain Verification, DKIM (2), and Custom Tracking Domain) and **one TXT type record** (DMARC).
{% hint style="info" %}
The SPF check for your mail is covered by the domain verification record. There is no need to add a separate SPF record on your sending domain.
{% endhint %}
{% endstep %}
{% step %}
Copy the **Name** and **Value** for each record one by one. You can do this by hovering and clicking each record.
{% endstep %}
{% step %}
**Paste the values into DigitalOcean**. Remember that DigitalOcean refers to the Name field as Hostname for all record types. For CNAME type records, it refers to the Value field as Is an Alias of.
{% endstep %}
{% step %}
Use the default value for TTL.
Click Create Record after adding each record in DigitalOcean.
{% endstep %}
{% step %}
Repeat the process of copying and pasting for each record until you've added all Mailtrap DNS records to DigitalOcean.
{% endstep %}
{% step %}
Some records may be verified immediately, while some may take more time. Mailtrap will check the DNS records automatically every hour, but you can force a check by clicking the Re-check DNS Records button.
{% endstep %}
{% step %}
If you add all the required DNS records correctly, the Status of DNS records will change from Missing to Verified, and the red dots will turn green.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
If you have additional questions, consult the official [DigitalOcean documentation](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/) or contact us at .
{% endhint %}
# GoDaddy
Verify your Mailtrap sending domain in GoDaddy. Add DNS records for DKIM/DMARC verification, pass compliance, and start sending emails.
To start sending emails with Mailtrap, you need to own a domain (e.g., `yourcompany.com`) and then verify your ownership over it. For this, you'll need access to your domain provider account, more specifically, the DNS records management page.
In this guide, you'll learn how to add and verify a domain from GoDaddy.
This guide assumes your domain uses GoDaddy's nameservers (e.g., `ns1.domaincontrol.com` or `ns2.domaincontrol.com`). This applies whether you registered your domain directly with GoDaddy or just pointed your DNS to GoDaddy from another registrar. Not sure? Check your domain registrar's settings or look for where you manage your DNS records. If it's in the GoDaddy dashboard, you're in the right place.
### Step-by-step guide
{% stepper %}
{% step %}
Go to GoDaddy and locate the domain you've added to Mailtrap.
{% endstep %}
{% step %}
Open the DNS settings and click **Add New Record**.
{% endstep %}
{% step %}
On the Domain Verification page in Mailtrap, you'll see the DNS records you need to add to GoDaddy. These are **Domain Verification**, **DKIM**, **DMARC**, and **Domain Tracking**. You'll need the values under **Type**, **Name**, and **Value**. The naming of these records in Mailtrap is the same as in GoDaddy.
Make sure you check the type next to each record in Mailtrap and choose a relevant one in GoDaddy. There are **four CNAME type records** (Domain Verification, DKIM (2), and Custom Tracking Domain) and **one TXT type record** (DMARC).
{% hint style="info" %}
The SPF check for your mail is covered by the domain verification record. There is no need to add a separate SPF record on your sending domain.
{% endhint %}
{% endstep %}
{% step %}
Copy the **Name** and **Value** for each record one by one. You can do this by hovering and clicking each record.
{% endstep %}
{% step %}
Paste the values into GoDaddy DNS management page.
{% endstep %}
{% step %}
Use the default value for TTL.
Click Save after adding each record in GoDaddy.
{% endstep %}
{% step %}
Repeat the process of copying and pasting for each record until you've added all the Mailtrap DNS records to GoDaddy.
{% endstep %}
{% step %}
Some records may be verified immediately, while some may take more time. Mailtrap will check the DNS records automatically every hour, but you can force a check by clicking the Re-check DNS Records button.
{% endstep %}
{% step %}
If you add all the required DNS records correctly, the Status of DNS records will change from Missing to Verified, and the red dots will turn green.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
If you have additional questions, consult the official [GoDaddy documentation](https://uk.godaddy.com/help/manage-dns-records-680) or contact us at .
{% endhint %}
# Google Cloud DNS
Verify your Mailtrap sending domain in Google Cloud DNS. Add DNS records for DKIM/DMARC verification, pass compliance, and start sending emails.
To start sending emails with Mailtrap, you need to own a domain (e.g., `yourcompany.com`) and then verify your ownership over it. For this, you'll need access to your domain provider account, more specifically, the DNS records management page.
In this guide, you'll learn how to add and verify a domain from Google Cloud DNS.
This guide assumes your domain uses Google Cloud DNS nameservers (e.g., `ns-cloud-a1.googledomains.com` or `ns-cloud-b1.googledomains.com`). This applies whether you registered your domain directly with Google or just pointed your DNS to Google Cloud DNS from another registrar. Not sure? Check your domain registrar's settings or look for where you manage your DNS records. If it's in the Google Cloud Console, you're in the right place.
### Step-by-step guide
{% stepper %}
{% step %}
Go to Google Cloud Console, type **Cloud DNS** in the search bar, and choose it from the results.
{% endstep %}
{% step %}
In the Cloud DNS Zones page, open the **Zone details** for the domain you've added to Mailtrap by clicking on the **Zone name**.
{% endstep %}
{% step %}
Click **Add Standard**.
{% endstep %}
{% step %}
On the Domain Verification page in Mailtrap, you'll see the DNS records you need to add to Google Cloud DNS. These are **Domain Verification**, **DKIM**, **DMARC**, and **Domain Tracking**. You'll need the values under **Type**, **Name**, and **Value**.
Make sure you check the type next to each record in Mailtrap and choose a relevant one in Google Cloud DNS. There are **four CNAME type records** (Domain Verification, DKIM (2), and Custom Tracking Domain) and **one TXT type record** (DMARC). Ignore Google's SPF type record; it's deprecated.
{% hint style="info" %}
The SPF check for your mail is covered by the domain verification record. There is no need to add a separate SPF record on your sending domain.
{% endhint %}
{% endstep %}
{% step %}
Copy the **Name** and **Value** for each record one by one. You can do this by hovering and clicking each record.
{% endstep %}
{% step %}
And paste the values into Google Cloud DNS. Remember that Google Cloud DNS refers to the Name field as DNS Name and the Value field as either Canonical name (for CNAME-type records) or TXT data (for TXT-type records).
When adding TXT-type records, add double quotes in the beginning and the end of the record string in the TXT data field.
{% endstep %}
{% step %}
Use the default value for TTL.
Click **Create** after adding each record in Google Cloud DNS.
{% endstep %}
{% step %}
Repeat the process of copying and pasting for each record until you've added all the Mailtrap DNS records to Google Cloud DNS.
{% endstep %}
{% step %}
Some records may be verified immediately, while some may take more time. Mailtrap will check the DNS records automatically every hour, but you can force a check by clicking the Re-check DNS Records button.
{% endstep %}
{% step %}
If you add all the required DNS records correctly, the Status of DNS records will change from **Missing** to **Verified**, and the red dots will turn green.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
If you have additional questions, consult the official [Google Cloud DNS documentation](https://cloud.google.com/dns/docs/records) or contact us at .
{% endhint %}
# Namecheap
Verify your Mailtrap sending domain in Namecheap. Add DNS records for DKIM/DMARC verification, pass compliance, and start sending emails.
To start sending emails with Mailtrap, you need to own a domain (e.g., `yourcompany.com`) and then verify your ownership over it. For this, you'll need access to your domain provider account, more specifically, the DNS records management page.
In this guide, you'll learn how to add and verify a domain from Namecheap.
This guide assumes your domain uses Namecheap's nameservers (e.g., `dns1.registrar-servers.com` or `dns2.registrar-servers.com`). This applies whether you registered your domain directly with Namecheap or just pointed your DNS to Namecheap from another registrar. Not sure? Check your domain registrar's settings or look for where you manage your DNS records. If it's in the Namecheap dashboard, you're in the right place.
### Step-by-step guide
{% stepper %}
{% step %}
Go to Namecheap, locate the domain you've added to Mailtrap on the dashboard, and click **Manage**.
{% endstep %}
{% step %}
Navigate to the **Advanced DNS** tab.
{% endstep %}
{% step %}
Click **Add New Record**.
{% endstep %}
{% step %}
On the Domain Verification page in Mailtrap, you'll see the DNS records you need to add to Namecheap. These are Domain Verification, DKIM, DMARC, and Domain Tracking. You'll need the values under Type, Name, and Value.
Make sure you check the type next to each record in Mailtrap and choose a relevant one in Namecheap. There are **four CNAME type records** (Domain Verification, DKIM (2), and Custom Tracking Domain) and **one TXT type record** (DMARC).
{% hint style="info" %}
The SPF check for your mail is covered by the domain verification record. There is no need to add a separate SPF record on your sending domain.
{% endhint %}
{% endstep %}
{% step %}
Copy the **Name** and **Value** for each record one by one. You can do this by hovering and clicking each record.
{% endstep %}
{% step %}
And paste the values into Namecheap. Remember that Namecheap refers to the **Name** **field** as **Host**.
{% endstep %}
{% step %}
Use the **default** value for TTL.
{% endstep %}
{% step %}
Repeat the process of copying, pasting, and clicking **Add New Record** for each record until you've added all the Mailtrap DNS records to Namecheap. Click **Save All Changes**.
{% endstep %}
{% step %}
Some records may be verified immediately, while some may take more time. Mailtrap will check the DNS records automatically every hour, but you can force a check by clicking the Re-check DNS Records button.
{% endstep %}
{% step %}
If you add all the required DNS records correctly, the Status of DNS records will change from **Missing** to **Verified**, and the red dots will turn green.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
If you have additional questions, consult the official [Namecheap documentation](https://www.namecheap.com/support/knowledgebase/article.aspx/434/2237/how-do-i-set-up-host-records-for-a-domain/) or contact us at .
{% endhint %}
# Squarespace
To start sending emails with Mailtrap, you need to own a domain (e.g., yourcompany.com) and then verify your ownership over it. For this, you'll need access to your Squarespace account, more specifically, the DNS records management page.
In this guide, you'll learn how to add and verify a domain from Squarespace.
This guide assumes your domain uses Squarespace's nameservers (e.g., `ext-cust.squarespace.com`). This applies whether you registered your domain directly with Squarespace or pointed your DNS to Squarespace from another registrar. Not sure? Check your domain registrar's settings or look for where you manage your DNS records. If it's in the Squarespace Domains panel, you're in the right place.
### Step-by-step guide
{% stepper %}
{% step %}
Log in to your [Squarespace account](https://account.squarespace.com).
{% endstep %}
{% step %}
In the account menu, click **Domains**.
{% endstep %}
{% step %}
Click the domain you want to verify.
{% endstep %}
{% step %}
Click **DNS Settings** and navigate down to **Custom records**.
{% endstep %}
{% step %}
In a separate browser tab, log in to your [Mailtrap account](https://mailtrap.io).
{% endstep %}
{% step %}
Navigate to **Sending Domains** and click on your domain.
{% endstep %}
{% step %}
Open the **Domain Verification** page; you will see a list of DNS records to add.
{% endstep %}
{% step %}
You will need to add the following record types. Here’s the basic field name mapping, see the next step for record-by-record mapping.
| **Mailtrap UI** | **Squarespace UI (CNAME)** | **Squarespace UI (TXT)** |
| --------------- | -------------------------- | ------------------------ |
| Type | Type dropdown | Type dropdown |
| Name | Host | Host |
| Value | Alias Data | Text |
| TTL (Auto) | TTL (leave default) | TTL (leave default) |
| {% endstep %} | | |
{% step %}
Here’s the full record-by-record mapping:
| **Mailtrap Record** | **Squarespace Type** | **Squarespace Host** | **Squarespace Value Field** | **What to paste** |
| --------------------------- | -------------------- | ------------------------------------ | --------------------------- | ---------------------------- |
| Domain Verification (CNAME) | CNAME | Copy Name from Mailtrap | Alias Data | Copy **Value** from Mailtrap |
| DKIM 1 (CNAME) | CNAME | rwmt1.\_domainkey | Alias Data | Copy **Value** from Mailtrap |
| DKIM 2 (CNAME) | CNAME | rwmt2.\_domainkey | Alias Data | Copy **Value** from Mailtrap |
| Custom Tracking (CNAME) | CNAME | mt-link (or whatever Mailtrap shows) | Alias Data | Copy **Value** from Mailtrap |
| DMARC (TXT) | TXT | \_dmarc | Text | Copy **Value** from Mailtrap |
For each record, go back to Squarespace **DNS Settings** → click **Add Record** → select the **Type** (CNAME or TXT) → paste the **Name** and **Value** from Mailtrap → click **Save**.
{% endstep %}
{% step %}
Repeat step 9 for all records listed on your Mailtrap **Domain** **Verification** page.
{% hint style="info" %}
* **Squarespace doesn’t require you to add the SPF record**.
* **Different value field names** - Squarespace calls CNAME values "Alias Data" and TXT values "Text". Mailtrap calls both just "Value".
* **No trailing dot** - If Mailtrap's value ends with a (.), remove it before pasting into Squarespace.
* **Host = subdomain only** - Squarespace auto-appends your domain. If Mailtrap shows rwmt1.\_domainkey.yourdomain.com, enter only rwmt1.\_domainkey.
* **Squarespace does not support CNAME records on the root ( @ ) of the domain**. If a provider’s instructions tell you to create a CNAME with @ as Host, this won’t work on Squarespace. Instead, use a subdomain (for example, www ) for the CNAME and keep an A/ALIAS record on the root, or host your DNS with a provider that supports root‑level CNAME flattening.
{% endhint %}
{% endstep %}
{% step %}
Go back to your Mailtrap **Domain Verification** page.
{% endstep %}
{% step %}
Click **Re-check DNS Records**.
{% endstep %}
{% step %}
Once all records show a green verified status, your domain is verified and ready to send.
{% hint style="info" %}
DNS changes can take **15 minutes to a few hours** to propagate across the internet. In rare cases, propagation may take up to 24 hours. Mailtrap automatically re-checks DNS records every hour, but you can trigger a manual check anytime with the **Re-check DNS Records** button.
{% endhint %}
{% endstep %}
{% endstepper %}
If you have additional questions, consult the official [Squarespace DNS documentation](https://support.squarespace.com/hc/en-us/articles/360001280748) or contact Mailtrap support at .
# API Integration
Integrate Mailtrap email API. Get API credentials, choose transactional or bulk sending, use SDKs or code samples, and start sending.
For use with AI assistants
AI-readable resources:
This page as Markdown —
API reference as Markdown — ,
llms.txt —
llms-full.txt —
SDK repos:\
.NET — \
Elixir — \
Java — \
Node.js — \
PHP — \
Python — \
Ruby —
For setup with AI assistant follow these steps. Pause and confirm with the user before proceeding at steps marked with ⏸️.
1. ⏸️ Ask the user for their tech stack (language/framework) and whether they need transactional emails, bulk emails, or both.
2. ⏸️ Ask the user for their API token, verified sending domain, and "from" email address (must be on the verified domain, e.g. ). If they don't have a token or domain yet, direct them to API Tokens setup () and Sending Domain setup ().
3. Install the appropriate SDK if one is available for the user's stack. Refer to the matching SDK repo above for installation instructions.
4. Generate sending code using the Transactional Stream endpoint (POST ) or Bulk Stream endpoint (POST ) depending on the user's choice in step 1.
5. ⏸️ Send a test email to verify the integration works. Confirm the recipient address with the user before sending.
6. Check that the email appears in the recipient's inbox and in Mailtrap Email Logs ().
My tech stack: \[tell the assistant your language/framework]
My API token: \[paste your token here — only share in a private AI assistant session]
My sending domain: \[your verified domain]
My "from" address: \[e.g. ]
Transactional or bulk: \[tell the assistant which stream you need]
Use API credentials to integrate Mailtrap with your project.
{% @arcade/embed url="" flowId="LyuU7ciMYs6jXmOuDuEW" %}
{% stepper %}
{% step %}
Go to the **Sending Domains** tab and choose the domain you want to send emails from. Remember that you'll be able to start sending emails once the domain is verified.
{% endstep %}
{% step %}
Navigate to the **Integration** tab for your selected domain.
{% endstep %}
{% step %}
Click the **Integrate** button under **Transactional Stream** or **Bulk Stream**.
{% hint style="info" %}
**Transactional Stream** is used to send automated, non-promotional application emails triggered by a specific user action.
**Bulk Stream** is used to send a single marketing campaign to a large group of recipients in bulk.
{% endhint %}
{% endstep %}
{% step %}
Toggle the switch to **API**.
{% endstep %}
{% step %}
Build the authenticated HTTP request in your programming language or framework and configure it with **Mailtrap Host** and **API Token**.
Alternatively, choose the programming language or framework from the menu under **Code Samples** and copy the sample configuration already containing your credentials. In this menu, you'll find official SDKs for [PHP](https://github.com/railsware/mailtrap-php), [Python](https://github.com/railsware/mailtrap-python), [Ruby](https://github.com/railsware/mailtrap-ruby), and [Node.js](https://github.com/railsware/mailtrap-nodejs).
{% hint style="info" %}
Note: For now, only Ruby, PHP (Laravel + Symfony), and Node.js SDKs support Bulk Stream, but others are in development. Request and response examples are also available [here](https://docs.mailtrap.io/developers/email-sending/transactional).
{% endhint %}
{% endstep %}
{% step %}
Complete your script and run it. If you did everything correctly, you should find the sent email in the inbox of the email address you indicated in the script. The email will also appear in **Email Logs** in Mailtrap.
{% endstep %}
{% endstepper %}
Remember that each domain has different API tokens that you can always access by clicking on the desired domain and going to the **Integration** tab.
You can also create additional API tokens by going to **Settings** → **API Tokens** and clicking **Add Token**.
Learn more about API Tokens
Mailtrap Email Sending API supports:
* attachments
* [email templates](https://docs.mailtrap.io/email-api-smtp/email-templates)
* [custom variables](/email-api-smtp/advanced/custom-variables)
* [email categories](/email-api-smtp/analytics/categories)
{% hint style="info" %}
If you need any help with API integration, please, contact our support team at .
{% endhint %}
# API Tokens
Learn how to create, manage, and use API tokens for Email API/SMTP.
For use with AI assistants
AI-readable resources:
This page as Markdown —
API reference as Markdown —
llms.txt —
llms-full.txt —
* The very first API token must be created manually by the user in the Mailtrap UI at — this cannot be done via API.
* Once a token exists, all further token management — creating, resetting, and deleting tokens — can be done programmatically via the API.
* Before creating, ask the user for the token name and desired permissions
* Important: the full token value is only returned on create or reset. Store it securely — it cannot be retrieved again.
#### Add and manage tokens manually
{% @arcade/embed url="" flowId="iWYZTaQURqnQsQBjRPqk" %}
{% stepper %}
{% step %}
Navigate to **Settings** in the menu on the left and select **API Tokens**.
{% endstep %}
{% step %}
To add a new token, click the **Add Token** button in the upper-right corner.
{% endstep %}
{% step %}
**Type the token name** into the designated field.
It’s perfectly fine to have a custom name for the API token, as it’s only for your reference, regardless of the use case.
{% endstep %}
{% step %}
**Assign permissions** by checking the boxes in the corresponding access level columns. Note that you must have admin permissions on a particular domain to send emails with this token.
{% endstep %}
{% step %}
Click the **Save** button and preview the new token under the **API Tokens** main menu.
{% endstep %}
{% endstepper %}
#### Auto-created token per domain
When you create a domain, a token is automatically created and named based on the following formula: \[domain name] + \[token] + \[token ID].
For example, if you add the example.com domain, the token for that domain will be named example.com token 1234. By default, the automatically generated token gets Domain Admin Mailtrap for the given domain.
{% hint style="info" %}
You need to edit permissions for the automatically generated token to allow for authorization on other domains.
{% endhint %}
### Where to find tokens?
Select **Settings** in the left menu, then API Tokens. You’ll see all active tokens, their creator, and their access level.
The automatically assigned token per domain is under the Integration tab in Sending Domains. Choose the desired stream, click Integrate, and toggle the switch to API. You'll see the endpoint (Host) and your API Token.
### Reset token
Go to **Settings** > **API Tokens**, click the three-dot menu icon next to the token you want to reset, and click **Reset API Token**.
Confirm your choice by clicking on the corresponding button.
{% hint style="success" %}
**Tip:** The three-dot menu icon next to the token also allows you to copy a token to your clipboard.
{% endhint %}
{% hint style="warning" %}
**Important notes:**
* After clicking the Reset credentials or Reset API Token buttons, the existing token becomes invalid after 12 hours. So, you have a 12-hour window to update all apps that use the old API token. Once the old token expires, some parts of your application will not work properly unless you've updated the token. All expired tokens get deleted from your account within 24 hours after expiration.
* After the API token is reset and expired, a new token is created. The token ID is added to the token name the same way it's done for automatically generated tokens, e.g., mailtrap.example token 4231.
{% endhint %}
### Edit permissions
As mentioned earlier, click the menu icon at the far right of a token and select **Edit permissions**.
Click on the corresponding boxes to add or remove token permissions. Then, confirm your selection with the **Save** button.
### Delete token
To delete a token, click a three-dot menu icon and choose the **Delete** **token** option.
Confirm the action by clicking the **Confirm** button.
{% hint style="warning" %}
**Important:** Keep in mind that a token is deleted immediately, and you can't delete the last token per domain.
{% endhint %}
# SMTP Integration
Integrate Mailtrap SMTP. Get SMTP credentials, choose transactional or bulk sending, use code samples, and start sending.
Learn how to integrate your application via SMTP.
### Locating your Mailtrap credentials
{% @arcade/embed url="" flowId="Hson2pnGZl4GDpuz7HPz" %}
{% stepper %}
{% step %}
Go to the **Sending Domains** tab and choose the domain you want to send emails from.
Keep in mind that the [domain must be verified](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain) in order for you to start sending emails.
{% endstep %}
{% step %}
Navigate to the **Integrations** tab for your selected domain and select whether you want to use our **Transactional Stream** or [**Bulk Stream**](https://docs.mailtrap.io/email-api-smtp/setup/bulk-stream).
{% hint style="info" %}
**Transactional Stream** is used to send automated, non-promotional application emails that are triggered by the user's specific action.
**Bulk Stream** is used to send a single marketing campaign to a large group of recipients in bulk.
{% endhint %}
{% endstep %}
{% step %}
Once you choose your preferred sending stream, click on **SMTP**. There, you will be able to see your Mailtrap credentials.
{% endstep %}
{% endstepper %}
### Method #1. Manual SMTP configuration
If you're using a tool like WordPress or Salesforce, you can simply copy/paste credentials such as **Host**, **Port**, **Username**, and **Password**. Here are some examples:
{% tabs %}
{% tab title="WordPress" %}
If you want to send emails from WordPress, you can use one of the many plugins (e.g., WP Mail SMTP or Post SMTP). For example, if you are using WP Mail SMTP, you can just navigate to the settings page and insert the Mailtrap credentials there.
{% endtab %}
{% tab title="Salesforce" %}
To send emails from Salesforce, simply add your Mailtrap credentials to your Email Relay configuration, just like so:
{% endtab %}
{% endtabs %}
### Method #2. Copy/pasting code samples
If you have a programming project, you can also copy/paste one of the pre-made code samples for various programming languages and frameworks. For instance:
{% tabs %}
{% tab title="Nodemailer" %}
For Nodemailer, all you need to do is copy/paste the pre-made transporter object from Mailtrap into your main configuration file (i.e., **index.js**).
```javascript
var transport = nodemailer.createTransport({
host: "live.smtp.mailtrap.io",
port: 587,
auth: {
user: "api",
pass: ""
}
});
```
{% endtab %}
{% tab title="Laravel" %}
Similarly, for Laravel, you can just copy the code snippet from Mailtrap into your **.env** file:
```php
MAIL_MAILER=smtp
MAIL_HOST=live.smtp.mailtrap.io
MAIL_PORT=587
MAIL_USERNAME=api
MAIL_PASSWORD=
```
{% endtab %}
{% endtabs %}
### Verifying your configuration
Once you add Mailtrap SMTP to your project, try sending an email from the tool of your choice or the project you're working on. If you did everything correctly, you should find the sent email in the inbox of the email address you indicated in the script. The email will also appear in the [Mailtrap Email Logs](https://docs.mailtrap.io/email-api-smtp/analytics/logs).
Remember that each domain has different SMTP credentials that you can always access by clicking on the desired domain and going to the **Integrations** tab.
You can also create additional API tokens (or SMTP passwords) by going to **Settings** → **API Tokens** and clicking **Add Token**.
Learn more about API Tokens
{% hint style="info" %}
If you need any help with SMTP integration, please, contact our support team at .
{% endhint %}
# Bulk Stream
Integrate Mailtrap Bulk Stream via API or SMTP. Get credentials, use SDKs or code samples, and send promotional emails with built-in compliance features.
## What is Bulk Stream?
Bulk Stream is Mailtrap's dedicated infrastructure for sending marketing, promotional, and non-transactional emails. It's designed to handle high-volume email campaigns while maintaining optimal deliverability and compliance with industry standards.
{% hint style="warning" %}
**Important**: Mailtrap requires you to use the Bulk Stream for all marketing and promotional emails. This separation protects your transactional email reputation and ensures compliance with email provider requirements.
{% endhint %}
## Why Use Bulk Stream?
### Suppression list separation
* **We separate suppression by a stream**. So e.g. you use one domain for both transactional and bulk emails and your recipients unsubscribed from bulk email - it won't affect your transactional email.
### Deliverability Protection
Using separate streams for transactional and bulk emails is critical for maintaining high deliverability:
* **Reputation Isolation**: Marketing emails don't affect your transactional email reputation. Ideally you should use a seperate subdomain/domain for your bulk emails.
* **Different IP Pools**: Dedicated IPs for bulk sending
* **Optimized Routing**: Infrastructure optimized for bulk sending patterns
* **Better Inbox Placement**: Proper categorization by email providers
### Automatic Compliance Features
Mailtrap automatically adds required elements to comply with Google, Yahoo, and other major providers' bulk sending requirements:
* **List-Unsubscribe Headers**: One-click unsubscribe functionality
* **List-Unsubscribe-Post Headers**: RFC 8058 compliance
* **Precedence Headers**: Proper bulk email identification
* **Unsubscribe Links**: Automatic footer unsubscribe links when not present
{% hint style="info" %}
**Google Requirements**: Starting February 2024, Gmail requires authentication, easy unsubscribe, and low spam rates for senders of 5,000+ daily emails. Mailtrap's Bulk Stream automatically handles these requirements.
{% endhint %}
## How to Use Bulk Stream
### Key Differences from Transactional Stream
The main difference from a user perspective is the endpoint/host you use:
| Stream | SMTP Host | API Base URL |
| ------------- | ----------------------- | ---------------------------------- |
| Transactional | `live.smtp.mailtrap.io` | `https://send.api.mailtrap.io/api` |
| Bulk | `bulk.smtp.mailtrap.io` | `https://bulk.api.mailtrap.io/api` |
**Important**: The API structure and calls remain the same - only the domain changes.
### Using with SDKs
Our official SDKs make it easy to switch between streams:
```javascript
// Node.js SDK example
const { MailtrapClient } = require("mailtrap");
// For bulk emails
const bulkClient = new MailtrapClient({
token: "your_api_token",
bulk: true // This flag switches to bulk stream
});
// Send bulk email
await bulkClient.send({
from: { email: "marketing@yourdomain.com" },
to: [{ email: "subscriber@example.com" }],
subject: "Our Monthly Newsletter",
html: "
Newsletter content...
",
category: "newsletter" // Categorize for analytics
});
```
## Setup Instructions
{% stepper %}
{% step %}
**Verify Your Sending Domain**
To use Bulk Stream, first verify a domain you own. Go to the Sending Domains tab and click Add Domain. Type your domain name and confirm with the Add button.
Then, add the DNS records Mailtrap provides to your domain provider.
Check our [Sending Domain Setup Guide](/email-api-smtp/setup/sending-domain) for detailed instructions on adding and verifying your domain.
{% endstep %}
{% step %}
**Integrate Your Application**
**For SMTP Integration**
To send emails via Bulk Stream SMTP, use the bulk-specific credentials:
* **Host**: `bulk.smtp.mailtrap.io`
* **Port**: 587 (or 25, 2525, 465 with SSL)
* **Authentication**: Your stream-specific username and password
See our [SMTP Integration Guide](/email-api-smtp/setup/smtp-integration) for detailed setup instructions.
**For API Integration**
To send via Bulk Stream API, use the bulk endpoint:
* **Base URL**: `https://bulk.api.mailtrap.io/api`
* **Authentication**: Bearer token (same as transactional)
See our [API Integration Guide](/email-api-smtp/setup/api-integration) for implementation details.
{% endstep %}
{% endstepper %}
## Bulk Email Best Practices
### Content Guidelines
* Include valuable, relevant content
* Use clear, honest subject lines
* Avoid spam trigger words
* Include your physical mailing address
* Make unsubscribe prominent and functional
### List Management
* Only send to opted-in subscribers
* Implement double opt-in for new subscribers
* Regularly clean your list of inactive users
* Honor unsubscribe requests immediately
* Never purchase email lists
### Sending Patterns
* Start with small volumes and gradually increase
* Maintain consistent sending patterns
* Avoid sudden volume spikes
* Send at optimal times for your audience
* Monitor engagement metrics
## Compliance Information
### Google & Yahoo Requirements (2024)
Starting February 2024, major email providers require:
1. **Authentication**: SPF, DKIM, and DMARC must be properly configured
2. **Easy Unsubscribe**: One-click unsubscribe must be supported
3. **Low Spam Rate**: Keep spam complaints below 0.3%
4. **Valid DNS Records**: Ensure proper forward and reverse DNS
{% hint style="success" %}
**Automatic Compliance**: Mailtrap's Bulk Stream automatically handles authentication headers, unsubscribe mechanisms, and proper email formatting to meet these requirements.
{% endhint %}
### Who is Considered a Bulk Sender?
According to Google's guidelines:
* Any sender reaching **5,000+ messages** to Gmail accounts within 24 hours
* Counted across all subdomains of your primary domain
* Once classified as bulk sender, the designation is permanent
### What Mailtrap Adds Automatically
When using Bulk Stream, Mailtrap automatically includes:
```
List-Unsubscribe: ,
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Precedence: bulk
```
Plus, if no unsubscribe link is detected in your HTML, we add a compliant footer:
```html
```
## Monitoring and Analytics
### Track Performance
* **Delivery Rate**: Monitor successful deliveries
* **Open Rate**: Track email engagement
* **Click Rate**: Measure content effectiveness
* **Bounce Rate**: Identify delivery issues
* **Spam Complaints**: Stay below 0.3% threshold
* **Unsubscribe Rate**: Monitor list health
### Use Email Categories
Categorize your bulk emails for better analytics:
```javascript
// API example with category
{
"category": "newsletter", // or "promotion", "announcement", etc.
"custom_variables": {
"campaign_id": "summer_2024",
"segment": "active_users"
}
}
```
## FAQ
Can I use the same API token for both streams?
Yes, your API token works for both Transactional and Bulk streams. Only the endpoint URL changes.
What happens if I send marketing emails through the Transactional stream?
This can harm your transactional email deliverability and may result in account warnings. Always use Bulk Stream for marketing emails.
Do I need separate domain verification for Bulk Stream?
No, once your domain is verified in Mailtrap, it works for both streams. However, you might want to use subdomains (e.g., marketing.yourdomain.com) for better reputation management.
How do I handle unsubscribes?
Mailtrap automatically adds unsubscribe headers and can manage suppressions. You can also implement your own unsubscribe handling via webhooks.
What's the sending limit for Bulk Stream?
Limits depend on your plan. Start with gradual volume increases to build reputation. Contact support for high-volume needs.
## Related Resources
* [**Email Deliverability Guide**](https://github.com/mailtrap/mailtrap-docs/blob/main/documentation/email-api-smtp/setup/broken-reference/README.md) - Essential reading for bulk senders
* [Sending Domain Setup](/email-api-smtp/setup/sending-domain)
* [Email Templates](/email-api-smtp/email-templates)
* [Suppressions List](/email-api-smtp/deliverability/suppressions-list)
* [Email Categories](/email-api-smtp/analytics/categories)
* [IP Warmup](/email-api-smtp/deliverability/ip-warmup)
* [Google's Email Sender Guidelines](https://support.google.com/mail/answer/81126)
# Sending Limits
Learn Mailtrap email sending limits: hourly, daily, connection, and email size. Understand what happens when limits are reached and how to upgrade.
When you first sign up for Mailtrap, we limit your throughput to 150 emails an hour. This is a security measure to prevent abusing our system for spam.
You can raise the hourly limit by upgrading to a one of our [paid plans](https://mailtrap.io/pricing/), which starts at 600 or even 800 emails per hour. Later on, our automation will proactively raise your limit if you're nearing it. For an even higher limit, you can submit a request to our support team.
{% hint style="warning" %}
Mailtrap Support team can set hourly limit depending on your needs.
It's a soft limit we are ready to adjust for your depending on your needs and usage.
{% endhint %}
If you try to send more emails than your hourly limit allows, the extra emails will be queued and sent in the next hours.
{% hint style="info" %}
Note: There are no hourly limits for Email Campaigns.
{% endhint %}
## Daily Limits
We have a daily limit of 150 emails/day only for our Free plan, which lets you send up to 4,000 emails per month. Emails sent over this limit will be rejected and won't be sent. There are no daily limits on paid plans.
Need to send more? Upgrade to a paid plan!
## Connection Limits
The maximum number of concurrent SMTP connections **per account** is 10.
If you exceed this limit, you'll get the following error:
```
535 5.7.8 Too many connections per account
```
The maximum number of concurrent SMTP connections **per IP** is 10.
The maximum number of messages per 1 SMTP connection is 100.
{% hint style="success" %}
If those limits are not enough, please let us know by contacting our Support Team. Limits can be adjusted only for paid plans.
{% endhint %}
## Email Size
The maximum allowed size of each email message, including attachments, is 10 MB in all plans by default. In Business and higher plans it's possible to increase size up to 30 MB by contacting our Support team.
# Email Templates
Create and send Mailtrap email templates with drag-and-drop builder or HTML editor, add Handlebars variables, and integrate via API or SMTP.
For use with AI assistants
This page as Markdown —
API reference as Markdown —
llms.txt —
llms-full.txt —
For setup with AI assistant, here is context about Mailtrap Email Templates:
Mailtrap hosts your email templates so you don't need to maintain HTML/CSS in your codebase. Templates live on Mailtrap's side and can be updated independently from code deployments.
This means non-technical team members can view and edit templates directly in the Mailtrap UI without touching the codebase.
Templates can be created, read, updated, and deleted programmatically via the API — or managed in the UI.
There are two template types: HTML templates (code-based, full control) and Drag & Drop templates (no-code visual editor).
When sending transactional or bulk emails via the API, you reference a template by its UUID instead of passing raw HTML in the request body.
Templates support dynamic variables using Handlebars syntax (e.g. {{user\_name}}, {{order\_id}}). Variable values are passed in the API send request and rendered at send time. See the Handlebars guide () for full syntax reference.
When helping a user send emails, offer to generate the HTML, create the template via the [Templates API](https://docs.mailtrap.io/developers/templates/templates.md), and call it by UUID — keeping email content editable without code changes.
### Overview
Email Templates allow you to design, edit, and host HTML email templates, and reference them via API.
By storing the template on Mailtrap and calling it via API, you can easily change the template code without committing to your codebase.
Email Templates support Variables, and Mailtrap uses Handlebars as a template engine.
You can put {{user\_name}} into your template and pass "John" as the "user\_name" value via API.
For a complete guide on using Handlebars with email templates, see [Handlebars Guide](/email-api-smtp/email-templates/handlebars).
### Creating a template
{% @arcade/embed url="" flowId="zUokTdds1algu3QCKhnc" %}
{% stepper %}
{% step %}
Navigate to the **Templates** menu.
{% endstep %}
{% step %}
Click the **Create New Template** button.
{% endstep %}
{% step %}
Click the drop-down menu to select one of your domains, enter the **Template name**, **Subject**, and **Category**, and click **Continue**.
{% endstep %}
{% step %}
Choose the **Drag & Drop Editor** to build the template without coding, or select **HTML Editor** if you prefer to write/modify the code.
{% endstep %}
{% step %}
Create/modify the design and click **Finish**.
The main **Templates** menu features all your saved templates. To quickly access a saved template, just click on it within the main menu.
{% endstep %}
{% endstepper %}
Limitations
Each account can have up to 200 email templates.
### Managing templates
#### List of templates and user permissions
Clicking on Templates in the side menu lists all the templates you can access. Access to templates is managed on a domain level. You need to have Admin access to a domain to manipulate the templates. In case you don't have Edit rights, you can't change the template.
{% hint style="warning" %}
You can delete a template. However, this action is irreversible, so be sure to change the sending/testing code after deletion. When the template is deleted, the UUID is also deleted, and Mailtrap won't be able to render it.
{% endhint %}
### Next steps
* [Editing and Customizing Templates](/email-api-smtp/email-templates/editing-and-customizing) - Learn how to customize templates with the Drag & Drop or Code Editor
* [Handlebars Guide](/email-api-smtp/email-templates/handlebars) - Complete guide to using Handlebars syntax in templates
* [Integration](/email-api-smtp/email-templates/integration) - Integrate templates with Email API/SMTP
* [Debugging](/email-api-smtp/email-templates/debugging) - Test templates with Email Sandbox
# Editing and Customizing
Learn how to edit and customize email templates using Details, Drag & Drop Editor, Code Editor, and test your templates.
### Details
Each template must have a name, subject, category, and assigned domain. The subject also supports variables.
Template details section
### Drag & Drop Editor
The drag-and-drop editor allows you to design templates without any coding.
Drag and Drop Editor
### Code Editor
Code Editor allows you to edit the HTML or Text content, depending on the emails you want to send.
The editor supports Find and Replace options, and you can use Cmd+F or Win+F as a hotkey to reveal a quick search bar.
If your template has an error, Handlebars cannot render it. You'll see an error message in the Preview tab, and the RAW code with an error will be highlighted in the Editor.
You can't save a template with errors, either. Remember that we don't validate HTML.
### **Uploading an image**
{% @arcade/embed url="" flowId="mgejv3R4azE0EEdylDVU" %}
{% stepper %}
{% step %}
Click Upload image in the upper right corner of the Code Editor.
{% endstep %}
{% step %}
Hit the Upload New button in the following menu and choose an image from your local drive (Supported formats are JPG, PNG, and GIF, and the maximum file size is 2 MB).
{% endstep %}
{% step %}
Once the image is uploaded, you will receive a confirmation notification. If the file format is unsupported or the image is too big, you will receive the corresponding error message.
{% endstep %}
{% step %}
Click the Copy URL button to copy the image URL to your clipboard, then click Template to return to the editing menu.
{% endstep %}
{% step %}
Proceed to add the image to the template body under the `` tag. You can preview it in the template as soon as the asset is added.
{% endstep %}
{% endstepper %}
### **Test Data**
Code Editor automatically parses your template and shows all the variables found. The Test Data tab helps you preview the object variables.
Test Data tab with template variables
By default, as a value, we put a variable name and add the "Test\_" prefix.
### Send test
If you're using email templates in production, you can send a test email to the account owner's email address to run basic tests. Simply press the Send Test button.
Send Test button
Important Notes:
* Your domain should be verified to send a test.
* Each test email is billed over your quota.
### Next steps
* [Handlebars Guide](/email-api-smtp/email-templates/handlebars) - Learn how to use Handlebars syntax to add dynamic content
* [Integration](/email-api-smtp/email-templates/integration) - Integrate templates with Email API/SMTP
* [Debugging](/email-api-smtp/email-templates/debugging) - Test templates with Email Sandbox
# Handlebars Guide
Complete guide to using Handlebars templating language with Mailtrap Email Templates, including syntax examples, helpers, and practical use cases.
Mailtrap Email Templates support the Handlebars templating language. It combines an input object (JSON) and a template to create text formats, HTML, or an email subject.
You can use Handlebars syntax to personalize your email templates and insert specific information for each of your recipients.
For instance, you may have a client business name called "business name" under a JSON object property. Then, using `{{business name}}` Handlebars expression somewhere in the template, you can insert the property value to an email template.
The main benefit of using this syntax is that you don't have to update your code base. The dynamic templating happens fast and outside the code base.
### Supported Handlebars features
Handlebars supports a bunch of features, not just the variable replacement. Mailtrap templates support the standard set of helpers:
* **Basic replacement**
* **Conditional statements**: `{{#if}}`, `{{#unless}}`, `{{#each}}`, and `{{#with}}`
The following sections give you examples for each of the helpers including code blocks, mock JSON data, and HTML output.
### Basic replacement
The basic usage is just to render the values you pass. You can use objects and refer to variables like `{{object_name.variable}}`.
If the variable is present in the data you pass, it won't be rendered.
If you want to do a replacement with HTML, use triple brackets `{{{value_with_html}}}`.
**Template**
```html
```
### **Special characters in subject lines**
If your subject line variable contains special characters (e.g. &, <, >, ", '), use triple braces `{{{ }}}` instead of double braces `{{ }}` in your template subject.
Double braces escape special characters into HTML entities, which works fine in the email body but shows raw entity codes in the subject line.
### Conditional Statements
#### if / else / if else
Use the `if` helper for conditional block rendering.
{% hint style="info" %}
Should the argument return `""`, `0`, `nil`, `false`, `empty_map`, `empty_slice`, or an `empty_array`, then the block won't be rendered.
{% endhint %}
**Template**
```html
{{#if user.isSubscribed}}
Hello {{user.name}},
Thank you for subscribing to our newsletter!
{{else}}
Hello {{user.name}},
We noticed that you have not yet subscribed to our newsletter. Click here to subscribe.
```
If you change the `isSubscribed` variable to `false` in JSON data, the HTML output is:
```html
Hello Jane Doe,
We noticed that you have not yet subscribed to our newsletter. Click here to subscribe.
```
{% hint style="info" %}
The examples above include both `if` and `else` expressions. Of course, you can use only `if`, but it's recommendable to include `else` as well to cover the scenario where a conditional statement is `false`.
{% endhint %}
#### unless
The `unless` block helper works like an inverse `if`. Simply put, it renders when the expression returns a `false` value.
**Template**
```html
{{#unless user.isSubscribed}}
Hello {{user.name}},
We noticed that you have not yet subscribed to our newsletter. Click here to subscribe.
We noticed that you have not yet subscribed to our newsletter. Click here to subscribe.
```
The block helper example also contains `{{else}}` and should the `isSubscribed` variable be `true`, here's the HTML output:
```markup
Hello Jane Doe,
Thank you for subscribing to our newsletter!
```
#### each
The `{{#each}}` helper is used to iterate over an object or array, then execute a block of code for each item.
In the example below, `{{#each user.items}}` iterate over the `user.items` array, then execute the code inside the block.
{% hint style="info" %}
`{{this}}` helper is used as a reference to the current item in the iteration.
{% endhint %}
**Template**
```html
{{#each user.items}}
```
#### with
You can use the `with` helper to change the context in which the code block gets executed.
In the example below, the `{{with user}}` block sets the context for the user object. Consequently, the `{{name}}` and `{{email}}` can be accessed directly. This is useful when you want to avoid writing long chains of nested property accessors.
**Template**
```html
{{#with user}}
```
**Template with else block**
In the example below, the `{{else}}` clause only gets executed if there's no value within the `{{with}}` block.
```markup
{{#with user}}
```
### Example: Order confirmation template
The following example contains the majority of Handlebars helpers explained above as well as mock JSON data, and HTML output.
**Email template in HTML:**
```html
Order Confirmation
Hello {{customer.name}},
Thank you for your order! Your order number is {{order.number}}.
Thank you for your order! Your order number is 123456.
Your order details are:
Product
Quantity
Price
Product 1
1
$10
Product 2
2
$20
Shipping to:
My company
John Smith
123 Main St
Anytown, State ZIP
USA
Your order will be shipped within 24 hours.
Total: $50
Thank you for shopping with us!
```
### Testing templates with Handlebars
In the quick tutorial below, we assume you've activated both Email Sandbox and Email API/SMTP.
{% stepper %}
{% step %}
Navigate to **Email API/SMTP** > **Email Templates** in the menu on the left.
{% endstep %}
{% step %}
Select your email template and click the **Integration** tab.
{% endstep %}
{% step %}
Copy the code under the **Integration** tab (cURL, or any other based on your preference).
To test the template, you only need to change the Sending API endpoint ([send.api.mailtrap.io](http://send.api.mailtrap.io/)) to Sandbox API ([sandbox.api.mailtrap.io](http://sandbox.api.mailtrap.io/)) and add the `inbox_id` to the end of the endpoint URL.
{% endstep %}
{% step %}
Run the template test and check the associated inbox to preview the template under sandbox.
{% endstep %}
{% endstepper %}
**Important notes:**
* Pay attention that the `Authorization: Bearer` (API token) token is related to the Inbox you're targeting. You can check (and copy-paste) the token under Settings > API Tokens.
* Your `inbox_id` is in the Inbox URL.
For more details on template debugging, see [Debugging](/email-api-smtp/email-templates/debugging).
# Integration
Learn how to integrate Mailtrap email templates with Email API/SMTP using Transactional or Bulk streams.
### Overview
Once you've created and customized your email template, you can integrate it with your application using the Email API or SMTP. This guide shows you how to get the necessary credentials and code samples to send emails using your templates.
### Integration steps
{% @arcade/embed url="" flowId="o6ZYucIUk0B04K4hWaQy" %}
{% stepper %}
{% step %}
Navigate to Templates in the menu on the left.
{% endstep %}
{% step %}
Click the template you want to call using the API.
{% endstep %}
{% step %}
Open the Integration tab.
{% endstep %}
{% step %}
With Email API/SMTP toggled on, click Integrate under Transactional Stream or Bulk Stream.
{% endstep %}
{% step %}
Copy the necessary credentials, such as Host, API Token, and Template UUID.
{% endstep %}
{% step %}
Alternatively, under Code Samples, choose the desired language and copy the sample configuration already containing the necessary credentials. Mailtrap's official SDKs ([Node.js](https://github.com/railsware/mailtrap-nodejs), [Python](https://github.com/railsware/mailtrap-python), [PHP](https://github.com/railsware/mailtrap-php), and [Ruby](https://github.com/railsware/mailtrap-ruby)) also support the templates feature.
{% endstep %}
{% step %}
Paste the code into your project and customize it if needed. Then, run the code to send an email to the email address you indicated in your script.
For more details, [open the API docs](https://docs.mailtrap.io/developers) and go to Email Sending API → Emails → Send email (including template) for transactional stream and Bulk Sending API → Emails → Send email (including template) for bulk stream. Under Body, click the dropdown menu, and choose `EmailFromTemplate`.
{% endstep %}
{% endstepper %}
# Debugging with Sandbox
Learn how to test and debug your email templates using Mailtrap Email Sandbox.
### Overview
Before sending your email templates to production, it's important to test them in a safe environment. Mailtrap Email Sandbox allows you to test your templates, preview how they render, and verify that all variables are working correctly.
### Debugging steps
{% stepper %}
{% step %}
Navigate to Templates in the menu on the left.
Navigate to Templates
{% endstep %}
{% step %}
Click the template you want to call using the API.
Select template to debug
{% endstep %}
{% step %}
Open the Integration tab.
Open Integration tab
{% endstep %}
{% step %}
Toggle the switch to Email Testing.
Toggle to Email Testing
{% endstep %}
{% step %}
And click Integrate.
Click Integrate for Testing Inbox
{% endstep %}
{% step %}
Select the desired sandbox from the dropdown menu to reveal its credentials. Copy the Host, API Token, Template UUID, and Sandbox ID.
Alternatively, you can also use one of the pre-made Code Samples.
Sandbox credentials and code samples
{% endstep %}
{% step %}
Paste the code into your project and customize it if needed. Then, run the code to send an email to the selected Email Testing sandbox.
{% endstep %}
{% step %}
Finally, check the sandbox you specified in the script.
Test email received in sandbox
The Tech Info tab contains the link to the template you tested and lists all the variables used in the template.
Tech Info tab with template details
For more details, [open the API docs](https://docs.mailtrap.io/developers) and go to [Sandbox API](https://docs.mailtrap.io/developers/email-sandbox/send-test-emails) → Test Emails → Send email (including templates). Under Body, click the dropdown menu, and choose `EmailFromTemplate`.
{% endstep %}
{% endstepper %}
# Migrate templates
Mailtrap uses Handlebars as its template engine. If your current provider also uses Handlebars (SendGrid, Mailgun, Amazon SES), most of your template markup ports directly. If your provider uses a different syntax (Brevo, Postmark, Mandrill with merge tags), you will need to convert your templates before importing them.
This guide walks you through the full migration process: exporting templates from your current provider, converting syntax where needed, creating templates in Mailtrap, and updating your send calls.
{% hint style="info" %}
Mailtrap supports up to 200 email templates per account. If you are migrating a larger template library, prioritize your highest-traffic templates first.
{% endhint %}
### Prerequisites
Before you start, make sure you have:
* A Mailtrap account with access to [Email Templates](/email-api-smtp/email-templates)
* A [verified sending domain](/email-api-smtp/setup/sending-domain) set up in Mailtrap
* An API token with Admin access to the account or domain you use for templates. See [API Tokens](/email-api-smtp/setup/api-tokens)
* Your existing templates exported as HTML from your current provider
### Step 1: Export your templates
Copy the HTML source of each template you want to migrate. You need the raw HTML, subject line, and any metadata (name, category) for each template.
How you export depends on your provider:
* SendGrid: Open a template in the Design Editor, switch to the Code Editor tab, and copy the HTML. Or use the `GET /v3/templates/{template_id}` API endpoint.
* Mailgun: Open the template in the Mailgun dashboard, copy the HTML from the editor. Or use the Templates API to list and retrieve templates.
* Mandrill: Navigate to Outbound > Templates, open a template, and copy the HTML source. Or use the `POST /api/1.0/templates/info.json` endpoint.
* Postmark: Open the template in the Postmark dashboard and copy the HTML. Or use `GET /templates/{templateId}` via the API.
* Brevo: Open the template editor in Brevo, switch to the HTML view, and copy the source. Or use `GET /v3/smtp/templates/{templateId}` via the API.
* Amazon SES: Use the `GetTemplate` API action or the AWS CLI (`aws sesv2 get-email-template --template-name your-template`).
If you have many templates, scripting the export via API is faster than copying manually.
### Step 2: Convert template syntax to Handlebars
Mailtrap supports these standard Handlebars features:
* `{{variable_name}}` - variable insertion
* `{{object.property}}` - nested/dot notation access
* `{{{variable}}}` - unescaped HTML (triple braces)
* `{{#if}}` / `{{else}}` / `{{/if}}` - conditionals
* `{{#unless}}` / `{{/unless}}` - inverse conditionals
* `{{#each}}` / `{{/each}}` - iteration over arrays
* `{{#with}}` / `{{/with}}` - context switching
Mailtrap does not support custom helpers like `formatDate`, `greaterThan`, `lessThan`, `and`, `or`, or `length`. If your templates use any of these, move that logic to your application and pass the result as a template variable.
Skip to the section for your current provider below. If your provider uses standard Handlebars, you can go straight to Step 3.
From SendGrid
SendGrid and Mailtrap both use Handlebars. Basic variable insertion (`{{variable}}`), conditionals (`{{#if}}`), iteration (`{{#each}}`), and unescaped HTML (`{{{variable}}}`) work the same way on both platforms. The differences are in helper functions and default value syntax.
**What needs to change**:
| Pattern | SendGrid | Mailtrap |
| ---------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Default/fallback value | `{{insert name "default=Customer"}}` | `{{#if name}}{{name}}{{else}}Customer{{/if}}` |
| Date formatting | `{{formatDate timestamp "MMMM DD, YYYY"}}` | Not supported - format dates server-side and pass as a string variable |
| Comparison helpers | `{{#greaterThan a b}}, {{#lessThan a b}}, {{#notEquals a b}}` | Not supported - compute in your application and pass a boolean |
| Logical operators | `{{#and condition1 condition2}}, {{#or condition1 condition2}}` | Not supported - evaluate in your application |
**Before (SendGrid)**:
```handlebars
Hello {{insert firstName "default=Customer"}},
Your order was placed on {{formatDate orderDate "MMMM DD, YYYY"}}.
Your order was placed on {{formatted_order_date}}.
{{#if qualifies_for_free_shipping}}
You qualify for free shipping.
{{/if}}
```
In this example, `formatted_order_date` and `qualifies_for_free_shipping` are computed in your application and passed as template variables.
From Mailgun
Mailgun and Mailtrap both use Handlebars. Your template markup works in Mailtrap without syntax changes.
The only differences are on the API side:
| Field | Mailgun | Mailtrap |
| ------------------- | ---------------------------------------- | ---------------------------------- |
| Template identifier | `template` (string name) | `template_uuid` (UUID) |
| Template variables | `t:variables` (JSON string in form data) | `template_variables` (JSON object) |
| Template versioning | `t:version` parameter | Not supported |
{% hint style="info" %}
Mailgun’s batch sending uses `%recipient.varname%` placeholders, which is a separate system from Handlebars templates. Mailtrap does not support this syntax. For batch sends, use the bulk endpoint (`bulk.api.mailtrap.io/api/send`) with individual `template_variables` per message.
{% endhint %}
From Mailchimp Transactional
Mailchimp Transactional supports two template syntaxes. Check the `merge_language` field in your send calls to determine which one your templates use.
If your templates use Handlebars (`merge_language: "handlebars"`): Copy the HTML into Mailtrap as-is. No markup changes needed.
If your templates use Mailchimp merge tags (`merge_language: "mailchimp"` or no `merge_language` set): Convert the syntax to Handlebars.
| Mailchimp merge tag | Handlebars equivalent |
| ------------------------------------------------------------------ | --------------------------------------------------------- |
| `*\|FNAME\|*` | `{{fname}}` |
| `*\|IF:FNAME\|*...content...*\|END:IF\|*` | `{{#if fname}}...content...{{/if}}` |
| `*\|IF:FNAME\|*...content...*\|ELSE:\|*...fallback...*\|END:IF\|*` | `{{#if fname}}...content...{{else}}...fallback...{{/if}}` |
**Additional changes**:
* **Editable regions**: Mailchimp’s `mc:edit` regions (filled via `template_content` in the API) have no equivalent in Mailtrap. Replace them with Handlebars variables in your template markup.
* **Variable format**: Mailchimp uses arrays of `{"name": "var", "content": "value"}` objects, split into `global_merge_vars` (all recipients) and `merge_vars` (per-recipient). Mailtrap uses a flat `template_variables` object.
**Mailchimp Transactional variable format:**
```hbs
"global_merge_vars": [
{"name": "company", "content": "Acme Inc"},
{"name": "year", "content": "2026"}
],
"merge_vars": [
{
"rcpt": "recipient@example.com",
"vars": [{"name": "first_name", "content": "Jane"}]
}
]
```
**Mailtrap variable format**:
```handlebars
"template_variables": {
"company": "Acme Inc",
"year": "2026",
"first_name": "Jane"
}
```
If you use per-recipient variables via `merge_vars`, map them to Mailtrap `template_variables` per message. For large sends, use the bulk sending flow instead of sending one API call per recipient.
From Postmark
Postmark uses Mustachio, a Mustache-inspired engine. The syntax is close to Handlebars but not identical.
**What needs to change**:
| Pattern | Postmark (Mustachio) | Mailtrap (Handlebars) |
| ------------------ | ----------------------------------- | ------------------------------------------------------------------ |
| Truthy conditional | `{{#var}}...{{/var}}` | `{{#if var}}...{{/if}}` |
| Falsy conditional | `{{^var}}...{{/var}}` | `{{#unless var}}...{{/unless}}` or `{{#if var}}{{else}}...{{/if}}` |
| Variable insertion | `{{variable}}` | `{{variable}}` (no change) |
| Iteration | `{{#each items}}...{{/each}}` | `{{#each items}}...{{/each}}` (no change) |
| Unescaped HTML | `{{{variable}}}` or `{{&variable}}` | `{{{variable}}}` |
**Before (Postmark)**:
```html
{{#name}}
{{/if}}
```
**Additional changes**:
* **Inline CSS**: If you rely on Postmark’s `InlineCss` flag, you will need to inline CSS in your HTML before uploading to Mailtrap. Use a build tool like [juice](https://github.com/Automattic/juice) to handle this.
* **API fields**: Change `TemplateId` or `TemplateAlias` to `template_uuid`, and `TemplateModel` to `template_variables`.
From Brevo
Brevo uses the Brevo Template Language (based on Pongo2/Django syntax). The `{{ }}` delimiters look similar to Handlebars, but the syntax is not compatible. You will need to rewrite your templates.
Conversion reference:
| Pattern | Brevo (Pongo2/Django) | Mailtrap (Handlebars) |
| ------------------ | ----------------------------------------------------------- | ------------------------------------------ |
| Variable insertion | `{{ params.variableName }}` | `{{variableName}}` |
| Nested access | `{{ params.order.item.name }}` | `{{order.item.name}}` |
| Conditionals | `{% if params.var %}...{% else %}...{% endif %}` | `{{#if var}}...{{else}}...{{/if}}` |
| Iteration | `{% for item in params.items %}{{ item.name }}{% endfor %}` | `{{#each items}}{{this.name}}{{/each}}` |
| Default/fallback | `{{ params.name \| default:"there" }}` | `{{#if name}}{{name}}{{else}}there{{/if}}` |
| Unescaped HTML | `{{ variable }}` (no escaping by default) | `{{{variable}}}` (triple braces) |
| Date formatting | `{{ params.date \| date:"Y-m-d" }}` | Not supported — format dates server-side |
**Before (Brevo)**:
```html
{% if params.hasOrder %}
{{/each}}
{{/if}}
```
From Amazon SES
Amazon SES and Mailtrap both use Handlebars. You can copy your template HTML into Mailtrap without any syntax changes.
The differences are on the API side:
| Field | Amazon SES | Mailtrap |
| ------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------- |
| Template identifier | `TemplateName` (string, max 64 chars) or `TemplateArn` | `template_uuid` (UUID) |
| Template variables | `TemplateData` (escaped JSON string, e.g. `"{\"name\": \"John\"}"`) | `template_variables` (standard JSON object) |
| Inline templates | Supported via `TemplateContent` (no pre-storage needed) | Not supported - templates must be created in Mailtrap first |
{% hint style="info" %}
SES requires `TemplateData` as a double-encoded JSON string. Mailtrap accepts `template_variables` as a regular JSON object, which simplifies your send calls.
{% endhint %}
### Step 3: Create templates in Mailtrap
Once your template HTML is ready and converted to Handlebars, create the templates in Mailtrap.
#### Use the Mailtrap UI
1. Navigate to **Email API/SMTP** → **Email Templates**.
2. Click **New Template**.
3. Choose an editor:
* **Drag & Drop Editor** - build templates visually without code
* **HTML Editor** - paste your converted HTML directly
4. Enter the **Template name**, **Subject**, and **Category**.
5. Paste your converted HTML into the editor.
6. Save the template. The template UUID appears in the template details. You will need it for your send calls.
#### Using the Templates API
To create a template programmatically, send a POST request to the Templates API. This is useful when migrating multiple templates at once.
**Create a template**:
```bash
curl --request POST \
--url https://mailtrap.io/api/accounts/{account_id}/email_templates \
--header 'Api-Token: YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"email_template": {
"name": "Welcome Email",
"subject": "Welcome to {{company_name}}!",
"category": "onboarding",
"body_html": "
Welcome {{user_name}}!
Thanks for signing up.
",
"body_text": "Welcome {{user_name}}! Thanks for signing up."
}
}'
```
Replace `{account_id}` with your Mailtrap account ID (found in the URL when you log in: `https://mailtrap.io/accounts/{account_id}/...`), and `YOUR_API_TOKEN` with your API token.
The response includes the template `uuid`, which you will use in your send calls:
```bash
{
"id": 123,
"uuid": "b81aabcd-1a1e-41cf-91b6-eca0254b3d96",
"name": "Welcome Email",
"category": "onboarding",
"subject": "Welcome to {{company_name}}!",
"body_html": "
"
}
}'
```
Only include the fields you want to change. All fields are optional on update.
**Delete a template**:
```bash
curl --request DELETE \
--url https://mailtrap.io/api/accounts/{account_id}/email_templates/{email_template_id} \
--header 'Api-Token: YOUR_API_TOKEN'
```
{% hint style="warning" %}
**Warning**: Template deletion is permanent and cannot be undone. Any send calls referencing the deleted template’s UUID will fail.
{% endhint %}
### Step 4: Update your send calls
After creating your templates in Mailtrap, update the API calls in your application to reference the new template UUIDs and pass variables in Mailtrap’s format.
**Send an email with a template**:
```bash
curl --request POST \
--url https://send.api.mailtrap.io/api/send \
--header 'Authorization: Bearer YOUR_MAILTRAP_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"from": {
"email": "sender@yourdomain.com",
"name": "Your App"
},
"to": [
{
"email": "recipient@example.com",
"name": "Jane Doe"
}
],
"template_uuid": "b81aabcd-1a1e-41cf-91b6-eca0254b3d96",
"template_variables": {
"user_name": "Jane Doe",
"order_number": "12345"
}
}'
```
When you use `template_uuid`, the subject, HTML body, and text body come from the template.
**Quick reference for API field changes**:
| **Provider** | **Old template field** | **Old variables field** | **Mailtrap template field** | **Mailtrap variables field** |
| ------------ | ------------------------------- | ------------------------------------------ | --------------------------- | ---------------------------- |
| SendGrid | `template_id (e.g. d-abc123)` | `personalizations[].dynamic_template_data` | `template_uuid` | `template_variables` |
| Mailgun | `template` (name string) | `t:variables` (JSON string) | `template_uuid` | `template_variables` |
| Mandrill | `template_name` (slug) | `global_merge_vars + merge_vars` | `template_uuid` | `template_variables` |
| Postmark | `TemplateId` or `TemplateAlias` | `TemplateModel` | `template_uuid` | `template_variables` |
| Brevo | `templateId` (integer) | `params` | `template_uuid` | `template_variables` |
| Amazon SES | `TemplateName` or `TemplateArn` | `TemplateData` (escaped JSON string) | `template_uuid` | `template_variables` |
### Step 5: Test with Email Sandbox
Before sending to real recipients, test your migrated templates in [Email Sandbox](/email-sandbox/overview) to verify they render correctly.
1. Point your application’s SMTP or API configuration to your sandbox inbox.
2. Trigger a send for each migrated template.
3. Check the following in the sandbox inbox:
* Variable substitution works correctly (no raw `{{variable}}` tags visible)
* Conditionals and loops render the expected content
* HTML layout and styling match your original templates
* Plain text version is readable
This lets you catch conversion issues before they reach real recipients.
### Tips
* **Start with your highest-traffic templates.** Migrate the templates that handle password resets, order confirmations, and welcome emails first.
* **Keep your old provider running in parallel.** Send from both providers during migration to avoid downtime, then cut over once all templates are verified.
* **Use the Templates API for bulk migration.** If you have many templates, script the creation process instead of using the UI. Read the full [API documentation](https://api-docs.mailtrap.io/) for details.
* **Format dates and computed values server-side.** Mailtrap’s Handlebars does not include date formatting or comparison helpers. Pass pre-formatted strings and pre-computed booleans as template variables.
* **Map your template IDs.** Keep a spreadsheet or config file that maps old provider template IDs to new Mailtrap template\_uuid values. This makes updating your codebase easier.
# Analytics & Reports
Learn what statistics Mailtrap provides: Stats dashboard, Email logs, Email categories, Mailbox providers.
# Stats Dashboard
Understand Mailtrap stats dashboard: delivery, open, click, bounce, and spam rates. Learn about domain filtering, warning thresholds, and metric calculations.
Mailtrap provides analytics for all the emails you send.
On the statistics dashboards, you can see the following metrics:
* Delivered emails
* Unique open rate
* Click rate
* Bounce rate
* Spam complaints
### **Navigating around the statistics dashboards**
In that **Stats** tab, you'll find a domain selector at the top of the page. Here, you can choose to show stats for a particular domain.
By default, the stats are shown for the last week + today.
### **Thresholds**
The thresholds are based on our extensive cross-industry research and, at this point, can’t be edited. The current values are:
* For bounce rate:
* 2-5% is a warning level (yellow)
* \>5% is a critical level (red)
* For spam rate:
* 0.08%-0.1% is a warning level (yellow)
* \>0.1% is a critical level (red)
### **Terminology**
#### **Delivered**
Delivered refers to the percentage of emails that were accepted by the recipient’s mailbox providers compared to all emails sent. Email is counted as delivered when a Delivery event is recorded in its Event History in [Email Logs.](/email-api-smtp/analytics/logs)
{% hint style="info" %}
"**Delivered**" status doesn't mean that a message went straight into the recipient's Primary folder. It may have still gone into Promotions and Updates, or it might have been automatically put into a Spam folder.
{% endhint %}
Mailtrap will reject an email if a recipient is on a suppression list for a given domain. Read more about [Suppressions](/email-api-smtp/deliverability/suppressions-list).
On top of that, an email can be rejected on the recipient’s end for various reasons:
* A message is considered spam, phishing, or other foul play.
* A security policy on the recipient’s end dictates that a message should be declined.
* A server timeout occurs (in such case, Mailtrap will retry the delivery 10 times until it eventually gives up).
* Email authentication protocols (SPF, DKIM, DMARC) fail.
#### **Unique open rate**
Unique open rate refers to the percentage of emails that were opened at least once compared to all emails sent.
Open tracking needs to be enabled for a domain in question in the Sending Domains tab. Only then will email opens be recorded.
#### **Click rate**
Click rate refers to the percentage of emails that received at least one link click compared to all delivered emails.
When any of the links in an email are clicked, a **click** event is recorded. The same happens for any further clicks, even if a recipient keeps clicking on the same or different links.
You can see the details of each click (timestamp, Recipient's IP, URL) in the **Events History** in the **Email Logs**.
However, the metrics such as **clicked** and **click rate** used in the statistics are calculated differently.
**Clicked** metric indicates how many emails received at least one click on.
The **click rate** is basically clicked/delivered \* 100%.
#### **Bounce rate**
Bounce rate refers to the percentage of emails dispatched from Mailtrap that were rejected on the recipient’s end compared to all emails sent.
Emails may bounce for different reasons, most commonly:
* Invalid email address.
* Rejection by the recipient’s mailbox because email is deemed spam, phishing, etc.
* The security policy of a mailbox provider that rejects emails from all or some domains.
* Permanent connection issue.
The term bounce used in Mailtrap is also known as a hard bounce. This is different from a soft bounce - another event present in Mailtrap that refers to a temporary delivery problem.
If an email soft bounces, Mailtrap will try to deliver it 10 more times. If there’s no positive outcome, an email will (hard) bounce and get counted towards the bounce rate.
#### **Spam complaints**
Spam complaints refer to the percentage of emails that are reported as spam by recipients, as compared to all emails that were delivered.
# Email Logs
Understand Mailtrap email logs: search and filter sent emails by status, events, and provider. View event history, previews, HTML source, and spam analysis.
It’s a place to view all the emails sent from your account, along with their corresponding details. These include the status of each message, its preview, event history, HTML source, and statistics.
#### How to use filters in Email Logs
These filters are a quick way to find:
* **Bounces** — All emails that were not accepted by the recipient’s mailbox provider (for any reason).
* **Spam** — All emails that were reported as spam by the recipients (this does not include emails that landed in the recipients’ spam folders).
* **Google** — All emails that were sent to free Gmail accounts.
* **Google Workspace** — All emails sent to mailboxes using Google Workspace, the paid version of Gmail used by businesses and organizations.
* **Outlook** — All emails that were sent to Outlook.com mailboxes.
* **Office 365** — All emails that were sent to Office 365 mailboxes.
* **Yahoo** — All emails that were sent to Yahoo mailboxes.
{% hint style="info" %}
When an email is sent, Mailtrap doesn't yet know which Mailbox Provider (e.g., Google, Outlook, Hotmail, etc.) it sent a message to. It's only able to determine this when it receives a response from the recipient's Mailbox Provider, which may sometimes take a few minutes.
{% endhint %}
The number of days Mailtrap stores email logs depends on your [billing plan](https://mailtrap.io/pricing/).
#### Understanding the filters
If you prefer to set up your filters manually, you have plenty of options at your disposal. Here’s what you can filter by:
Criteria
What is it?
Example operator and value
Email to
Email address of a recipient, the To: header of a message.
Is: john.doe@mailtrap.io
Email from
Email address a message is sent from, the From: header of a message. Can be used to find messages sent from a specific domain.
Is: marketing@mailtrap.io
Subject
Subject line of a message. The value is not case-sensitive.
Contains: Product Update
Status
The current state of an email.
Is: Delivered, Not delivered, Enqueued, Opted Out
Events
An action that occurred to an email before, during, or after delivery. An email can have multiple events associated with it.
Include: Sending, Delivery, Open
Number of clicks
The total count of clicks that links in an email received. Click tracking must be enabled for clicks to be counted.
Greater than: 3
Number of opens
The total number of times that an email was opened. Note: some mailbox providers, browsers, or extensions can block tracking, which will affect the results. Open tracking must be enabled for opens to be counted.
Is: 2
Client sending IP
IP of a device (e.g., your computer) that an email was sent from.
Is: 107.177.200.201
Mailtrap sending IP
IP that Mailtrap used to send an email.
Is not: 34.193.89.247
Full response from the Mailbox provider server
The response Mailtrap received when an email failed to be delivered or when a soft bounce was recorded.
Contains: The email account that you tried to reach does not exist.
Mailbox provider server type
The name of the recipient’s mailbox provider. Available once an email is delivered or a response about a failed delivery is received.
Is: Proton Mail
Mailbox provider server raw
The name of the recipient’s mailbox provider, as specified in their MX record.
Contains: gmail-smtp-in.l.google.com
Categories
The category specified in the “X-MT-Category” header of an email.
Contains: Newsletter
You can combine different filters by using the **Add Filter** button to the right. In some fields, you may add multiple values to find emails matching either of them.
For example, here, we search for emails that were delivered or clicked, and the recipient has either a Google Workspace or Yahoo! mailbox.
Email Logs store emails sent from all your domains. If you wish to filter only for a particular domain or address, use **Email from**. For example:
#### Diving deeper into Email Logs
Email Logs provide much more information about each sent message. To access this, click on any of the messages.
The **Email info** tab provides the basic details of a message, including the timestamps, status, from/to addresses, or the IPs. If you’re confused about any of these terms, check our [Sending Glossary](https://github.com/mailtrap/mailtrap-docs/blob/main/documentation/email-api-smtp/email-sandbox/sandbox-glossary.md).
Event History offers a list of all the events that have happened to this email since it was sent and until this moment.
You may know the HTML Source, Text, Preview, Raw, and Spam Analysis tabs well from Email Sandbox. Here, you can preview how your message looks on different devices, see its code, or see its spam score.
# Email Categories
Understand Mailtrap email categories: organize email types like welcome, onboarding, or billing. Track performance, analyze metrics, and compare categories.
Email Categories were built to show the performance of various types of emails, such as welcome emails, billing emails, confirmation emails, etc.
#### Why should you use categories?
* See statistics for each type of email you send.
* Analyze key metrics of each category, such as open, click, or bounce rates. A single underperforming category can influence your overall sender reputation.
* Compare different types of emails and know straight away which perform better.
* Debug specific templates when, for example, an open rate suddenly drops.
* Simplify the search for any particular message. Filter out only emails matching a certain category to narrow down the results.
Email categories examples:
* “Feature XYZ intro”
* “Password reset 1st email”
* “Test A Order Confirmation”
* “Downgrade flow Tier 1”
* “Onboarding Msg 3”
* “Newsletter 04/20”
#### How to use
You specify categories when creating an email to be sent with Mailtrap, by inserting a category name into the `X-MT-Category` header if you are using SMTP.
If you are using the API, refer to our [Api Docs](https://docs.mailtrap.io/developers/email-sending/transactional).
At this point, categories can only be specified when sending an email. Once you add one to an email and a message is sent, the category will appear in Mailtrap Email Logs’ filters as well as in statistics.
Categories cannot be removed or modified at this point. The number of categories in your account is unlimited.
#### How to analyze performance
Categories can be tracked via the Email Categories tab in the Stats menu.
You can filter out the data for specific domains or mailbox providers using the filters. You can also limit the number of domains displayed and compare statistics only for some of them.
Mailtrap tracks statistics for each day separately, which can sometimes lead to, for example, open rates going into hundreds of percent.
# Mailbox Providers
Analyze email performance by mailbox providers like Gmail, Outlook, and Yahoo. Filter by domain and category, track metrics, and identify deliverability issues.
Why is it important to monitor mailbox provider stats?
It’s important because the deliverability towards a specific provider can suddenly drop. This is a clear sign that a provider has started treating you negatively, so it’s critical to take action to improve the situation.
The following sections detail how to take advantage of **Mailbox Providers** feature within **Mailtrap API/SMTP**.
#### Mailbox Providers filters
Mailbox Providers Overview panel allows you to filter by **Domains**, **Mailbox Providers**, and **Categories**. Here’s how to use each filter.
**Domains**
1. Click on arrows in the All Domains box.
2. Choose one or more domains you’d like to use.
3. When you select the domain, the Table automatically shows corresponding statistics.
**Mailbox providers filter**
1. Click the arrows in the Mailbox Provider box.
2. Choose the provider you’d like to use.
3. Check the corresponding stats in the table below.
You can select a few providers at the same time - just repeat the actions listed above.
**Categories**
1. Click the arrows in the **Categories** box.
2. Choose a category or categories.
3. Preview the stats for that category in the table below.
#### Navigating mailbox providers
**Table**
The first column features **Mailbox Providers** of your recipients.
The stats include the number of **Delivered** emails. You can also see **Unique Opens** and **Unique Open Rate**, as well as **Clicked** emails and **Click Rate**.
Also, the Tables tab shows **Bounce** emails and **Bounce Rate**, plus **Spam** and Spam **Complaints**. Finally, you can see the **Clicked to Open Rate**.
You can learn more about [Stats](/email-api-smtp/analytics) here.
**Color coding**
To immediately understand email deliverability, the table features colors that signal if the value is good, bad, or just average.
* Green - good results - exceed what we perceive as a satisfactory value for a particular data point.
* Yellow - borderline results - neither good nor bad, and may require your attention or action.
* Red - the result is under the threshold we consider satisfactory and it requires your action to improve the performance of a specific mailbox provider.
# Statuses and Events
Learn about Mailtrap statuses and events: delivery, bounces, opens, clicks, and opt-outs. Understand how statuses differ from events and track performance.
When sending emails with Mailtrap, you’ll often encounter the terms Status and Event.
**Status** is the latest delivery status of an email. Each status bears a distinct color, and an email can only have one status at a time. The available statuses are: **Delivered, Not Delivered, Enqueued,** and **Opted Out**.
As an email changes status, multiple **events** can occur. Events are one-time occurrences that are logged into the **Event History**. Multiple events can (and often are) recorded for an email.
For example, a certain email can have the status **Opted Out**. This indicates that the recipient marked your message as spam or unsubscribed from the list. The **Event History** tab for such an email may look like this:
The chart below showcases all the possible events and the relations between them.
Here’s a summary of all the possible events:
{% tabs %}
{% tab title="Enqueued" %}
Email has been queued for sending or has been dispatched, but something prevented its delivery.
Event
Event Description
Sending
Email sending is in process, or it’s in the queue.
Soft bounce
Email couldn’t be delivered, most commonly due to a server timeout, full inbox, or too large size. The delivery will be attempted 10 more times. Possible outcomes: Delivery or Bounce.
Suspension
Email was sent from an unverified domain. We’ll re-check the domain status 10 more times. If it’s verified during this time, an email will be sent. Possible outcomes: Delivery, Reject.
{% endtab %}
{% tab title="Not delivered" %}
Email failed to be delivered, and no further attempts will be made.
Event
Event Description
Reject
The domain in question was not verified in time after an initial suspension of an email, and a message was rejected. Or, a recipient is on a suppression list for this domain.
Bounce
Email recorded a bounce (permanent delivery failure), and no further attempts will be made to deliver it. Most commonly, this happens because of an invalid email address or a rejection by the recipient’s mailbox provider.
{% endtab %}
{% tab title="Delivered" %}
Email was accepted by the recipient’s mailbox provider.
Event
Event Description
Delivery
Email was accepted by the recipient’s mailbox provider. Note: this doesn’t exclude a delivery to a spam folder. In some cases, an email may be accepted, but an internal policy may prevent it from reaching a sandbox.
Open
Email was opened by a recipient or another person that a message was forwarded to. Multiple open events can be recorded.
Click
Any link in an email was clicked.
{% endtab %}
{% tab title="Opted Out" %}
A recipient opted out of receiving any further messages and has been added to Mailtrap’s suppression list for this domain.
{% hint style="info" %}
This doesn't prevent you from emailing them from other verified domains.
{% endhint %}
Event
Event Description
Unsubscribe
The recipient unsubscribed from receiving emails. Mailtrap won’t send any further emails to them from this domain.
Spam
User reported a message as spam. Mailtrap won’t send them any more messages from this domain.
{% endtab %}
{% endtabs %}
And here's a summary of the possible statuses:
Status
Status Description
Event
Event Description
Enqueued
Email has been queued for sending or has been dispatched, but something prevented its delivery.
Sending
Email sending is in process, or it’s in the queue.
Soft bounce
Email couldn’t be delivered, most commonly due to a server timeout, full inbox, or too large size. The delivery will be attempted 10 more times. Possible outcomes: Delivery or Bounce.
Suspension
Email was sent from an unverified domain. We’ll re-check the domain status 10 more times. If it’s verified during this time, an email will be sent. Possible outcomes: Delivery, Reject.
Not delivered
Email failed to be delivered, and no further attempts will be made.
Reject
The domain in question was not verified in time after an initial suspension of an email, and a message was rejected. Or, a recipient is on a suppression list for this domain.
Bounce
Email recorded a bounce (permanent delivery failure), and no further attempts will be made to deliver it. Most commonly, this happens because of an invalid email address or a rejection by the recipient’s mailbox provider.
Delivered
Email was accepted by the recipient’s mailbox provider.
Delivery
Email was accepted by the recipient’s mailbox provider. Note: this doesn’t exclude a delivery to a spam folder. In some cases, an email may be accepted, but an internal policy may prevent it from reaching an sandbox.
Open
Email was opened by a recipient or another person that a message was forwarded to. Multiple open events can be recorded.
Click
Any link in an email was clicked.
Opted Out
A recipient opted out of receiving any further messages and has been added to Mailtrap’s suppression list for this domain. Note: this doesn’t prevent you from emailing them from other verified domains.
Unsubscribe
The recipient unsubscribed from receiving emails. Mailtrap won’t send any further emails to them from this domain.
Spam
User reported a message as spam. Mailtrap won’t send them any more messages from this domain.
{% hint style="success" %}
If you want to track how many emails were delivered, it's better to use the **Delivery** event rather than the **Delivered** status.
{% endhint %}
When a recipient unsubscribes or reports your message as spam, an email's status changes to Opted Out. At the same time, the Delivery event remains in its Events History. By filtering for this event, you’ll easily find all emails that were delivered in a chosen timeframe, regardless of what happened to them next.
Some useful definitions:
* **Client sending IP** — IP address of a device that was used to send an email.
* **Mailtrap sending IP** — IP address of Mailtrap, used to send a message to the final recipient.
* **Recipient IP** — IP address of a device or an email server where an email was opened. If a message is opened on devices using different IP addresses, multiple Recipient IPs will be recorded. If a message is not opened at all, no Recipient IP will be displayed.
Find more definitions in Sending Glossary
# Deliverability Features
Learn about email deliverability features and tools Mailtrap provides to guarantee high inbox placement rates of your emails.
Maximize your email deliverability with Mailtrap's comprehensive suite of deliverability tools. These features help you maintain a good sender reputation, manage bounces effectively, and ensure your emails reach their intended recipients.
### Essential Guide
#### [Email Deliverability Guide](https://mailtrap.io/email-deliverability-guide/)
**Start here!** Our comprehensive guide covers everything you need to know about achieving optimal deliverability:
* Golden rules of email deliverability
* Technical setup and domain authentication
* List management best practices
* Content optimization
* Monitoring and compliance
{% hint style="info" %}
**Recommended**: Read the Email Deliverability Guide first to understand best practices before configuring individual features.
{% endhint %}
### Key Features
Suppressions List
Automatically manage unsubscribed users and prevent sending to invalid email addresses. Keep your lists clean and maintain good sender reputation.
Get weekly health status reports and critical alerts for your email deliverability metrics including opens, clicks, bounces, unsubscribes, and spam complaints.
Best practices to protect your sending domain from abuse, including securing web forms, implementing CAPTCHA, and hiding sensitive configuration files.
# Suppressions List
Manage Mailtrap suppression lists. View, add, remove, or import suppressed emails from hard bounces, unsubscribes, and spam complaints via CSV or manually.
When hard bounce, unsubscribe, and spam complaints events occur, Mailtrap adds the email address to a suppression list. The suppression list contains all the addresses you cannot send emails to.
You'll find all the addresses on suppression lists in the **Suppressions** menu to the left.
The menu contains the data for all your domains. If an email address was suppressed for more than one domain, it appears multiple times on the list.
You can export the whole Suppressions list.
### How to remove an email from a suppression list
If you believe an email landed on a suppression list by accident, you can remove it by clicking the **Reactivate** button to the right.
However, we advise you not to misuse the feature.
If someone decided to report your message as spam or leave your email list, you really don’t want to be emailing them again (unless they explicitly told you they had done it by mistake). Any further attempts will probably result in the same outcome, immediately hurting your email deliverability.
### Suppression list filters
You can filter the suppression list for:
* Specific email address
* Sending domain
* Type of suppression
* Reason for suppression
### How to add recipients to the suppression list
Mailtrap allows you to add recipients manually or by uploading a CSV file.
#### Manual method
Select **Insert manually**. Then, under **Add to stream**, choose Bulk, Transactional, or Any. Under **Add to domain**, choose all or one of your domains.
After you select the domain and stream, type or copy-paste the email addresses you want to suppress into the designated box. Then, click the **Add To Suppressions** button to complete the action.
You can add only one email address per line and up to 1,000 emails per selected domain.
Note that there's also the **Add New/Import** button at the top right of the screen in the Suppressions main dashboard. It allows you to access the **Add recipients to suppression list** menu quickly.
#### Upload CSV
Before you upload CSV to Mailtrap, you first need to export the document from your current sending provider. See how to do it with SendGrid, Postmark, and Mailgun.
### Exporting suppressions
#### Sendgrid
Navigate to Suppression Management - this is where you’ll find the list of all your Unsubscribe Groups. You’ll see the default groups and the ones you created.
To export the CSV file, you need to click the Settings button (the gear icon) next to each group, then choose **Export**.
#### Mailgun
Mailgun keeps three suppression lists (complaints, bounces, and unsubscribes) for each of your sending domains. There's no global, account-level suppression list, so you need to export separate lists for each domain you transfer to Mailtrap.
To get the list in CSV format, make sure you choose the correct domain and use the Mailgun dashboard to export the lists.
#### Postmark
There’s an Export button in the Postmark dashboard. This allows you to export up to 500 records in a JSON file. For more records, you need to use Postmark’s Messages API.
Many online services offer services for converting JSON to CSV. [Postmark’s help page](https://postmarkapp.com/support/article/881-can-i-export-a-list-of-all-bounces) provides more information.
### Importing to Mailtrap
Select **Upload CSV**, then choose the stream and the domain.
Click **Browse file** to select the CSV file from your computer or drag and drop it into the **Select file** box.
To complete the action, click **Add To Suppressions** and you’re done. If you wish, you can also download our CSV template by clicking on the corresponding option.
**Hint:** You can suppress sending of transactional and marketing emails separately or do both at once by selecting 'Any'. For example, if a user X unsubscribes from marketing emails and they're now on the suppression list, this doesn't stop you from sending them transactional emails. However, if they unsubscribe from those too, they won't receive any emails.
# Dedicated IP
Learn about Mailtrap IP warmup: shared vs dedicated IPs, automated IP warmup schedule, and gradual daily sending limits over 3 weeks.
Mailtrap offers both shared IP addresses as well as dedicated IPs.
### Shared IP vs Dedicated IP
A **shared IP** is a default option with nearly all sending providers (including Mailtrap). A provider maintains a pool of IPs that are shared among their users.
A **dedicated IP** is the IP address that only you use for sending emails. As such, you have full control over your reputation and can influence it with each email sent.
We recommend dedicated IPs only if your volume regularly exceeds 100,000+ emails per month.
{% hint style="info" %}
If you’re interested in using a dedicated IP, the Deliverability team will be happy to assist you.
Contact us
{% endhint %}
Each request is reviewed individually by our Deliverability team. In some cases we recommend and insist users to stay on a shared IP for their own benefit.
### Automated IP warmup at Mailtrap
Each newly purchased dedicated IP goes through a mandatory 3-weeks-long (in most cases) warm-up process, aimed at giving you the best possible preparation for sending mass emails.
Mailtrap automatically increases your volume each day, with about 30% more emails sent every day. Simultaneously, our deliverability experts closely monitor your stats.
At the moment the IP warm-up schedule looks as follows:
Day
Emails sent per day
Max emails per hour
Day
Emails sent per day
Max emails per hour
1
300
60
2
390
80
3
510
100
4
660
130
5
860
170
6
1,100
220
7
1,400
290
8
1,900
380
9
2,400
490
10
3,200
640
11
4,100
830
12
5,400
1,100
13
7,000
1,400
14
9,100
1,800
15
11,800
2,400
16
15,400
3,100
17
20,000
4,000
18
26,000
5,200
19
33,700
6,700
20
43,900
8,800
21
57,000
11,400
This schedule shouldn’t, of course, limit your email sending capability. Any emails over a limit will automatically be sent via one of Mailtrap’s Shared IPs.
# Bounce Categorization
Understand how Mailtrap categorizes email bounces based on MX server responses, including bounce types, descriptions, and automatic suppression rules.
Mailtrap categorizes [bounces](/email-api-smtp/analytics/dashboard) based on the responses from the recipients' MX servers.
The table below lists these responses and their descriptions. It also contains information on whether these bounces cause automatic suppression.
You can find bounce categories in the app, specifically in event history in Email Logs, Webhooks payload for bounce and soft\_bounce events, and Suppressions for hard bounces.
Category
Event name
Description
Adding to Suppressions
transientfail
Transient failure
The email encountered a temporary issue.
No
greylisting
Greylisting
The email was temporarily rejected by the recipient's server to determine whether the sender was legitimate or not.
No
badsender
Bad sender
The email was rejected because the sender's address was invalid or unrecognized.
No
block
Blocked
The recipient's email server blocked the email, possibly due to security policies.
No
content
Content issue
The email content triggered content filters and was rejected by the recipient's server.
No
dnsFail
DNS failure
The email could not be delivered due to issues with the DNS configuration of the recipient's domain.
No
generalfail
General failure
The email could not be delivered due to a general failure on the recipient's server.
No
other
Other
The email was bounced for an unspecified or unknown reason.
No
relayfail
Relay failure
The email was rejected because the server is not allowed to relay messages.
No
serverfail
Server failure
The email could not be delivered due to a failure on the recipient's server.
No
spam
Spam detected
The email was identified as spam by the recipient's mail server.
No
verifyfail
Verification failed
The email was rejected because the sender's or recipient's addresses could not be verified.
No
timeout
Timeout
The email was bounced due to an unspecified issue, probably a timeout.
Yes
badrecipient
Bad recipient
The email was bounced because the recipient's email address is invalid or does not exist.
Yes
overquota
Over quota
The recipient's mailbox is full and cannot accept new messages.
Yes
serverpolicy
Server policy
The email was rejected due to the recipient's server policy settings.
No
spam_gmail
Gmail limitation
The email bounced due to limitations from Gmail recipient due to either incorrect authentication, sudden increase of email traffic, or reputation issue
No
# Feedback Loops
Learn how Mailtrap integrates with popular Feedback Loops (FBLs) to track spam complaints from major mailbox providers including Outlook, Yahoo, and more.
Mailtrap is integrated with the majority of popular Feedback Loops (FBLs) to gather information about spam complaints.
{% hint style="info" %}
Remember that Gmail doesn’t provide spam complaint information per message.
{% endhint %}
Still, Mailtrap adds `Feedback-ID` to all emails sent to Gmail. If you specify Email Categories, we add it to the header as a part of the category. Yet, it’s up to Gmail to show that info in your Google Postmaster. Read more about the feedback header [here](https://support.google.com/a/answer/6254652?hl=en).
Our Deliverability Team can review aggregated data for Spam Rates for Gmail recipients daily if you provide us with view rights for Google Postmaster. This service is available for our paid customers. Please contact our support team for the details.
Contact SupportThe list of FBLs Mailtrap is integrated with:
* Microsoft Outlook
* Yahoo! Mail
* Bluetie
* Comcast
* Fastmail
* gandi.net
* Liberty Global (Chello, UPC, and UnityMedia)
* Locaweb
* Mail.ru
* OpenSRS/Hostedmail (Tucows)
* Rackspace
* Seznam
* SFR
* SilverSky
* Swisscom
* Synacor
* Telecom Italia
* Telenet
* Telenor
* Telstra
* Terra
* UOL
* Virgilio
* Virgin Media
* Yandex
* Ziggo
While using our services, Mailtrap may get alerts from these FBLs if your recipients submit spam complaints. You'll see them in your [Stats](/email-api-smtp/analytics/dashboard) and may receive them via [Webhooks](/email-api-smtp/setup/sending-domain#optional-webhooks-4hmes).
We also support the `CFBL-Address` header as per [RFC 9477](https://www.rfc-editor.org/rfc/rfc9477.html). However, it’s still experimental, and not all mailbox providers support it.
# Deliverability Alerts
Get weekly health status reports and critical alerts for your email deliverability metrics including opens, clicks, bounces, unsubscribes, and spam complaints.
Deliverability Alerts help you monitor your email performance by providing automated notifications about your sending metrics.
{% hint style="info" %}
A minimum of 500 emails per week is required to receive alerts, as the system needs sufficient data to provide meaningful statistics.
{% endhint %}
If you want, you can toggle the alerts off. However, we recommend keeping them enabled because a missed issue may affect your domain authority and sender reputation.
## Health Status Weekly
Health Status Weekly alerts are sent out on Mondays and provide a detailed preview of the following stats:
* Opened
* Clicks
* Bounces
* Unsubscribes
* Spam
The report includes clearly color-coded comparisons to the previous week, making it immediately obvious if one or more stats need your attention or show a negative trend. Additionally, there are insights (digest explanations of the stats) to help you troubleshoot your email infrastructure faster.
## Integrate Mailtrap Alerts with Slack
Each Slack channel has a unique email address. You can leverage that to route Mailtrap Alerts directly to Slack. Here's how to do it on the desktop app:
{% stepper %}
{% step %}
Click the channel name in the header and select **Integrations**.
{% endstep %}
{% step %}
Click **Send emails to this channel**, then the **Get Email Address** button.
{% endstep %}
{% step %}
Navigate to the Deliverability Alerts page in Mailtrap, and paste the Slack email address into the field under **Who receives notifications?**
{% endstep %}
{% step %}
Click **Save** and all alerts will be routed to the Slack channel instead of your email.
{% endstep %}
{% endstepper %}
## Critical Alerts
{% hint style="warning" %}
Critical Alerts feature is currently switched off. We'll notify you once it's back on.
{% endhint %}
Critical Alerts are sent hourly (the system checks your metrics every three hours for the past 24 hours) when one or more of your critical stats are below the predetermined threshold.
The predetermined thresholds are based on extensive cross-industry research and examples of best practices.
{% hint style="info" %}
If you're getting a lot of false positives or negatives, feel free to reach out to us at .
{% endhint %}
# Protecting Your Domain
Best practices to protect your sending domain from abuse, including securing web forms, implementing CAPTCHA, and hiding sensitive configuration files.
Adding and verifying your domain with Mailtrap is a simple process. However, in some cases, an automated security tool may flag your domain as high-risk and reject it. To prevent this, follow the best practices outlined in this article to enhance your security and ensure a smooth verification process.
Verified domain status
### Protect your web forms
You should protect all email-triggering online forms on your website. Otherwise, bots may use them to send a large volume of unsolicited emails to recipients who did not expect these emails and can start marking them as spam. Also, those kinds of emails may potentially contain malicious content, severely affecting your sender's reputation.
{% hint style="warning" %}
It's highly recommended that **all** web forms that can trigger email sending, such as newsletters, user registration pages, and password reset forms, be secured. This applies even if emails to be sent via Mailtrap are unrelated to those forms or are sent to different email addresses than the one gathered through online forms.
{% endhint %}
{% hint style="info" %}
If your domain is used to send emails to users who registered through an unprotected form that gets abused - even if those emails were sent using a tool other than Mailtrap - your domain reputation may suffer, and you can experience deliverability issues when sending legitimate emails through Mailtrap.
{% endhint %}
#### Protection methods
* **CAPTCHA/reCAPTCHA** — Requires human interaction to complete the form
* **Honeypots** — An invisible field that bots automatically fill, but humans don't see
* **Timing check** — Rejecting all submissions completed under 1 second
* **IP rate limiting** — Detect IPs that attempt to use the form multiple times and prevent further submissions
* **Double opt-in** — Ensure that the email address is valid and that the user genuinely wants to receive communications
### CAPTCHA
Adding CAPTCHA or reCAPTCHA is one of the most efficient ways to protect your forms on your website from bots and spam. Here's how to implement it:
1. Choose a trusted CAPTCHA solution:
* [Google reCAPTCHA](https://www.google.com/recaptcha/about/)
* [hCAPTCHA](https://www.hcaptcha.com/)
* [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/)
2. Sign up for the API keys
3. Add the CAPTCHA widget to your form HTML
4. Validate the CAPTCHA on your server
5. Test your implementation
### Honeypot fields
Honeypot fields are hidden fields that should remain empty. If a bot catches them, it'll automatically complete them, thus blocking itself from the form.
To add honeypots:
1. Add a hidden input field to your frontend
2. Validate the honeypot field in your backend
{% hint style="info" %}
We recommend using a randomized name for honeypot fields to avoid detection by bots that specifically look for common field names.
{% endhint %}
### Timing check
By adding a timing check, you block all submissions completed under 1 second (or any time you think a bot might be able to complete a form).
You can also add a maximum time limit, like 1 hour. This way, if a form is left open too long, the user submission will be rejected. This can be useful for detecting expired or suspicious sessions.
### Rate limiting by IP address
Rate limiting controls the number of requests a single IP can make to a server within a timeframe you specify. With rate limiting, you can easily detect IPs that attempt to use the form multiple times and prevent further submissions.
### Double opt-in
After a user submits their email address, they must confirm their subscription by clicking a verification link sent to their inbox. This extra step:
* Ensures that the email address is valid
* Confirms the user genuinely wants to receive communications
* Helps prevent spam and fraudulent sign-ups
* Protects your sender reputation
### Hide your .env file
The .env file is where you store your sensitive configuration information, including API keys, database credentials, and other critical environment variables. Spammers could send emails to your recipients on your behalf if your .env is exposed, so we may not approve your domain if it's accessible.
{% hint style="danger" %}
How you store your .env file is your first line of defense against attackers.
{% endhint %}
**Best practices:**
* Keep your .env file from the public by hiding it outside your web root, restricting file permissions, or using your preferred method.
* Turn off debug mode, as it can expose sensitive information, including environment variables. This is typically done by setting your `DEBUG` to `False`, depending on your programming language.
### Additional security measures
The methods outlined in this article are not exhaustive. While securing your web forms and hiding your .env files are fundamental security measures, they should be considered just the first line of defense.
Additional recommended measures:
* Use strong passwords that are regularly updated.
* Manage access rights carefully to ensure only authorized users can access sensitive systems.
* Conduct regular security audits to identify and address potential vulnerabilities.
* Implement additional security layers to better protect your website or application.
# Advanced Features
Learn what features for advanced email sending scenarios Mailtrap Email API/SMTP provides.
Take your email sending to the next level with Mailtrap's advanced features. These tools are designed for power users who need more control over their email infrastructure and want to optimize their sending patterns.
## Features Overview
Custom Variables
Add custom metadata to your emails for advanced tracking and segmentation. Pass through data that helps you analyze email performance in your own systems.
# Custom Variables
Add unique data to your emails with custom variables. Track user IDs, inbox IDs, and other metadata via Email Logs using X-MT-Custom-Variables header.
Custom variables are pieces of information that you can include with emails to better manage them in the future. They allow you to add unique data to each message, for example, the data can be an internal `user_id`, `inbox_id`, etc.
For now, you can only access them via Email Logs.
#### How to access custom variables
1. Click on the given functionality
2. Choose an email
3. Check the variables (Variable name 1, 2, 3…) under the Email info tab
#### **How to set up custom variables with SMTP**
Mailtrap has an option to pass unique arguments to each sent email via the `X-MT-Custom-Variables`. And we add the arguments to the RAW email body. Of course, the RAW data is visible to the sender but not the end-user.
To set custom variables, you only need to set the unique argument in the following format - `{"variable name": "variable value"}`.
Here’s a code snippet, to show you where to look for it, and how to set the variable. Note that this applies when you set Mailtrap as your SMTP server.
{% code title="cURL Example with Custom Variables" %}
```bash
curl --ssl-reqd \
--url 'smtp://send.smtp.mailtrap.io:587' \
--user 'api:49ad7a716f18d9c64xxxxx' \
--mail-from 'example@mailtrap.io' \
--mail-rcpt 'email@exampledomain.com' \
--upload-file - <
Lastly, keep in mind that we don’t support arrays. If you want to add arrays - `[“index0”,”index1”,”index2”]`, for example, Mailtrap only takes the first value (`"index0"`) and ignores the rest.
{% hint style="warning" %} We limit the custom variables payload to 1000 bytes, and it’s a valid JSON string. If the payload is more than 1000 bytes, Mailtrap ignores the `X-MT-Custom-Variables`.
We use only - `X-MT-Custom-Variables`; and it can’t get appended with another one.
# Excluding Links from Tracking
Learn how to exclude specific links from tracking using the data-mt-no-track attribute to preserve app deeplinks and sensitive URLs.
By default, when link tracking is enabled for a domain, Mailtrap rewrites links in your emails to add tracking redirects. However, in some cases you may want to exclude certain links (such as app deeplinks or sensitive URLs) from being tracked.
### How to Disable Tracking for a Specific Link
To prevent a link from being tracked, add the special attribute `data-mt-no-track` to your `` tag in the HTML body of the email.
```html
Open in App
```
When this attribute is present:
* The link in the HTML body will not be replaced with a tracking redirect.
* If the same link also exists in the Text body of your email, it will also remain untouched (not rewritten).
### Notes
* This works on a per-link basis - all other links without the attribute will still be tracked.
* The attribute must be included in the HTML body. If the identical URL also appears in the Text body, it will inherit the no-track behavior.
* Use this for app deeplinks or any URL where tracking redirects could break functionality.
# Auto BCC
Automatically add BCC recipients to all emails sent from your domain with custom headers support.
### How to set up Auto BCC
{% stepper %}
{% step %}
Go to **Sending Domains** and choose the domain you want to set up Auto BCC for.
{% endstep %}
{% step %}
Navigate to the **Auto BCC** tab.
{% endstep %}
{% step %}
Enter an email address that will be included as BCC in all the emails you send from this domain and click **Add Email**.
{% endstep %}
{% step %}
Optionally, specify a custom X-header that will be included in emails to BCC recipients. Enter the Name and Value, and click **Add Header**.
{% endstep %}
{% step %}
To delete the email address or a custom header, click the trash bin icon and confirm the action by clicking **Delete**.
{% endstep %}
{% endstepper %}
### Important notes
* You can add multiple BCC email addresses, and all of them will receive email copies;
* You can’t use Auto BCC with a demo domain;
* Using this feature will increase your usage. Each email copy sent will count against your quota or overage calculation.
# Webhooks
Set up webhooks to receive real-time notifications about email deliverability events and account activities within your Mailtrap account.
Webhooks allow you to receive all information about your deliverability and activities within your account (Audit Log) almost in real-time.
{% hint style="info" %}
IPv6 ranges are AWS-provided, not Mailtrap-owned, and they're available on request. Feel free to contact us at <_support@mailtrap.io>.\_
{% endhint %}
### Event types
**Sending events:**
* **Delivery** - Email successfully delivered
* **Bounce** - Permanent delivery failure
* **Soft bounce** - Temporary failure (will retry)
* **Spam complaint** - Recipient reported spam
* **Unsubscribe** - Recipient unsubscribed
* **Open** - Email was opened
* **Click** - Link was clicked
* **Suspension** - Message suspended
* **Reject** - Message rejected
**Audit Log events (available for enterprise only):**
* User login events
* Profile updates
* Permission changes
* And more
### How to set up webhooks
{% stepper %}
{% step %}
Navigate to **Settings** → **Webhooks** and click the **Create New Webhook** button.
{% endstep %}
{% step %}
Enter a valid **Webhook URL**. Use a password and username as an extra security layer with basic authorization to prevent others from sending information to that endpoint. You can also use a token as a query parameter or use [webhook signature](https://docs.mailtrap.io/email-api-smtp/advanced/webhooks#webhook-signature-verification).
{% endstep %}
{% step %}
Choose the **Payload format** (JSON or JSON Lines).
Examples of payload:
{% tabs %}
{% tab title="JSON" %}
Events sent as a JSON object with an `events` array:
```json
{
"events": [
{"event": "delivery", "email": "user@example.com", ...}
]
}
```
{% endtab %}
{% tab title="JSON Lines" %}
Events sent as newline-delimited JSON:
```jsonl
{"event":"delivery","email":"user@example.com",...}
{"event":"open","email":"user@example.com",...}
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
Select the webhooks area (**Audit Log** or **Email Sending**).
{% endstep %}
{% endstepper %}
**If you choose Audit Log**, you will receive events related to all activities within your account that are supported by the Audit Log.
**If you choose Email Sending**, you'll also need to:
{% stepper %}
{% step %}
Choose the **Sending Stream** (Transactional or Bulk) for which you want to set up the webhooks.
{% hint style="info" %}
**Transactional Stream** is used to send user-triggered emails to one recipient at a time, while **Bulk Stream** is used to send promotional emails to multiple recipients at once.
{% endhint %}
{% endstep %}
{% step %}
Choose the **domain** you want to receive events' data for and select one or more [event types](/email-api-smtp/analytics/statuses-and-events) by ticking the corresponding checkbox.
{% endstep %}
{% step %}
Click the **Run Test** button to test the webhook setup. The code represents a dummy payload of the webhook structure and how to read it correctly. If your endpoint responds with a 200 code, you'll see a confirmation in the app. All other response codes show an error during a test.
{% hint style="info" %}
One popular way to test webhooks outside your system is [Webhook.site](https://webhook.site/#!/view/d24cebd2-99cc-46f3-8685-c779017f39a0), but don't use it for production.
{% endhint %}
{% endstep %}
{% step %}
If the tests are successful, click the **Save** button. All information will be sent to your webhook endpoint.
{% hint style="info" %}
To edit, pause, or delete an active webhook, go back to the Webhooks tab and select the webhook you want to change.
{% endhint %}
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
Mailtrap webhooks are delivered only on ports 443 (for HTTPS) or 80 (for HTTP). Please be sure to use these ports only.
{% endhint %}
### Receive events (JSON format)
Receive webhook events as a JSON object containing an array of events.
Set **Payload format: JSON** in your webhook settings.
Mailtrap sends a `POST` request to your webhook URL with events as a JSON object.
**Your endpoint should:**
* Accept `Content-Type: application/json`
* Return HTTP 200 to acknowledge receipt
* Process events asynchronously
#### Payload
**events** one of\[] optional
object · SendingWebhookEvent optional Email lifecycle webhook event
**event** string · enum required\ Event type\ Possible values: `delivery` `open` `click` `unsubscribe` `spam` `soft bounce` `bounce` `suspension` `reject`
**message\_id** string required\ Unique message ID
**sending\_stream** string · enum required\ Sending stream used\ Possible values: `transactional` `bulk`
**email** string required\ Recipient email address
**sending\_domain\_name** string required\ Sending domain name
**category** string optional\ Category assigned when sending
**custom\_variables** object optional\ Custom variables from the email
* **Other properties** string | number | boolean optional
**timestamp** integer required\ Unix epoch timestamp
**event\_id** string required\ Unique event ID (use for idempotency)
**reason** string optional\ Reason (for `suspension` and `reject` events)
**response** string optional\ Server response (for `soft bounce` and `bounce` events)
**response\_code** integer optional\ SMTP response code (for `soft bounce` and `bounce` events)
**bounce\_category** string optional\ Bounce category (for `soft bounce` and `bounce` events)
**ip** string optional\ User IP address (for `open`, `click`, `unsubscribe` events)
**user\_agent** string optional\ User agent (for `open`, `click`, `unsubscribe` events)
**url** string optional\ Clicked URL (for `click` events)
object · ActivityLogWebhookEvent optional Account activity webhook event (Enterprise only)
**event** string required\ Activity log event type\ Example: `activity_log.user.updated`
**description** string required\ User-friendly event description\ Example: `updated the user profile`
**actor** object required\ User or system that performed the action
* **id** integer optional\ Actor ID\ Example: `1`
* **type** string · enum optional\ Actor type\ Possible values: `user` `api_token`
* **name** string optional\ Actor name\ Example: `John Doe`
**resource** object optional\ Affected resource (optional)
* **id** string optional\ Resource ID\ Example: `1`
* **type** string · enum optional\ Resource type\ Possible values: `user` `api_token` `billing` `account` `sso_config` `sending_domain` `project` `inbox` `contact_list` contact\_field `contact_segment`
* **name** string optional\ Resource name\ Example: `John Doe`
**changes** object optional\ Changes made (optional)\ Example: `{"name":{"from":"John","to":"John Doe"}}`
* **Other properties** object optional
**timestamp** integer required\ Unix epoch timestamp\ Example: `1735830138`
**Responses**
| `200` | Return 200 to acknowledge successful receipt |
| ------------------------------------------ | -------------------------------------------------------- |
| `500` | Any other status triggers retry (40 retries every 5 min) |
**Payload**
{% tabs %}
{% tab title="Delivery" %}
```json
{
"events": [
{
"event": "delivery",
"timestamp": 1728669700,
"sending_stream": "transactional",
"category": "Password reset",
"custom_variables": {
"user_id": "123"
},
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Bounce" %}
```json
{
"events": [
{
"event": "bounce",
"timestamp": 1728669700,
"sending_stream": "transactional",
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"response": "[CS01] Message rejected due to local policy",
"response_code": 555,
"bounce_category": "spam",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Soft Bounce" %}
```json
{
"events": [
{
"event": "soft bounce",
"timestamp": 1728669700,
"sending_stream": "transactional",
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"response": "4.7.1 Temporary error, please retry",
"response_code": 451,
"bounce_category": "greylisting",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Spam" %}
```json
{
"events": [
{
"event": "spam",
"timestamp": 1728669700,
"sending_stream": "transactional",
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Suspension" %}
```json
{
"events": [
{
"event": "suspension",
"timestamp": 1728669700,
"sending_stream": "transactional",
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"reason": "Your account has reached its daily sending limit.",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Reject" %}
```json
{
"events": [
{
"event": "reject",
"timestamp": 1728669700,
"sending_stream": "transactional",
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"reason": "Recipient in suppression list. Reason: unsubscription",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Open" %}
```json
{
"events": [
{
"event": "open",
"timestamp": 1728669700,
"sending_stream": "transactional",
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"ip": "127.138.158.185",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Click" %}
```json
{
"events": [
{
"event": "click",
"timestamp": 1728669700,
"sending_stream": "transactional",
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"ip": "142.86.27.2",
"user_agent": "Mozilla/5.0 (Windows NT x.y; Win64; x64)",
"url": "https://mailtrap.io/email-api",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Unsubscribe" %}
```json
{
"events": [
{
"event": "unsubscribe",
"timestamp": 1728669700,
"sending_stream": "transactional",
"message_id": "1df37d17-0286-4d8b-8edf-bc4ec5be86e6",
"email": "receiver@example.com",
"event_id": "bede7236-2284-43d6-a953-1fdcafd0fdbc",
"sending_domain_name": "examplesender.com"
}
]
}
```
{% endtab %}
{% tab title="Audit Log User Login" %}
```json
{
"events": [
{
"event": "activity_log.user.login",
"description": "logged in with SSO",
"actor": {
"id": 1,
"type": "user",
"name": "John Doe"
},
"timestamp": 1735830138
}
]
}
```
{% endtab %}
{% tab title="Audit Log: Profile Update" %}
```json
{
"events": [
{
"event": "activity_log.user.updated",
"description": "updated the user profile",
"actor": {
"id": 1,
"type": "user",
"name": "John Doe"
},
"resource": {
"id": "1",
"type": "user",
"name": "John Doe"
},
"changes": {
"name": {
"from": "John",
"to": "John Doe"
}
},
"timestamp": 1735830138
}
]
}
```
{% endtab %}
{% endtabs %}
### Receive events (JSON Lines format)
Mailtrap sends a `POST` request to your webhook URL with events in [JSON Lines](https://jsonlines.org/) format.
Each line is a separate JSON object. Parse line by line.
**Your endpoint should:**
* Accept `Content-Type: application/jsonl`
* Return HTTP 200 to acknowledge receipt
* Process events asynchronously
**Payload**
object · SendingWebhookEvent optional Email lifecycle webhook event
**event** string · enum required\ Event type\ Possible values: `delivery` `open` `click` `unsubscribe` `spam` `soft bounce` `bounce` `suspension` `reject`
**message\_id** string required\ Unique message ID
**sending\_stream** string · enum required\ Sending stream used\ Possible values: `transactional` `bulk`
**email** string required\ Recipient email address
**sending\_domain\_name** string required\ Sending domain name
**category** string optional\ Category assigned when sending
**custom\_variables** object optional\ Custom variables from the email
* **Other properties** string | number | boolean optional
**timestamp** integer required\ Unix epoch timestamp
**event\_id** string required\ Unique event ID (use for idempotency)
**reason** string optional\ Reason (for `suspension` and `reject` events)
**response** string optional\ Server response (for `soft bounce` and `bounce` events)
**response\_code** integer optional\ SMTP response code (for `soft bounce` and `bounce` events)
**bounce\_category** string optional\ Bounce category (for `soft bounce` and `bounce` events)
**ip** string optional\ User IP address (for `open`, `click`, `unsubscribe` events)
**user\_agent** string optional\ User agent (for `open`, `click`, `unsubscribe` events)
**url** string optional\ Clicked URL (for `click` events)
object · ActivityLogWebhookEvent optional Account activity webhook event (Enterprise only)
**event** string required\ Activity log event type\ Example: `activity_log.user.updated`
**description** string required\ User-friendly event description\ Example: `updated the user profile`
**actor** object required\ User or system that performed the action
* **id** integer optional\ Actor ID\ Example: `1`
* **type** string · enum optional\ Actor type\ Possible values: `user` `api_token`
* **name** string optional\ Actor name\ Example: `John Doe`
**resource** object optional\ Affected resource (optional)
* **id** string optional\ Resource ID\ Example: `1`
* **type** string · enum optional\ Resource type\ Possible values: `user` `api_token` `billing` `account` `sso_config` `sending_domain` `project` `inbox` `contact_list` contact\_field `contact_segment`
* **name** string optional\ Resource name\ Example: `John Doe`
**changes** object optional\ Changes made (optional)\ Example: `{"name":{"from":"John","to":"John Doe"}}`
* **Other properties** object optional
**timestamp** integer required\ Unix epoch timestamp\ Example: `1735830138`
**Responses**
| `200` | Return 200 to acknowledge successful receipt |
| ------------------------------------------ | -------------------------------------------------------- |
| `500` | Any other status triggers retry (40 retries every 5 min) |
**Payload**
{% tabs %}
{% tab title="Delivery events" %}
```jsonl
{"event":"delivery","timestamp":1728669927,"sending_stream":"transactional","category":"Password reset","message_id":"1df37d17-0286-4d8b-8edf-bc4ec5be86e6","email":"receiver@example.com","event_id":"bede7236-2284-43d6-a953-1fdcafd0fdbc","sending_domain_name":"examplesender.com"}
{"event":"delivery","timestamp":1728669927,"sending_stream":"transactional","category":"Email confirmation","message_id":"ca7974af-7212-42aa-99fb-cc4742d0658b","email":"another@example.com","event_id":"657b8544-6a95-4c47-997f-6e47922a5052","sending_domain_name":"examplesender.com"}
```
{% endtab %}
{% tab title="Bounce events" %}
```jsonl
{"event":"bounce","timestamp":1728669927,"sending_stream":"transactional","message_id":"1df37d17-0286-4d8b-8edf-bc4ec5be86e6","email":"receiver@example.com","event_id":"bede7236-2284-43d6-a953-1fdcafd0fdbc","response":"[CS01] Message rejected","response_code":555,"bounce_category":"spam","sending_domain_name":"examplesender.com"}
```
{% endtab %}
{% tab title="Mixed events" %}
```jsonl
{"event":"delivery","timestamp":1728669927,"message_id":"abc-123","email":"user1@example.com","event_id":"evt-1","sending_stream":"transactional","sending_domain_name":"example.com"}
{"event":"open","timestamp":1728669930,"message_id":"abc-123","email":"user1@example.com","event_id":"evt-2","sending_stream":"transactional","ip":"192.168.1.1","sending_domain_name":"example.com"}
{"event":"click","timestamp":1728669935,"message_id":"abc-123","email":"user1@example.com","event_id":"evt-3","sending_stream":"transactional","url":"https://example.com","sending_domain_name":"example.com"}
```
{% endtab %}
{% endtabs %}
### Audit Log event structure
Audit Log events include the following fields:
* **event** — The event type
* Example: `activity_log.user.updated`
* **description** — The event description. Meant to be a user-friendly representation of the event type.
* Example: `updated the user profile`
* **actor** — Object representing the actor who executed the action or if the action was performed by the system actor.
* Example: `{"id":1,"type":"user","name":"Jack"}` or `{"name":"Mailtrap"}`
* **resource** — Optional object representing the resource affected by the action
* Example: `{"id":17,"type":"sandbox","name":"Main"}`
* **changes** — Optional object representing the changes made to the resource
* Example: `{"name":{"from":"John","to":"John Doe"}}`
* **timestamp** — The timestamp in Unix epoch format
* Example: `1735830138`
All stats are built on the events, and you get most event information from the Mailtrap UI.
### Retry schedule and batches
#### Retry schedule
If your endpoint is down and doesn't respond with 200 OK, we'll retry multiple times. The scheduling logic is as follows:
* **Retry** - 40 retries every 5 minutes. The webhook will be considered failed if we don't receive 200 OK with all retries. If the webhook fails, we'll pause it and notify you by email. You'll need to check its settings and resume it manually.
* **Timeout** - 30 seconds. If your endpoint doesn't respond within that time, the webhook event batch will go to the retry schedule.
#### Batches
Webhooks are delivered in batches, so a single request can contain multiple events. This reduces the number of requests to your endpoint and lowers load on your infrastructure.
Mailtrap can include up to 500 events per delivery. Events are collected and sent every 30 seconds (if there are events to deliver).
The batch format depends on the webhook payload type you choose:
* **JSON**: events are sent as a JSON array in a single payload.
* **JSON Lines**: events are sent as one JSON object per line (not wrapped in an array).
### Webhook Signature Verification
Mailtrap signs all webhook requests to ensure they originate from Mailtrap and haven't been tampered with.
#### Overview
Mailtrap uses [HMAC-SHA256](https://tools.ietf.org/html/rfc2104) to sign webhook payloads. Each webhook has a unique signing secret that you can use to verify the authenticity of incoming requests.
### How it works
* Signature Header – Mailtrap includes a \`Mailtrap-Signature\` header in every webhook request.
* Signature Algorithm – The signature is computed using HMAC-SHA256.
* Signature Format – The signature is a hexadecimal-encoded string.
* Signing Secret – Each webhook has a unique signing secret (32 hex characters).
### Getting your signing secret
The signing secret is automatically generated when you create a webhook. You can view and manage your signing secret in the Mailtrap UI:
{% stepper %}
{% step %}
#### Find the webhook you want to configure in to your webhooks settings
{% endstep %}
{% step %}
#### The signing secret will be displayed in the webhook details
Then, you can:
* Copy the secret to use in your verification code.
* Reset it at any time from the UI if you wish to (i.e., for security reasons).
**Important**: When you reset the signing secret, the old secret becomes invalid immediately. Make sure to update your verification code with the new secret.
{% endstep %}
{% endstepper %}
#### Verifying the signature
To verify a webhook signature, you need to:
1. Extract the \`Mailtrap-Signature\` header from the incoming request
2. Get the raw request body (as bytes/string, not parsed JSON)
3. Compute HMAC-SHA256 using your signing secret and the raw body
4. Compare the computed signature with the header value using a constant-time comparison
**Important notes:**
* **Use the raw request body** – Do not parse the JSON first. Use the raw bytes/string exactly as received.
* **Constant-time comparison** – Always use a constant-time comparison function to prevent timing attacks.
* `Content-Type` – The signature is computed on the raw body regardless of Content-Type (JSON or JSONL)
#### Code examples
{% tabs %}
{% tab title="Ruby" %}
```ruby
ruby
require 'openssl'
def verify_webhook_signature(request_body, signature_header, signing_secret)
return false if signature_header.blank? || request_body.blank?
computed_signature = OpenSSL::HMAC.hexdigest(
OpenSSL::Digest.new('sha256'),
signing_secret,
request_body
)
# Use secure_compare for constant-time comparison
Rack::Utils.secure_compare(computed_signature, signature_header)
end
```
{% endtab %}
{% tab title="Rails controller" %}
```ruby
def webhook_received
signature = request.headers['Mailtrap-Signature']
body = request.raw_post
signing_secret = 'your_signing_secret_here'
unless verify_webhook_signature(body, signature, signing_secret)
head :bad_request
return
end
# Process the webhook...
end
```
{% endtab %}
{% tab title="Python" %}
```python
import hmac
import hashlib
def verify_webhook_signature(request_body, signature_header, signing_secret):
if not signature_header or not request_body:
return False
computed_signature = hmac.new(
signing_secret.encode('utf-8'),
request_body.encode('utf-8'),
hashlib.sha256
).hexdigest()
# Use hmac.compare_digest for constant-time comparison
return hmac.compare_digest(computed_signature, signature_header)
```
{% endtab %}
{% tab title="Flask" %}
```python
from flask import request
@app.route('/webhook', methods=['POST'])
def webhook_received():
signature = request.headers.get('Mailtrap-Signature')
body = request.get_data(as_text=True)
signing_secret = 'your_signing_secret_here'
if not verify_webhook_signature(body, signature, signing_secret):
return '', 400
# Process the webhook...
return '', 200
```
{% endtab %}
{% tab title="Node.js / Express" %}
```javascript
const crypto = require('crypto');
function verifyWebhookSignature(requestBody, signatureHeader, signingSecret) {
if (!signatureHeader || !requestBody) {
return false;
}
const computedSignature = crypto
.createHmac('sha256', signingSecret)
.update(requestBody, 'utf8')
.digest('hex');
// Use crypto.timingSafeEqual for constant-time comparison
const signatureBuffer = Buffer.from(signatureHeader, 'hex');
const computedBuffer = Buffer.from(computedSignature, 'hex');
if (signatureBuffer.length !== computedBuffer.length) {
return false;
}
return crypto.timingSafeEqual(signatureBuffer, computedBuffer);
}
// Usage in Express
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['mailtrap-signature'];
const body = req.body.toString('utf8');
const signingSecret = 'your_signing_secret_here';
if (!verifyWebhookSignature(body, signature, signingSecret)) {
return res.status(400).send('Invalid signature');
}
// Process the webhook...
res.status(200).send('OK');
});
```
{% endtab %}
{% tab title="Express" %}
```javascript
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['mailtrap-signature'];
const body = req.body.toString('utf8');
const signingSecret = 'your_signing_secret_here';
if (!verifyWebhookSignature(body, signature, signingSecret)) {
return res.status(400).send('Invalid signature');
}
// Process the webhook...
res.status(200).send('OK');
});
```
{% endtab %}
{% tab title="PHP" %}
```php
How it works
All SMTP sending exits through proxy instances with Elastic IPs from these ranges. Webhook traffic (audit logs, transactional events, test webhooks) routes through NAT gateways pinned to the same ranges.
To whitelist, add these to your firewall's inbound rules:
```
# IPv4 CIDR blocks - covers both sending and webhooks
45.158.83.0/24
5.181.200.0/24
# Or, for webhooks only (specific IPs)
45.158.83.129
45.158.83.130
# Protocols
TCP - SMTP (port 25/587/465) for sending
TCP - HTTPS (port 443) for webhooks
```
{% hint style="info" %}
For automated firewall provisioning (Terraform, CloudFlare, AWS Security Groups), use the machine-readable endpoint:
{% endhint %}
When to use it
* Your webhook endpoint sits behind a firewall that blocks unknown IPs.
* Your security team requires an explicit allowlist for all inbound traffic.
* You're automating infrastructure and need static CIDRs for IaC templates.
* You're in a regulated industry (finance, healthcare, insurance) with strict network policies.
Limitations
* IPv6 ranges are AWS-provided, not Mailtrap-owned—available on request.
* Specific sending IPs may change; whitelist the full /24 range rather than individual addresses.
# Static IPs for sending & webhooks
Mailtrap sends all outgoing traffic, both SMTP email delivery and webhook callbacks, from a fixed set of Mailtrap-owned IP ranges. Two IPv4 CIDR blocks cover everything: `45.158.83.0/24` and `5.181.200.0/24`.
### How it works
All SMTP sending exits through proxy instances with Elastic IPs from these ranges. Webhook traffic (audit logs, transactional events, test webhooks) routes through NAT gateways pinned to the same ranges.
To whitelist, add these to your firewall's inbound rules:
```
# IPv4 CIDR blocks — covers both sending and webhooks
45.158.83.0/24
5.181.200.0/24
# Or, for webhooks only (specific IPs)
45.158.83.129
45.158.83.130
# Protocols
TCP — SMTP (port 25/587/465) for sending
TCP — HTTPS (port 443) for webhooks
```
{% hint style="info" %}
For automated firewall provisioning (Terraform, CloudFlare, AWS Security Groups), use the machine-readable endpoint:
{% endhint %}
### When to use it
* Your webhook endpoint sits behind a firewall that blocks unknown IPs
* Your security team requires an explicit allowlist for all inbound traffic
* You're automating infrastructure and need static CIDRs for IaC templates
* You're in a regulated industry (finance, healthcare, insurance) with strict network policies
### Limitations
* IPv6 ranges are AWS-provided, not Mailtrap-owned — available on request
* Specific sending IPs may change; whitelist the full /24 range rather than individual addresses
### FAQ
Can I whitelist specific webhook IPs?
Both SMTP sending and webhooks use the same Mailtrap-owned IPv4 ranges:
* `45.158.83.0/24`
* `5.181.200.0/24`
Protocols: SMTP for sending, HTTPS for webhooks. TCP, any port.\
For IPv6 — contact support.
To automate IP retrieval, use the JSON reference: What are Mailtrap’s IP ranges for firewall whitelisting?
Yes. Add both `45.158.83.0/24` and `5.181.200.0/24` for webhook IP whitelisting. These are the same ranges used for SMTP sending, so one set of firewall rules covers everything.
To automate IP retrieval, use the JSON reference:
# Mailtrap CLI app
Mailtrap CLI is a command-line tool for accessing Mailtrap features that allow you to send emails, inspect sandbox inboxes, monitor deliverability stats, and administer domains, templates, contacts, and more, all from your terminal.
Link to official [GitHub documentation](https://github.com/mailtrap/mailtrap-cli).
### How it works
#### Installation
To install Mailtrap CLI app, choose one of the following installation methods:
* Homebrew (macOS / Linux):
```
brew install mailtrap/cli/mailtrap
```
* Download binary
Download the latest release from [GitHub Releases](https://github.com/mailtrap/mailtrap-cli/releases) and add it to your `PATH`.
* Go install:
```
go install github.com/mailtrap/mailtrap-cli@latest
```
#### Authentication
To validate your token, detect your account ID, and save both to **\~/.mailtrap.yaml** run the following command:
```
mailtrap configure --api-token YOUR_TOKEN
```
Or, you can also use environment variables:
```
export MAILTRAP_API_TOKEN=your-token
```
#### Using the CLI
Then use any of the \~87 commands across 20 resource groups. A few examples:
```
# Send a transactional email
mailtrap send transactional \
--from "app@yourdomain.com" \
--to "user@example.com" \
--subject "Order confirmed" \
--html "
Thanks for your order
"
# Check spam score on a sandbox message
mailtrap messages spam-score --sandbox-id 12345 --id 67890
# Pull sending stats by mailbox provider
mailtrap stats by-esp --start-date "2025-01-01" --end-date "2025-04-07" --domain-ids 111
# Bulk import contacts from JSON
mailtrap contacts import --file contacts.json
```
Every command supports `--output` json for scripting and CI/CD integration. Shell completion is available for Bash, Zsh, Fish, and PowerShell.
# Help & Support
Get help with Email API/SMTP issues and find answers to common questions.
Find answers to common questions and troubleshoot issues with Mailtrap's Email API/SMTP service. Our comprehensive help resources are designed to get you back on track quickly.
## Resources
Frequently Asked Questions
Browse our comprehensive FAQ section for quick answers to common questions about Email API/SMTP setup, integration, and best practices.
## Common Issues
### Authentication & Access
* [401 Unauthorized Error](/email-api-smtp/help/troubleshooting/unauthorized-401-error) - Fix API token and authentication issues
* [Domain Not Allowed](/email-api-smtp/help/troubleshooting/sending-from-domain-not-allowed) - Resolve domain verification problems
### Email Delivery Issues
* [From Header Mismatch](/email-api-smtp/help/troubleshooting/from-header-domain-mismatch) - Fix sender address configuration
* [SSL Cipher Error](/email-api-smtp/help/troubleshooting/ssl-cipher-overlap-error) - Resolve SSL/TLS connection issues
* [Office 365 Quarantine](/email-api-smtp/help/troubleshooting/ms-office-365-quarantine) - Handle Microsoft email filtering
## Getting Help
### Self-Service Resources
1. Check the [FAQs](/email-api-smtp/help/faqs) for quick answers
2. Review the [Troubleshooting Guide](/email-api-smtp/help/troubleshooting)
3. Search our documentation using the search bar
4. Check our [API Reference](https://docs.mailtrap.io/developers)
### :comments-question-check:Contact Support
If you can’t find the answer you need in our documentation or something doesn’t work as expected, feel free to contact our support team and speak with an agent, we’re here to help.
If the information provided (including AI responses) doesn’t fully resolve your question or your case requires a closer look, our team can review your setup and assist further.
You can get in touch with the Mailtrap Support team using one of the following ways:
* **From your Mailtrap account**
1. Log in to your account [here](https://mailtrap.io/signin).
2. Go to the :circle-question:[**Help Center**](https://mailtrap.io/help-center) > :message-dots: Get Help
3. Click **Start conversation.**
* **Email us at** 📧
Whether you need technical assistance, help troubleshooting interface or account-specific issues, or simply want to talk to customer support, our team will be happy to assist you.
### Before Contacting Support
Please have the following information ready:
* Your account email
* Error messages (exact wording)
* Request IDs from email logs
* Steps to reproduce the issue
* Screenshots if applicable
## Feedback & suggestions
*We welcome technical feedback and contributions that help us improve Mailtrap’s functionality and documentation. Please use the appropriate channel depending on the type of request.*
#### :bug:Bug Reports
**If you encounter a product issue or unexpected behavior, please** [#contact-support](#contact-support "mention")**.**
To help us investigate efficiently, include:
* A detailed description of the issue
* Exact reproduction steps
* Relevant stream, domain, sandbox, or account details
* Timestamps (including timezone)
* Screenshots or logs if available
#### :file-circle-plus:Feature Requests
For product improvements or new feature proposals, use **our** [**Public Roadmap**](https://mailtrap.featurebase.app/en) **portal**.
There you can:
* **Submit a new feature request**
* **Upvote existing requests**
* **Subscribe to updates for specific requests**
#### :file-doc:Documentation Improvements
If you identify unclear, incomplete, or outdated documentation:
1. Use the **feedback widget** located on the right-hand side of the page to rate the article:\
2. **Provide specific feedback** describing what should be corrected, clarified, or expanded\
This helps us continuously refine our docs.
#### :square-code:GitHub & Technical Collaboration
For open-source projects, SDKs, or public repositories, join us on [GitHub](https://github.com/mailtrap).
## Quick Solutions
### Can't send emails?
1. Verify your [API token](/email-api-smtp/setup/api-tokens) is correct
2. Check your [sending domain](/email-api-smtp/setup/sending-domain) is verified
3. Review your [sending limits](/email-api-smtp/setup/sending-limits)
4. Confirm your [integration](/email-api-smtp/setup/api-integration) is properly configured
### Emails not reaching inbox?
1. Check [email logs](/email-api-smtp/analytics/logs) for delivery status
2. Review [bounce categorization](/email-api-smtp/deliverability/bounce-categorization) for issues
3. Verify SPF, DKIM, and DMARC records
4. Check if recipients are on [suppressions list](/email-api-smtp/deliverability/suppressions-list)
### Integration issues?
1. Review the [API integration guide](/email-api-smtp/setup/api-integration)
2. Check the [SMTP integration guide](/email-api-smtp/setup/smtp-integration)
3. Test with [Email Sandbox](/email-sandbox/overview) first
4. Use our [API reference](https://docs.mailtrap.io/developers) for detailed endpoints
# Sending Glossary
Definitions of key terms and phrases used in Mailtrap Email API/SMTP, including DNS records, email events, SMTP settings, and deliverability concepts.
This glossary explains key terms and phrases used in Mailtrap Email API/SMTP.
## A
**API sending** — Send emails using Mailtrap's API endpoints. Our API is compatible with SendGrid, Mandrill, and Mailgun APIs.
**AWS CLI** — An abbreviation for Amazon Web Services Command Line Interface. It's a tool to control and manage AWS resources. Mailtrap provides DNS records in JSON format for AWS Route53 to create records using AWS CLI.
**AWS Route53** — A DNS service from Amazon. If you use it, you can copy-paste the DNS records in JSON format and add them to AWS Route53.
## B
**Bounce** — One of the possible events, also known as "hard bounce". Most commonly, a bounce occurs when the recipient's email address is incorrect or the server declines a message. It indicates a permanent failure of delivery. You won't be able to send any further emails to this address from this domain.
**Bounce rate** — The percentage of bounced emails. A bounce event may happen due to an invalid address, your email not passing certain mailbox provider criteria, or a connection issue. Note that it's the recipients who bounce the emails, not Mailtrap. To secure great deliverability in the long run, you want to keep the bounce rate low.
## C
**Category** — A method used to categorize different types of emails sent from your Mailtrap account. You specify a category when creating an email as one of its parameters. For each unique category specified this way, you'll be able to see separate email analytics. Example categories can include password reset, invoice, welcome email, etc.
**Click** — An event that occurs when a link in your email is clicked. Click tracking must be enabled prior to sending an email for any clicks to be recorded.
{% hint style="info" %}
When an email with click tracking enabled is forwarded, all further clicks will also be included in the click count.
{% endhint %}
**Click rate** — The percentage of opened emails that got one or more clicks on their links. All clicks are recorded and can be seen under Events History in the Email Logs menu. But only the first click is calculated towards the Click Rate within a selected period.
**Client sending IP** — IP address of a device that was used to send an email.
**cURL** — A command-line tool to transfer data using various protocols and an option to quickly make API calls. With Mailtrap, you get a sample cURL code with an API to send an email to yourself.
## D
**DNS records** — A DNS record is an instruction stored at a DNS server. It describes how to handle requests from that domain. Certain records you add give Mailtrap a guarantee that you own the domain and have the right to send from it. Other records let mailbox providers know that you're an authenticated server and boost your email deliverability.
### DNS record types
| Record type | Description |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CNAME domain authentication** | DNS record used for verification purposes. Mailtrap uses it to verify that you're the owner of a domain and can send through it. |
| **SPF** | A very common TXT-type authentication method. It specifies which IP addresses (mail servers) are authorized to send emails on your behalf. |
| **DKIM** | A CNAME type authentication method, an encrypted digital signature that comes with each email. Mailtrap uses private keys to sign the body and the header of your emails before sending them to the mailbox providers. |
| **DMARC** | A TXT type email authentication protocol used to ensure an authenticated email domain aligns with the domain found in the `from:` address. It's an additional security layer that tells mailbox providers what to do with your emails should they fail authentication. |
**Domain** (or **Sending Domain**) — The domain used in the `from:` field of an email. You must be the owner of a domain and have it verified to be able to send emails from Mailtrap. No public domains can be used with Mailtrap Sending (e.g. Gmail, Hotmail).
## E
**Email Logs** — The list of all the emails sent from your account. Contains all the vital details of each message, including the recipient's details, timestamps, HTML/CSS of a message, opens/clicks stats, as well as additional tools, such as email preview or spam check.
**Event** — A particular action that occurred to your email. The available events are: Sending, Delivery, Reject, Open, Click, Bounce, Spam, Unsubscribe, Soft Bounce, Suspension. In the Email Logs, you can view all the events associated with a particular message in chronological order.
## M
**Mailbox provider** — An email service used by the end recipient to receive emails. Examples include Gmail, Outlook, Cisco email protection, or Mimecast email protection.
**Mailtrap sending IP** — IP address of Mailtrap, used to send a message to the final recipient.
## O
**Open** — An event that occurs when an email is opened. Mailtrap inserts an invisible pixel into an email. When a message is opened and a pixel is "displayed", an 'open' event is recorded.
{% hint style="info" %}
Some mailbox providers, browsers, and plugins block the tracking of opens. Users or their providers can also block images from being displayed. In each of these cases, no "open" event will be recorded even if an email is opened.
{% endhint %}
## R
**Recipient IP** — IP address of a device or an email server where an email was opened. If a message is opened on devices using different IP addresses, multiple recipient IPs will be recorded. If a message is not opened at all, no recipient IP will be displayed.
## S
**SMTP** — Short for Simple Mail Transfer Protocol, SMTP is a protocol that facilitates email transmissions.
### SMTP Settings
| Setting | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Host** | Name of Mailtrap's outgoing email sending server. |
| **Port** | Communication endpoints responsible for moving email data between servers via SMTP. Mailtrap supports 587, 2525, and 25 ports. We recommend using 587 because it's the standard secure SMTP port. |
| **Username** | When configuring Mailtrap Sending with SMTP, the username is 'api'. |
| **Password** | Mailtrap uses API tokens as SMTP passwords. By default, a token is generated when you add a domain. |
| **Auth** | Authentication mechanism that Mailtrap supports. We use two common mechanisms: LOGIN, PLAIN. |
| **TLS** | Short for Transport Layer Security, TLS is a protocol that encrypts and delivers mail securely. |
**Spam** — One of the possible email events. This happens when a recipient chooses to report a message as spam. No further messages will be delivered to such recipients. Recurring spam complaints are known to very negatively influence email deliverability.
**Spam complaints** — The percentage of delivered emails that got labeled as spam by recipients. It also includes the emails that got automatically labeled as spam by mailbox providers.
**Status** — Indicates the most recent state of your message. The available statuses are: Delivered, Not Delivered, Enqueued, and Opted Out. An email can have only one status at a time.
**Suppression list** — A list of email addresses that Mailtrap won't send any further emails to. Email addresses land on a suppression list when a message bounces, a recipient unsubscribes, or they report an email as spam.
{% hint style="info" %}
Suppression lists are individual for each of your sending domains. If an address lands on such a list for domain X, it won't prevent you from sending emails to them from other verified domains.
{% endhint %}
## T
**Transactional email** — The type of email triggered by a user's action (e.g. registration, password reset, etc.) or a certain event in the system (monthly invoice, notification about a limit reached, etc.). Transactional emails are usually triggered separately for each recipient, as opposed to marketing or sales emails that are traditionally sent in batches.
## U
**Unique open rate** — The percentage of opened emails out of all delivered emails within a specified period. Recipients may block tracking on their end, so the actual open rate could be higher than what you see in Mailtrap.
**Unsubscribe** — One of the possible events. It occurs when a recipient of your email clicks on the "unsubscribe" link in your message. No further emails will be sent to this recipient from a given domain.
# FAQs
Frequently asked questions about Mailtrap Email API/SMTP.
This page covers frequently asked questions about Mailtrap Email API/SMTP. For technical issues and error troubleshooting, see the [Troubleshooting section](/email-api-smtp/help/troubleshooting).
#### Getting Started
What is Mailtrap?
Mailtrap is an email delivery service to send transactional and promotional emails. Popular among developer and product teams for its Email API and SMTP solutions.
How do I integrate Mailtrap with my application?
1. [Sign up](https://mailtrap.io/register/signup/) for an account.
2. Go to Email Sending and select [Sending Domains](https://mailtrap.io/domains).
3. After you've added and verified all the DNS records, wait for the Compliance Check to be completed.
4. Proceed to integrate Mailtrap with your application via SMTP or API.
Learn more:
* [API Integration](/email-api-smtp/setup/api-integration)
* [SMTP Integration](/email-api-smtp/setup/smtp-integration)
* [Sending Domain Setup](/email-api-smtp/setup/sending-domain)
If you have any questions, contact us at .
Can I send emails without my domain?
No, you can't.
To send emails, Mailtrap requires you to add a sending domain, authenticated and verified using the DNS records Mailtrap provides.
Can I send emails on behalf of other domains?
No, you can't.
If you verified mydomain.com, you can send emails only on behalf of your domain.
#### Domain Setup
Should I use my domain name with www. ?
No, you should use your domain without it.
Please check our [Sending Domain Setup Guide](/email-api-smtp/setup/sending-domain) for detailed instructions on adding and verifying your domain.
When I add a domain to Mailtrap, does that include subdomains?
No, you need to add and verify each subdomain/domain separately.
#### Features & Capabilities
Can I receive emails with Mailtrap?
Right now, Mailtrap doesn't provide MX records to catch inbound emails, so they'll bounce.
Another option is to use a real email address in the "reply-to" field if a recipient replies to your email.
Can I send emails to end-users with Mailtrap?
Yes, you can. Mailtrap is an email delivery service to send transactional and promotional emails. Popular among developer and product teams for its Email API and SMTP solutions.
Can I force an encrypted connection?
Yes, you can enforce encrypted connections. Mailtrap SMTP server uses STARTTLS, which works for all SMTP ports. We support only TLS connections because of the POODLE vulnerability (SSLv2 and SSLv3 are disabled).
I would like to whitelist live.smtp.mailtrap.io on my firewall. What is Mailtrap's IP range?
We use AWS with auto-balancing, so our IP ranges are the following:
#### Billing & Limits
How does Mailtrap billing work?
We bill each email. For example, if an email has 3 recipients - we bill 3 of them. If it has + 3 in CC, we bill 6 together. The same goes for recipients in BCC.
What is the email size limit?
The maximum size of an email with attachments for Mailtrap is 10 MB. Upon request, we can extend the limit in some cases to 30 MB.
What is the monthly message limit for email sending?
It's the maximum number of emails you can send with Mailtrap per month. The total number of emails per month depends on the subscription plan.
If you reach your monthly limit, you'll receive the SMTP protocol error: "535 5.7.0 Monthly messages limit reached". We also send out notifications for having used 80%, 90%, and 100% of the monthly limit.
To continue sending when you're over the limit, please upgrade your subscription plan. Alternatively, you can wait until the next billing period starts, when the limit is reset.
For more details, check the [Sending Limits](/email-api-smtp/setup/sending-limits) and [Pricing page](https://mailtrap.io/pricing/?tab=api).
How much does Mailtrap cost?
Mailtrap offers flexible pricing plans that scale with your email volume, from starter plans for small projects to enterprise solutions for high-volume senders.
For current pricing and to choose a plan that best fits your needs, visit our [pricing page](https://mailtrap.io/pricing/?tab=api).
#### Data & Privacy
Is it possible to export Email logs?
Right now, it's not possible, but there's a workaround.
You can set up [Webhooks](/email-api-smtp/advanced/webhooks) to automatically collect logs. And you can use a tool like [Zapier](/guides/integrations/zapier), for example, to create a spreadsheet from your webhooks.
Does Mailtrap comply with the GDPR?
The General Data Protection Regulation (GDPR) came into effect on May 25, 2018. We have implemented appropriate technical and security processes to ensure Mailtrap's full compliance with this regulation.
For more details, refer to our:
* [Privacy Policy](https://mailtrap.io/privacy/)
* [Navigational Information](https://mailtrap.io/navigational-info/)
* [Data Protection Agreement](https://mailtrap.io/dpa/)
Do you have a bug bounty program?
We do not. In case you have found a vulnerability on our website that you are eager to report to us, you are welcome to do so at . All issue reporters will be mentioned on our [changelog page](https://mailtrap.io/changelog/).
# Troubleshooting
Common issues and solutions for Mailtrap Email API/SMTP.
This section covers common issues you might encounter when using Mailtrap Email API/SMTP and their solutions.
### Common Issues
#### Authentication & Authorization
* [Unauthorized Error (401 Code)](/email-api-smtp/help/troubleshooting/unauthorized-401-error) - Issues with API credentials, tokens, or domain verification
* [Sending from Domain Not Allowed](/email-api-smtp/help/troubleshooting/sending-from-domain-not-allowed) - Domain verification and FROM address problems
#### Email Delivery
* [From Header Domain Mismatch](/email-api-smtp/help/troubleshooting/from-header-domain-mismatch) - Fixing FROM header configuration issues
#### SSL & Security
* [SSL Cipher Overlap Error (Error 1001)](/email-api-smtp/help/troubleshooting/ssl-cipher-overlap-error) - Custom tracking domain SSL certificate issues
#### Third-Party Services
* [MS Office 365 Quarantine](/email-api-smtp/help/troubleshooting/ms-office-365-quarantine) - Mailtrap emails going to Office 365 quarantine
### Need More Help?
If you don't find the solution to your problem here:
1. Check our [FAQs](/email-api-smtp/help/faqs) for general questions
2. Contact support at
3. Visit the API documentation for technical details
# 401 Unauthorized Error
How to fix "Unauthorised" (401) authentication errors in Mailtrap Email API/SMTP.
If you're getting an "Unauthorised" error (401 code) when trying to send emails, there are several possible causes and solutions.
### Common Causes
**1. Sending from Unverified Domain**
Make sure you're sending from the domain that you've set up and verified in Mailtrap. Using any other domain will result in this error.
{% hint style="danger" %}
If you verified `example.com`, you can only send from `*@example.com` addresses. Attempting to send from `otherdomain.com` will fail with a 401 error.
{% endhint %}
**2. API Token Permissions**
If you've configured a custom API token for your domain, make sure it has proper permissions to send emails.
Check your [API tokens](https://mailtrap.io/settings/api-tokens) and verify the token has:
* Email sending permissions
* Access to the correct domain
* Valid expiration date (if applicable)
**3. Incorrect Credentials**
Make sure you're using the correct SMTP/API credentials provided in the Integration tab of your domain.
SMTP and API credentials in Integration tab
### How to Fix
{% stepper %}
{% step %}
**Verify Your Domain**
1. Go to [Sending Domains](https://mailtrap.io/domains)
2. Ensure your domain shows the **Verified** badge
3. If not verified, complete the DNS record setup
{% endstep %}
{% step %}
**Check API Token (if using custom tokens)**
1. Go to [API Tokens](https://mailtrap.io/settings/api-tokens)
2. Verify the token has **Send Email** permissions
3. Ensure it's assigned to the correct domain
4. Check that the token hasn't expired
{% endstep %}
{% step %}
**Verify Credentials**
Navigate to: **Sending Domains > Integration > Integrate** (under Transactional or Bulk Stream)
Copy the exact credentials shown there:
* For SMTP: Username and Password
* For API: API Token
Replace your current credentials with these values.
{% endstep %}
{% step %}
**Test with cURL**
Use the cURL code example to test if the error persists:
1. Go to **Sending Domains > Integration > Integrate**
2. Select your stream (Transactional or Bulk)
3. Go to **Code Samples > cURL**
4. Copy and run the cURL command
Code Samples section with cURL example
If the cURL test succeeds but your application fails, the issue is with your application's configuration.
{% endstep %}
{% endstepper %}
### Still Having Issues?
If you've verified all the above and still getting 401 errors:
* Double-check that your FROM address domain matches your verified domain
* Ensure there are no extra spaces or special characters in your credentials
* Contact support at with:
* Your domain name
* The exact error message
* A code sample showing how you're attempting to send
### Related Articles
* [Sending Domain Setup](/email-api-smtp/setup/sending-domain)
* [API Integration](/email-api-smtp/setup/api-integration)
* [SMTP Integration](/email-api-smtp/setup/smtp-integration)
* [Sending from Domain Not Allowed](/email-api-smtp/help/troubleshooting/sending-from-domain-not-allowed)
# Domain Not Allowed
How to fix "Sending from domain is not allowed" (550 5.7.1) error in Mailtrap Email API/SMTP.
### Error Message
```
Error: Mail command failed: 550 5.7.1 Sending from domain is not allowed
```
This error occurs when you try to send an email using SMTP with a domain that doesn't match your verified domain in Mailtrap.
### Common Causes
**1. Domain Mismatch**
You're sending an email with `FROM: {anything}@mydomain.com`, but in Mailtrap, you've verified `anotherdomain.com`.
**The verified domain and FROM domain in your emails must match.**
{% hint style="warning" %}
If you verified `example.com` in Mailtrap, you can only send emails from `*@example.com` addresses.
{% endhint %}
**2. Domain Not Verified or Compliance Check Failed**
Your domain might not be fully verified, or you haven't passed the Compliance Check.
### How to Fix
{% stepper %}
{% step %}
**Check Your Verified Domains**
Go to [Sending Domains](https://mailtrap.io/domains) in your Mailtrap account.
{% endstep %}
{% step %}
**Verify Domain Status**
Look for the **Verified** badge next to your domain. If you don't see it:
1. Click on the domain
2. Check if all DNS records are found by Mailtrap (all should be green)
3. If any records are missing or incorrect, update them with your DNS provider
{% endstep %}
{% step %}
**Check Compliance Status**
Scroll down to see the **Compliance Check** status.
If the compliance check hasn't passed:
* Review any additional steps required
* Complete any pending actions
* Wait for the check to complete
{% endstep %}
{% step %}
**Update Your FROM Address**
Ensure your application sends emails from an address that matches your verified domain:
* **Correct:** `noreply@yourdomain.com` (if `yourdomain.com` is verified)
* **Incorrect:** `noreply@otherdomain.com` (if `otherdomain.com` is not verified)
{% endstep %}
{% endstepper %}
### Related Articles
* [Sending Domain Setup](/email-api-smtp/setup/sending-domain)
* [SMTP Integration](/email-api-smtp/setup/smtp-integration)
* [Unauthorized Error (401 Code)](/email-api-smtp/help/troubleshooting/unauthorized-401-error)
# From Header Mismatch
How to fix "From: Header does not match the sender's domain" error in Mailtrap Email API/SMTP.
### Error Message
```
From: Header does not match the sender's domain
```
This error occurs when the `From:` header in your email doesn't match your verified domain in Mailtrap.
### The Requirement
To send email with Mailtrap, your `From:` header **must match** your verified domain.
{% hint style="info" %}
**Example:** If your verified domain in Mailtrap is `acme.com`, your `From:` address must be `{anything}@acme.com`.
If you're sending from a subdomain like `mail.acme.com`, your `From:` address must match that subdomain exactly.
{% endhint %}
### Common Causes
**1. Unverified Domain**
Your domain hasn't been added or verified in Mailtrap yet.
**Solution:**
1. Go to [Sending Domains](https://mailtrap.io/domains)
2. Add your domain
3. Complete the DNS verification process
**2. Envelope From vs Header From Mismatch**
In some frameworks (like Laravel), the `MAIL_FROM_ADDRESS` variable is used for the envelope from address, but it's not the same as the header `From:` address.
{% hint style="warning" %}
Make sure both the **envelope from** and the **header from** use the same domain.
{% endhint %}
**3. Subdomain Confusion**
If you verified `example.com` but are trying to send from `mail.example.com`, you need to verify the subdomain separately.
### How to Fix
{% stepper %}
{% step %}
**Verify Your Domain**
First, check if your domain has been added to your Mailtrap account.
1. Go to [Sending Domains](https://mailtrap.io/domains)
2. Look for your domain in the list
3. Ensure it has the **Verified** badge
If not verified, complete the DNS setup process.
{% endstep %}
{% step %}
**Check Your Email Configuration**
Ensure your email message has a `From:` header that contains an address on your verified domain.
**Example for Laravel:**
{% code title=".env" %}
```bash
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="Your App Name"
```
{% endcode %}
Make sure `MAIL_FROM_ADDRESS` uses your verified domain.
{% endstep %}
{% step %}
**Verify Envelope From Matches Header From**
Most likely, the envelope from address is set separately from the header. Make sure they match.
For Laravel specifically:
* Check that `MAIL_FROM_ADDRESS` in your `.env` file matches your verified domain
* Verify this address is used in both the envelope and header
{% endstep %}
{% step %}
**Test Your Configuration**
Send a test email and verify:
* The `From:` header shows your verified domain
* The envelope from (visible in email headers) matches
* No errors appear in your logs
{% endstep %}
{% endstepper %}
### Framework-Specific Examples
**Laravel**
In your `.env` file:
{% code title=".env" %}
```bash
MAIL_MAILER=smtp
MAIL_HOST=live.smtp.mailtrap.io
MAIL_PORT=587
MAIL_USERNAME=your-smtp-username
MAIL_PASSWORD=your-smtp-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"
```
{% endcode %}
Ensure `MAIL_FROM_ADDRESS` uses your verified domain.
**Other Frameworks**
The principle is the same across all frameworks:
1. Set your `From:` address to use your verified domain
2. Ensure both envelope and header from addresses match
3. Verify the domain in Mailtrap before sending
### Still Having Issues?
If you've verified your domain and updated your configuration but still see this error:
* Check your email sending code for hardcoded `From:` addresses
* Look for middleware or plugins that might be modifying the `From:` header
* Review your framework's documentation for email configuration
* Contact support at
### Related Articles
* [Sending Domain Setup](/email-api-smtp/setup/sending-domain)
* [SMTP Integration](/email-api-smtp/setup/smtp-integration)
* [Sending from Domain Not Allowed](/email-api-smtp/help/troubleshooting/sending-from-domain-not-allowed)
* [Unauthorized Error (401 Code)](/email-api-smtp/help/troubleshooting/unauthorized-401-error)
# Click Tracking Blocked – SSL Cipher Error
Received a 'Click tracking disabled - custom hostname blocked' alert? Read this article and learn how to fix SSL errors when using custom domains for click tracking in Mailtrap Email API/SMTP.
Click tracking or custom domain tracking issues include `SSL_ERROR_NO_CYPHER_OVERLAP` or `Error 1001` errors.
Custom domain blocked: SSL error when accessing custom domain for click tracking
### Understanding custom domain click tracking
Mailtrap allows you to use your own domain for click tracking. To achieve this:
1. You add an `mt-link` CNAME record during the domain setup process
2. Mailtrap issues a security certificate for the mt-link subdomain to ensure a secure connection
3. Certificates from **Let's Encrypt** and **Google Trust Services** are used
### Why your custom hostname was blocked
The primary cause for custom domain tracking issues is that some domains have a list of trusted Certificate Authorities (CAs) specified in **CAA records**.
{% hint style="warning" %}
If your CAA records don't include Google Trust Services and Let's Encrypt, Mailtrap won't be able to request certificates from them. This prevents click tracking from working because browsers can't establish a secure connection, hence the custom hostname issues.
{% endhint %}
### Checking your CAA records
You can check the CAA records for your domain using this command:
{% code title="Terminal" %}
```bash
dig CAA example.com
```
{% endcode %}
The output might look similar to this:
{% code title="Sample Output" %}
```
;; ANSWER SECTION:
example.com. 13990 IN CAA 0 issue "globalsign.com"
example.com. 13990 IN CAA 0 issuewild "globalsign.com"
```
{% endcode %}
In this example, the domain only allows GlobalSign to issue certificates, which is why Mailtrap cannot obtain a certificate.
### Solution: Update CAA records
You have two options:
**Option 1: Add required CAs (recommended)**
If you want to keep your existing CAA records, modify them to include Google Trust Services and Let's Encrypt:
{% code title="Required CAA Records" %}
```
# Google Trust Services
0 issue "pki.goog; cansignhttpexchanges=yes"
# Let's Encrypt
0 issue "letsencrypt.org"
```
{% endcode %}
**Option 2: Remove CAA restrictions**
If you don't need to restrict which CAs can issue certificates for your domain, you can remove the CAA records entirely.
### How to add CAA records
**CAA Record Configuration**
Field
Value
Description
Name
blank or @, depending on your provider
TTL
1 hour or any other appropriate TTL
Controls how long the record is valid.
Flag
0
0 means that no flags have been set. Please read your DNS provider's documentation for specific behavior.
Tag
issue
Allows the CA to issue certificates for this domain and its subdomains (e.g., mt-link subdomain).
Google Trust Services needs the additional parameter cansignhttpexchanges=yes.
{% hint style="info" %}
You'll need to create **two separate CAA records**: one for Google Trust Services and one for Let's Encrypt.
{% endhint %}
### Verification
After updating your CAA records:
{% stepper %}
{% step %}
**Wait for DNS propagation**
It can take several hours for the changes to your CAA records to propagate. This varies by DNS provider and TTL settings.
{% endstep %}
{% step %}
**Verify CAA records**
Run the `dig CAA example.com` command again to confirm the new records are in place.
{% endstep %}
{% step %}
**Test your mt-link subdomain**
Once propagated, you should be able to access your mt-link subdomain without SSL errors:
{% endstep %}
{% endstepper %}
### Additional resources
For DNS setup guides specific to your provider, see:
* AWS Route 53 Setup Guide
* Cloudflare DNS Setup Guide
* GoDaddy DNS Setup Guide
### Need help?
If you're still experiencing SSL errors after updating CAA records:
* Wait at least 24 hours for full DNS propagation
* Verify the records are correctly formatted (check for typos)
* Contact your DNS provider for CAA record support
* Reach out to Mailtrap support at
# Office 365 Quarantine
How to resolve your emails sent from Mailtrap Email API/SMTP being sent to Office 365 quarantine.
Sometimes transactional messages from Mailtrap (such as email confirmations, invitations to join a sandbox, invoices, etc.) can be sent to Threat Management >> Quarantine by MS Office 365.
### Solution
If you have faced this issue, follow these steps to resolve it:
{% stepper %}
{% step %}
**Access Office 365 Quarantine**
Go to .
{% endstep %}
{% step %}
**Select Mailtrap Emails**
Select the emails sent from Mailtrap that are in quarantine.
{% endstep %}
{% step %}
**Release Messages**
Click the **Release messages** button.
{% endstep %}
{% step %}
**Add to Allow List**
Check the **"Add sender to your organization's allow list"** checkbox.
This will prevent future emails from Mailtrap from being quarantined.
{% endstep %}
{% endstepper %}
### Alternative: OAuth Integration
When signing up for Mailtrap, you have the option to use Office 365 account authorization (OAuth) for smooth integration. In this case, email confirmation won't be required and you can avoid quarantine issues altogether.
### Related Articles
* [Getting Started with Email API/SMTP](/email-api-smtp/setup/sending-domain)
* [Email API/SMTP FAQs](/email-api-smtp/help/faqs)
# Overview
Test and preview emails safely in a sandbox environment before sending to production
\
Email Sandbox is a safe testing environment that captures all your test emails, preventing them from reaching real inboxes. Perfect for development, QA testing, and staging environments, it ensures your email functionality works flawlessly before going live.
For use with AI assistants
AI-readable resources:
This page as Markdown —
API reference as Markdown —
llms.txt —
llms-full.txt —
For setup with AI assistant, here is context about Mailtrap Email Sandbox:
Email Sandbox is for testing and debugging only — it is a fake SMTP server that traps all emails sent from your application. Emails sent to Sandbox never reach real recipients. No domain setup or verification is required to start using Sandbox.
For live email sending to real recipients, refer to the Email API/SMTP setup guide ().
SMTP credentials for Sandbox can be found in the Mailtrap UI or programatically. Go to Sandboxes (), select your sandbox, then open the Integration tab. Each sandbox has its own unique SMTP username and password. The host is sandbox.smtp.mailtrap.io, port 25, 465, 587 or 2525. API endpoint that returns SMTP credentials:
When you're ready to move from Sandbox to live sending, the switch depends on your integration method:
— If using SMTP directly: replace the Sandbox SMTP credentials with live sending SMTP credentials, found in Sending Domains () → select your domain → Integration tab → SMTP.
— If using a Mailtrap SDK: all official SDKs use the same pattern — a sandbox boolean flag and an inbox ID in the client constructor. To switch to live sending, set sandbox to false and drop the inbox ID.
— If using the API directly: change the endpoint from the Sandbox API ([https://sandbox.api.mailtrap.io/api/send/{inbox\_id}](https://sandbox.api.mailtrap.io/api/send/%7Binbox_id%7D)) to the Transactional () or Bulk () sending endpoint.
## What is Email Sandbox?
Email Sandbox acts as a **fake SMTP** server that traps all emails sent from your application. Instead of delivering to actual recipients, emails are captured in a secure inbox where you can:
* Preview how emails look across different clients
* Test email workflows without risk
* Validate HTML rendering and responsiveness
* Debug email issues before production
* Share test results with your team
## Key Features
### Safe Testing Environment
* **Zero Risk**: Emails never reach real recipients
* **Multiple Sandboxes**: Separate environments for different projects
* **Email Address per Sandbox**: Unique inbound email addresses for each sandbox
* **Team Collaboration**: Share sandboxes with team members
### Email Analysis Tools
* **HTML/Text Preview**: See exactly how emails render
* **Spam Score Analysis**: Predict spam filter behavior
* **Email Headers**: Inspect all technical details
* **Attachment Support**: Test file attachments
### Advanced Testing
* **Bounce Emulation**: Test bounce handling
* **API & SDKs**: Full programmatic access with official SDKs
### Collaboration Features
* **Shared Sandboxes**: Team-wide access
* **Email Forwarding**: Share specific test cases
* **Access Control**: Manage permissions
## Use Cases
### Development Testing
Perfect for developers building email features:
* Test email templates during development
* Verify dynamic content and personalization
* Debug email sending logic
* Test different email scenarios
* Validate email formatting
### QA & Staging
Essential for quality assurance:
* End-to-end workflow testing
* Cross-client compatibility checks
* Regression testing
* Performance testing
* User acceptance testing
### Email Design
Ideal for designers and marketers:
* Preview email designs
* Test responsive layouts
* Check image rendering
* Validate link tracking
* Review content formatting
## How It Works
### 1. Simple Integration
Choose your integration method:
**SMTP Configuration:**
```
Host: sandbox.smtp.mailtrap.io
Port: 2525
Username: YOUR_SANDBOX_USERNAME
Password: YOUR_SANDBOX_PASSWORD
```
**Unique Email Addresses:** Each sandbox provides unique @mailtrap.io addresses for inbound testing.
### 2. Send & Receive Test Emails
* **Outbound**: Your application sends emails normally - Sandbox captures them
* **Inbound**: Send emails to your sandbox's unique addresses for testing replies and parsing
### 3. Review & Analyze
Access your sandbox to preview, test, and share all captured emails (both sent and received).
## Quick Start
{% stepper %}
{% step %}
**Create a Sandbox**
Log in and create your first sandbox. Name it based on your project or environment.
{% endstep %}
{% step %}
**Configure Your App**
Update your application's SMTP settings with sandbox credentials.
{% endstep %}
{% step %}
**Send Test Email**
Send a test email from your application to verify the connection.
{% endstep %}
{% step %}
**Analyze Results**
Review the captured email in your sandbox inbox.
{% endstep %}
{% endstepper %}
## Integration Methods
### SMTP Integration
Works with any application or framework:
```python
# Python example
import smtplib
server = smtplib.SMTP('sandbox.smtp.mailtrap.io', 2525)
server.login('username', 'password')
server.sendmail(from_addr, to_addr, message)
```
### API Integration with Official SDKs
Full programmatic access with our official SDKs for all major languages:
**Node.js SDK:**
```javascript
const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({
token: "YOUR_API_TOKEN",
testInboxId: INBOX_ID
});
// Send test email
await client.testing.send({
from: { email: "test@example.com" },
to: [{ email: "user@example.com" }],
subject: "Test Email",
text: "Testing in sandbox"
});
```
**PHP SDK:**
```php
use Mailtrap\MailtrapClient;
use Mailtrap\Helper\ResponseHelper;
$mailtrap = new MailtrapClient('YOUR_API_TOKEN');
// Get sandbox messages
$response = $mailtrap->sandbox()
->inbox(INBOX_ID)
->messages()
->get();
```
**Available SDKs:**
* Node.js/TypeScript
* PHP
* Python
* Ruby
* Java
* Go
* .NET
### Email Address per Sandbox
Each sandbox automatically gets unique email addresses:
```
# Example addresses for your sandbox:
sandbox-12345@inbox.mailtrap.io
test-project-67890@inbox.mailtrap.io
# Test inbound email processing:
1. Send email to your sandbox address
2. Process received email via API/SDK or review in your Sandbox
3. Test reply handling and parsing
```
### Framework Examples
Pre-configured for popular frameworks:
* Laravel
* Ruby on Rails
* Django
* Spring Boot
* others
## Testing Capabilities
### Email Validation
* **HTML Validation**: Check for rendering issues
* **Attachment Testing**: Validate file handling
### Deliverability Testing
* **Spam Score**: SpamAssassin scoring
* **Blacklist Check**: IP reputation verification
* **Header Analysis**: Technical validation
## Best Practices
### Environment Separation
* Use different sandboxes for dev, staging, QA
* Name sandboxes clearly (e.g., "iOS App - Dev")
* Document sandbox purposes
### Testing Strategy
* Test both happy path and edge cases
* Check mobile responsiveness
* Test with real data (safely)
* Automate repetitive tests
## Getting Started
{% columns %}
{% column %}
**Setup Guides**
* [Application Integration](/email-sandbox/setup/sandbox-smtp-integration)
* [Sandbox API](/email-sandbox/setup/sandbox-api-integration)
* [Email Address Setup](/email-sandbox/setup/email-address-per-sandbox)
{% endcolumn %}
{% column %}
**Testing Tools**
* [Email Inspector](/email-sandbox/testing/email-template)
* [HTML Check](/email-sandbox/testing/email-html)
* [Deliverability Tests](/email-sandbox/testing/spam-blacklist-reports)
* [Bounce Emulator](/email-sandbox/testing/bounce-rate)
{% endcolumn %}
{% endcolumns %}
## Support & Resources
* [Features and Limits](/email-sandbox/help/features-and-limits)
* [Sandbox Glossary](/email-sandbox/help/glossary)
* [FAQs](/email-sandbox/help/faqs)
* [Troubleshooting](/email-sandbox/help/troubleshooting)
## Next Steps
1. [**Create your first sandbox**](/email-sandbox/setup) - Get started in minutes
2. [**Integrate with your app**](/email-sandbox/setup/sandbox-smtp-integration) - Configure SMTP settings
3. [**Test email templates**](/email-sandbox/testing/email-template) - Validate your emails
4. [**Share with team**](/email-sandbox/collaboration/sharing-sandboxes) - Collaborate on testing
# Setup & Configuration
Get Email Sandbox configured and integrated with your application
Get started with Email Sandbox quickly and easily. This section covers everything you need to integrate Email Sandbox into your development workflow.
## Integration Options
Application Integration
Step-by-step guide to integrate Email Sandbox with your application. Learn how to configure SMTP settings, use API endpoints, and route test emails to your sandbox.
## Quick Start
#### 1. Create Your First Sandbox
* Log in to your Mailtrap account
* Navigate to Email Sandbox
* Click "Create New Sandbox"
* Name your sandbox (e.g., "Development", "Staging", "QA")
#### 2. Get Your Credentials
* SMTP Host: `sandbox.smtp.mailtrap.io`
* SMTP Port: `2525` (or `25`, `465`, `587`)
* Username: Your sandbox username
* Password: Your sandbox password
#### 3. Configure Your Application
```javascript
// Example Node.js configuration
const nodemailer = require('nodemailer');
const transporter = nodemailer.createTransport({
host: 'sandbox.smtp.mailtrap.io',
port: 2525,
auth: {
user: 'your_username',
pass: 'your_password'
}
});
```
#### 4. Send Test Email
```javascript
await transporter.sendMail({
from: 'test@example.com',
to: 'user@example.com',
subject: 'Test Email',
text: 'This is a test email'
});
```
## Integration Methods
#### SMTP Integration
* Universal compatibility with any SMTP client
* No code changes required
* Perfect for legacy applications
* Supports all major frameworks and languages
#### API Integration
* Full programmatic control
* Retrieve and analyze emails via API
* Automate testing workflows
* Perfect for CI/CD pipelines
# Sandbox SMTP Integration
Learn how to integrate sandbox with your application using SMTP credentials or code samples
## Copy SMTP credentials
{% stepper %}
{% step %}
Go to **Email Testing** → **Sandboxes**.
{% endstep %}
{% step %}
Open the sandbox (named **My Sandbox**) created by default.
{% endstep %}
{% step %}
Under the **Integration** tab, select **SMTP** and copy the credentials such as Host, Port, Username, and Password.
{% endstep %}
{% step %}
Paste them into your email-sending script, service, or MTA (any service that supports SMTP integration), and run it. The email will arrive in your sandbox in a few seconds.
{% endstep %}
{% endstepper %}
## Select your integration
Instead of copy-pasting the SMTP credentials, you can use the code samples already containing your credentials.
{% stepper %}
{% step %}
In the **Integration** tab of your sandbox, scroll down to **Code Samples** and select the programming language or framework you're working with.
{% endstep %}
{% step %}
Copy the configuration and paste it into your email-sending script. Then, run it. The email will arrive in the sandbox in a few seconds.
{% endstep %}
{% endstepper %}
{% hint style="success" %}
*Learn how exactly Mailtrap can help you streamline email testing processes from our* [*case study with The Software House*](https://mailtrap.io/case-studies/the-software-house/)*.*
{% endhint %}
# Sandbox API Integration
Learn how to use the Sandbox API to automate testing and manage email sandboxes programmatically.
### How the API works
The testing API uses REST protocol and can return calls as JSON objects. And it's compatible with the majority of programming languages.
Mailtrap supports the following HTTPs requests:
* **POST** to create a resource
* **PATCH** to update a resource
* **GET** to get a resource or list of resources
* **DELETE** to delete a resource
### What you can do with the Sandbox API
Via the API, you can run the following commands:
* **Sandbox** — Create a new sandbox, reset the sandbox credentials and its email address; receive messages, clean one or all messages in the sandbox, mark all messages as read; manage users.
* **Project** — Create a new project, update, and delete it; manage its users.
* **Email forwarding** — Manage forwarding messages to real email addresses (available starting from the Individual plan).
* **Email content** — Inspect the email body by getting raw HTML (you can also download it), text, and detailed info about the HTML part, including a list of possible errors; receive message attachments.
* **Bcc and message headers** — Receive message headers (Bcc is also included in this section, notwithstanding that it is not a regular message header). Bcc is available starting from the Team plan.
* **Deliverability** — Get a Spam report and domain blacklisting details.
This way, you can test and verify if:
* Email sending script works.
* Email recipients are correct + Bcc testing (on the advanced plans).
* HTML template doesn't cause errors.
* Mail merge/dynamic content is replaced properly.
* Appropriate files are attached.
* Important links, such as reset password and account confirmation, work.
* Your message doesn't trigger a spam filter and your domain is not blacklisted, etc.
### How to get started with Sandbox API
First, you need to get a token. You can find it under **Settings** > **`API Tokens`**.
To learn more about managing your tokens, please [check this guide](/email-api-smtp/setup/api-tokens). Then, there are a couple ways to send authenticated HTTP requests:
* Send a HTTP header `Api-Token: {api_token}` , where `{api_token}` is your API token.
* Send a HTTP header `Authorization: Bearer #{token}` , where `{api_token}` is your API token (more info: Token Access Authentication).
Go to the [API documentation](https://docs.mailtrap.io/developers/email-sandbox/send-test-emails), check samples, and experiment in the console.
# API Tokens
Learn how to create, manage, and use API tokens for Email Sandbox.
The guidelines assume that you've set up Email Sandbox and use the corresponding [API v2](https://docs.mailtrap.io/developers/email-sandbox/sandboxes-inboxes).
#### Add and manage tokens manually
{% stepper %}
{% step %}
Navigate to **Settings** in the menu on the left and select **API Tokens**.
{% endstep %}
{% step %}
To add a new token, click the **Add Token** button in the upper right corner.
{% endstep %}
{% step %}
**Type the token name** into the designated field.
It’s perfectly fine to have a custom name for the API token, as it’s only for your reference, regardless of the use case.
{% endstep %}
{% step %}
**Assign permissions** by checking the boxes in the corresponding access level columns. Note that you must have admin permissions on a particular domain to send emails with this token.
{% endstep %}
{% step %}
Click the **Save** button and preview the new token under the **API Tokens** main menu.
{% endstep %}
{% endstepper %}
#### Auto-created token per domain
When you create a domain, a token is automatically created and named based on the following formula: \[domain name] + \[token] + \[token ID].
For example, if you add the example.com domain, the token for that domain will be named example.com token 1234. By default, the automatically generated token gets Domain Admin Mailtrap for the given domain.
{% hint style="info" %}
You'll need to edit permissions for the automatically generated token to allow for authorization on other domains.
{% endhint %}
#### Where to find tokens?
**SMTP Integration**
The automatically assigned token per domain is under the **Integration** tab in **Sending Domains**. Choose the desired stream, click **Integrate**, and toggle the switch to **SMTP**. SMTP password is the same as the API Token.
#### Settings > API Tokens
Select **Settings** in the left menu, then **API Tokens**. You'll see all active tokens, their creator, and their access level.
Click the three-dot menu to the far right of the specific user token and select Edit permissions.
{% hint style="info" %}
**Important notes:**
* You can also give Account Admin access to the token and get access to all Projects, Sandboxes, and domains on that account.
* If you want to test how it works, you need to get authenticated using your API token. Mailtrap uses Bearer Authentication, so you must pass the token under the Authorization header of your email.
{% endhint %}
### Reset token
There are two ways to reset API tokens:
#### Resetting API tokens in the Sandboxes
To reset tokens, go to your Sandbox under the **Sandboxes** tab and click the **Reset Credentials** function next to your credentials.
Then, click **Reset Credentials** and confirm your choice with the **Yes,** **Reset** button.
#### Resetting API Tokens from the API Tokens menu
Go to API Tokens, click the three-dot menu icon next to the token you want to reset, and click Reset API Token.
Confirm your choice by clicking on the corresponding button.
{% hint style="success" %}
**Tip:** The three-dot menu icon next to the token also allows you to copy a token to your clipboard.
{% endhint %}
{% hint style="warning" %}
**Important notes:**
* After clicking the Reset credentials or Reset API Token buttons, the existing token becomes invalid after 12 hours. So, you have a 12-hour window to update all apps that use the old API token. Once the old token expires, some parts of your application will not work properly unless you've updated the token. All expired tokens get deleted from your account within 24 hours after expiration.
* After the API token is reset and expired, a new token is created. The token ID is added to the token name the same way it's done for automatically generated tokens, e.g., mailtrap.example token 4231.
{% endhint %}
### Edit permissions
As mentioned earlier, click the menu icon at the far right of a token and select Edit permissions.
Click on the corresponding boxes to add or remove token permissions. Then, confirm your selection with the Save button.
### Delete token
To delete a token, click the three-dot menu icon and choose the **Delete token** option.
Confirm the action by clicking the **Confirm** button.
{% hint style="warning" %}
**Important:** Keep in mind that a token is deleted immediately, and you can't delete the last token per domain.
{% endhint %}
# Email Address per Sandbox
Use a dedicated customizable email address for each sandbox to send test messages without SMTP integration.
This feature offers an email address for testing, which you can customize. It supports dynamic aliases and provides you with an unlimited number of virtual email addresses. As soon as it is linked to your [sandbox](https://mailtrap.io/sandboxes), you can manage, view, and share your test results via the Mailtrap UI.
Starting from the [Basic](https://mailtrap.io/pricing/) billing plan, each of your sandboxes includes a dedicated email address you can use to send messages. You will find it in the **Email Address** tab. You can use your current email setup without needing to integrate Mailtrap as a fake server and run safe experiments.
The email address is enabled for you by default. To disable, edit, and reset the email address for this sandbox, click on the three-dots (more) menu.
As you can see from the screenshot, the sandbox address consists of two parts:
* A **customizable alias**, which you can edit manually. You can use any combination of numbers and Latin symbols. For example, you can use your company name or the name of the current sandbox with an identifying number.
* Mailtrap's **technical hash**, which can't be changed. It consists of 6 symbols and acts as our internal sandbox identifier.
This way, you get an infinite number of combinations and can imitate sending emails to a large number of users (with unique email addresses).
The sandbox name changes are applied instantly.
{% hint style="info" %}
Note that Mailtrap verifies sandbox aliases so that if you try to send a message to a custom sandbox address that doesn't exist, you will receive a `554 5.5.1 Error: no sandbox for this email.`message.
{% endhint %}
Additionally, Mailtrap sandboxes support dynamic aliased addresses. For example, [mailtrap-load-test-12ab34+1@inbox.mailtrap.io](mailto:mailtrap-load-test+1-12qb34@mailtrap.io) and [mailtrap-load-test-12ab34](mailto:mailtrap-load-test+2-12qb34@mailtrap.io)[+2](mailto:mailtrap-load-test+2-12qb34@mailtrap.io)[@inbox.mailtrap.io](mailto:mailtrap-load-test+2-12qb34@mailtrap.io) will be equally accepted and delivered to the same sandbox.
As a result of testing, all your experiments will be perfectly sorted and delivered to the corresponding Mailtrap virtual sandboxes. You will be able to review all of the messages and verify their content. This is crucial when you use personalization (especially in a subject line) and dynamic elements or localization.
Another important point is that sending to sandboxes from your production server doesn't affect your domain's reputation for the main email providers like Gmail, Hotmail, Yahoo, etc.
# Testing Features
Comprehensive email testing tools for quality assurance
Email Sandbox provides a complete suite of testing tools to ensure your emails look perfect and function correctly across all email clients and scenarios.
## Testing Capabilities
Email Template Inspector
Analyze your email templates in detail. Check rendering, validate structure, and ensure compatibility across different email clients.
# Email Template Inspector
Check email content, validate HTML code, and verify text versions of your message.
### 1. View the email in the sandbox and check its content
Go to the **HTML tab**, which opens by default when you open a message. It demonstrates how the email is rendered in a web browser and allows you to:
* Check whether the template looks as expected: Markup is correct, images are displayed, and fonts are supported.
* Review the message content, click the links and buttons.
* Test the message for responsiveness: click the device icons in the tab to see how it looks on mobile, tablet, and desktop.
### 2. Check the HTML template code for validity
Email clients use different rendering standards. This is why your email can be displayed not as you designed it. You need to check that your message code won't cause rendering issues.
**HTML Check** scans through your email in search of problematic elements. For each it finds, it displays the list of email clients that lack support for it or support it only partially. It also estimates the support for your emails' code across popular email clients, making adjustments for their popularity.
Go to the **HTML Check** tab to see the report:
**HTML Check** collects the list of rules used in your email and compiles it with the supporting data we have for the most popular email clients. The final result is the Market Support, or the overall level of HTML/CSS support for your email.
Below you will see a list of rules that cause errors in the specified email clients. To the right of each element, you can see the numbers (\[1], \[2], etc.). Click on any of them, and the "show more" section will expand, explaining what the issue is and which client/version it applies to.
Clicking on the line number will take you to the **HTML Source** tab where you can view your email's entire HTML.
To learn more about the HTML Check feature, refer to the [HTML Check article](/email-sandbox/testing/email-html).
### 3. Make sure that the HTML and TEXT versions of your message match
It is important to include both the HTML and text versions in your message. This not only affects the spam score but also helps your recipients to understand your message if the HTML part hasn't rendered for some reason. Go to the **Text** tab to inspect the text version.
# HTML Check
Learn how HTML Check scans your email for problematic elements and provides market support scores.
**HTML Check** scans through your email in search of problematic elements. For each it finds, it displays the list of email clients that lack support for it or support it only partially. It also estimates the support for your emails' code across popular email clients, and provides you with percentage of the market share accordingly.
The report is available in the **HTML Check** tab:
The higher your market support score, the better for your email!
### Understanding the Market Support score
Each HTML email template consists of dozens, if not hundreds, of HTML/CSS rules. The support for them varies across email clients and even across versions of particular clients. It's not uncommon that, for example, Apple Mail supports a rule for iOS 11.0+ (but doesn't for an older version) and only has partial support for the macOS app.
**HTML Check** collects the list of rules used in your email and compiles it with the support data we have for the most popular email clients. The final result is the **Market Support**, or the overall level of HTML/CSS support for your email.
The support for a rule in a particular client can fall into one of three categories:
* **Full support** — The rule is fully supported across all versions of a client.
* **Partial support** — The rule is not fully supported in a given client, OR at least one of the versions of this client doesn't support it.
* **No support** — The email client offers no support for this rule.
When calculating the score, we take into consideration the market share of each email client. Some clients (e.g., Gmail or iPhone's default Mail app) are far more popular than others (for example, Yahoo! Mail). For that reason, the less popular clients may lack support for specific elements thus having a far more significant impact on the Market Support score.
### Filtering options
By default, the market support is calculated for all email clients listed to the right and all their versions in common use. You can freely check and uncheck particular filters, and the market score will adjust immediately.
The vertical list shows five common families of email clients, 'Other' representing less popular clients (e.g., Thunderbird, AOL, etc.). The horizontal list lets you narrow down the results for the particular type of client: mobile, web, or desktop.
For example, if you were to select only Apple Mail and Yahoo! Mail but unchecked 'Mobile', both clients' iOS and Android apps would be ignored. If there's no client for a particular category (e.g., Apple Mail doesn't have a web client), unchecking a category won't alter the results.
As usual, the weight on the Market Support result is proportional to the popularity of each client.
Filtering is particularly beneficial if you know that the vast majority of your users are, for example, on mobile or use only Outlook to view your emails. You can get a more focused market support result this way.
Note that at least one category (Web/Mobile/Desktop) and at least one email client need to be checked to generate any result.
### The algorithm behind HTML Check
You may also view the support for the entire family of popular email clients, such as Gmail (iOS, Android apps, desktop, mobile webmail, etc.). Simply hover over the respective name, and the green (fully supported), orange (partially supported), and red (not supported) numbers will appear.
To understand how these are calculated, let's look at an example. We want to view the results for Gmail only, which, across all three categories, has ten different versions of its email client (as an example). Our email has three HTML/CSS rules:
* **'height attribute'** — Not supported in clients \[2], \[4], and \[6], only partially supported in \[5]
* **'max-width'** — Not supported in clients \[2], \[3], and \[4], partially supported in \[5], and \[6]
* **'style tag**' — Not supported in \[2]
**HTML Check** algorithm calculates which clients:
* Don't support at least one of the styles used in a template -> \[2], \[3], \[4], \[6] -> 4/10 -> 40% -> these are marked as red (no support)
* Only partially support at least one of the styles (and have not been marked as 'no support') -> \[5] -> 1/10 -> 10% -> these are marked as orange (partial support)
* All other clients - \[1], \[7], \[8], \[9], \[10] - 5/10 -> 50% - are marked as green (full support)
Note that client \[5] partially supports one rule but doesn't support another. Because we look at the "worst" support level across all rules, this client was tagged as 'no support'.
The support for Gmail in our example is:
* **Full support** — 50%
* **Partial support** — 10%
* **No support** — 40%
We collect the data on support for particular rules from [Caniemail.com](https://www.caniemail.com/).
### Analyzing the HTML elements
Almost always, at least a few errors will appear. For instance:
Each will display:
* Element name (e.g. 'margin-left')
* Clients that don't support this element (red) or offer only partial support (orange)
* Hyperlinks to individual lines where the element was found (more on these below)
* "show more" label shedding more light on the problematic element.
To the right of each element, you can see the numbers (\[1], \[2], etc.). Click on any of them, and the "show more" section will expand, explaining what the issue is and which client/version it applies to.
Clicking on the line number will take you to the **HTML Source** tab where you can view your email's entire HTML.
This also demonstrates the alternative way of using HTML Check. You can use the **HTML Source** tab from the start and inspect the code, line by line. Each problematic line will be highlighted with an orange or a red circle, with an exclamation mark inside of it.
For more details on the issue, head to the **Check HTML** tab and look for this item down the list.
# Email Headers and Bcc
Learn how to verify email headers including Subject, From, To, and Bcc fields.
* **Subject line.** View how it looks for the recipient and make sure that they are rendered as expected, especially if you used emojis.
* **FROM** (sender). Make sure the sender's name and email address are correct.
* **TO** (recipients) - To and Cc. When you send multiple emails and/or use "merge" functions, you should carefully check whether recipients are generated correctly.
* **Bcc** - Blind copy, which is not a header, making it especially difficult to test. With Sandbox, you can check whether proper addresses are added (available starting from the [Team plan](https://mailtrap.io/pricing/)).
You can perform all these checks in your Mailtrap sandbox. Open the message, and check the Subject, From, and To headers first. Then click **Show Headers** or go to the **Tech Info** tab directly. There, you will find the following information:
* Message-Id
* Message date and time
* Reply-To
* Bcc'ed email address(-es) (if there is no Bcc, then you will see the "There is no Bcc information in this email message" message)
**SMTP Info** section demonstrates the message details according to the SMTP protocol. Mailtrap analyzes SMTP commands of the message, compares message headers and recipients, and then prints out the difference to the Bcc field. To learn more about Bcc and how it works, read:
{% embed url="" %}
Please note that the sandbox shows Bcc 'as is'. It displays an email message for each DATA SMTP command. If an SMTP client fetches Bcc from the RCPT TO command, it will be displayed as one email message in the Mailtrap sandbox. However, some clients send email messages to Bcc'ed addresses as separate RCPT TO **and** DATA commands that result in a separate/second email message in the sandbox.
If you need detailed information about the message metadata, view the **Raw** tab.
# Spam & Blacklist reports
Learn how to check spam score and blacklisting to ensure email deliverability
### Spam Report
Go to the **Spam Analysis** tab to view the Spam Report. It contains the general score and a detailed table with spam test points and their descriptions.
[Apache SpamAssassin](https://mailtrap.io/blog/spamassassin-score/), the most popular email filter, runs numerous tests on email headers and body text and assigns a score to each of them.
A score below 5 points is considered good. If your email gets more than 5 points, it will most likely be treated as spam by various email clients. In this case, check the rules that gained the highest score and fix your email template accordingly.
### Blacklists Report
You will find the Blacklists Report in the **Spam** **Analysis** tab as well.
It checks whether your IP or domain has been listed on any of the commonly used blacklists. It shows resources that have been queried and your current status. If your domain or IP is blacklisted, click the resource name; it's hyperlinked to the blacklist website -- check their rules for delisting and follow their instructions.
# Bounce Emulator
Learn how to test your SMTP client's behavior when the server responds with an error
## Constructing the address
The recipient's username should start with bounce+ and contain the response in URL-encoded form: `bounce+550+no+such+user+here@inbox.mailtrap.io` .
To create it, use [https://www.urlencoder.org](https://www.urlencoder.org/) or any other URL encoding solution.
Tip: You cannot use capital letters because email addresses are converted to lowercase by any responsible SMTP client. But you can use URL encoding to express capital letters: `bounce+550+%4Eo+such+user+here@inbox.mailtrap.io` .
## Using Bounce Emulator with an email client
Just use the inbox.mailtrap.io host with any email client or application and send an email to `bounce+451+server+unavailable@inbox.mailtrap.io` .
## Using Bounce Emulator with Sandbox
If your application is connected to Email Sandbox SMTP, send an email from the application to `bounce+454+authentication+required@anydomain.com` , and your application will receive a bounce response from the Sandbox SMTP server.
*Note: This feature does not work with API, as bounce codes are specific to SMTP.*
# Load Testing
Test your email application at scale using the Sandbox Enterprise plan with up to 150 emails per 10 seconds across 300 sandboxes
Email app load testing is one of the most popular cases of using Sandbox Enterprise plan. This plan allows you to send up to 150 emails every 10 seconds to as many as 300 sandboxes.
Every sandbox has a unique email address that can be customized (the "email per sandbox" feature). It consists of two parts:
* A **customizable alias, which you can edit manually**. You can use any combination of numbers and Latin symbols. For example, your company name or the name of the current sandbox with an identifying number. Sandboxes support dynamic aliased addresses. For example, and will both be accepted and delivered to the same sandbox.
* **Technical hash, which cannot be changed**. It consists of 6 symbols and acts as our internal sandbox identifier. Using this feature, you can use an infinite number of address combinations, and can imitate sending emails to a large number of users (with unique email addresses). The sandbox name changes are applied instantly, meaning that you don't have to pause your email testing and wait until a new alias becomes valid.
{% hint style="success" %}
*Also, note that if you try to send a message to a custom sandbox address that doesn't exist, you will get the "554 5.5.1 Error: no sandbox for this email" message.*
{% endhint %}
By default, the sandbox email address is disabled for security reasons. To activate it, go to the **Email Address** tab and open the three dots menu next to the **Copy** button. Click **Enable**. In this menu, you will also find the **Edit** and **Reset Address** buttons.
### Load testing use case
Large-scale systems employ numerous servers to distribute loading. Specifying **a separate testing email address for each server** allows you to follow and inspect failures or unexpected behavior. This way you can test and load all your resources at once and then filter the results accordingly.
Here is how it looks in practice:
* email **server A** sends messages to the [servera-12ab32@inbox.mailtrap.io](mailto:servera-12ab32@mailtrap.io) sandbox
* email **server B** sends messages to the [serverb-12ab44@inbox.mailtrap.io](mailto:servera-12ab32@mailtrap.io) sandbox
* email **server C** sends messages to the [serverc-12ab55@inbox.mailtrap.io](mailto:servera-12ab32@mailtrap.io) sandbox
* …
* email **server L** sends messages to the [serverl-12ab99@inbox.mailtrap.io](mailto:servera-12ab32@mailtrap.io) sandbox, etc.
Afterward, you can enter a corresponding project in your account and see a list of these sandboxes with the number of messages in each sandbox.
This way, you can check and compare your sending capabilities and instantly identify which of your servers is experiencing problems.
*You can disable the email addresses any time you need it. We recommend disabling them as soon as you finish testing, for improved safety.*
# Sandbox Management
Manage and organize emails in your sandbox effectively
Efficiently manage, search, and organize emails within your Email Sandbox. These tools help you maintain a clean testing environment and quickly find the emails you need.
## Management Features
Searching Messages
Powerful search capabilities to find specific emails quickly. Filter by sender, subject, date, content, and custom criteria.
# Searching Messages
Search for emails in your sandbox by subject, recipient address, or recipient name
Email search works as a case-insensitive pattern matching. You can search for emails by:
* All words from email subject
* TO email address
* TO name
# Automatic Forwarding
Forward emails from the sandbox to any inbox automatically for testing in different clients and notifying colleagues.
You can forward emails from the sandbox to any inbox.
* View emails in different email clients, or even other apps.
* Notify your colleagues or clients about the testing progress.
* Use it as a proxy between your application and your email client; never miss a thing from your QA environment.
Email forwarding is available starting from the [Basic plan](https://mailtrap.io/pricing/). You can set automatic forwarding to confirmed email addresses or domains.
### How to set automatic forwarding to an email address
To set auto-forwarding to email addresses, go to the **Auto Forward** tab in your sandbox and enter the forwarding email address(es).
The email confirmation will be sent to this email address(es) for verification. Once the address is confirmed by its owner, you can **add this address to the "To" or "Cc" headers** of your email messages, and they will be automatically forwarded.
In the **Auto Forward** tab, you will also find the list of email addresses for forwarding and their statuses:
* *Active* means that its owner has confirmed that they agree to receive emails.
* *Pending* means that the owner hasn't confirmed that they agree to receive emails.
To resend the confirmation or remove a forwarding rule, use the action buttons in the three-dots menu next to the selected email address.
### How to set automatic forwarding to a domain
To set auto-forwarding to a domain, you need to add a TXT record to verify your site. Here are the steps:
1. Enter your domain in the Domain field and click the **Add domain** button.
2. In the displayed table you will find the record and its value.
3. Go to your domain settings page, select **Manage DNS**, and **choose TXT** from the list of options (for details, consult your domain provider documentation).
4. Copy the authentication key from the **Value** column and paste it to your TXT record.
5. Once completed, get back and click the **Verify** button for this domain. The status should change to **Active**. The system will forward messages to any email address which matches "\*@domain" in the "To" or "Cc" email headers. To remove a forward rule, use the action buttons in the three-dots menu next to the domain.
### `From:` header in forwarded emails
All forwarded email messages use forward.mailtrap.info in the `From:` header, e.g., when you forward an email from sandbox you'll see something like this in your sandbox:
> From: Mailtrap Forward <>
It helps to use forwarding for users with a strict DMARC policy on their domains. Since DMARC doesn't allow sending emails from your domain without permissions, sandbox rewrites the `From:` header. But because the original sender is valuable information, especially in automated testing, we still preserve it in *x-mailtrap-original-from* header of the forwarded emails.
# Manual Forwarding
Forward individual emails from sandbox to any inbox for testing in different clients or notifying colleagues.
You can forward emails from sandbox to any inbox.
* View emails in different email clients, or even other apps.
* Notify your colleagues or clients about the testing progress.
* Use it as a proxy between your application and your email client and never miss a thing from your QA environment.
Email forwarding is available starting from the [Basic plan](https://mailtrap.io/pricing/).
### Manual forwarding setup
To forward emails manually, go to the **Manual Forward** tab in your sandbox and add the email address for forwarding.
The email confirmation will be sent to this email address for verification. Once the address is confirmed by its owner, you can forward emails to it.
Return to the sandbox, open the message you want to forward and click the forwarding icon in the top-right of the screen.
In the **Manual Forward** tab, you will also find the list of email addresses for forwarding and their statuses:
* *active* means that its owner has confirmed that they agree to receive emails.
* *pending* means that the owner hasn't confirmed that they agree to receive emails.
Click the three-dot menu icon next to the email address to resend confirmation, or to remove this email address.
### `From:` header in forwarded emails
All forwarded email messages use forward.mailtrap.info in the `From:` header, e.g., when you forward an email, you'll see something like this in your sandbox:
> From: Mailtrap Forward <
It helps to use forwarding for users with a strict DMARC policy on their domains. Since DMARC doesn't allow sending emails from your domain without permissions, sandbox rewrites the `From:` header.
But because the original sender is valuable information, especially in automated testing, we still preserve it in *x-mailtrap-original-from* header of the forwarded emails.
# Collaboration
Team features for collaborative email testing
Work effectively with your team using Email Sandbox's collaboration features. Share sandboxes, projects, and test results to streamline your email testing workflow.
## Collaboration Features
Sharing Sandboxes
Share individual sandboxes with team members. Control access levels and permissions for different users.
# Sharing Sandboxes
Share individual sandboxes with team members for collaborative email testing.
### How to organize your sandbox data
The best practice is to create separate sandboxes for different environments: development, test, or staging. Each sandbox is defined by SMTP credentials (your username and password). If necessary, you can reset them at any time.
### How to share your sandboxes with others
For effortless collaboration with your colleagues or customers, you can share data of your choice with them: separate sandboxes or whole projects. To learn how to share projects, read our [dedicated article](/email-sandbox/collaboration/sharing-projects).
There are two ways to share your sandbox:
1. Invite users directly to sandbox
2. Share sandbox via User Management
To share a sandbox, you need to be one of the following:
1. Sandbox, project, or account admin
2. Account owner
Also, sharing options are available starting from the Team plan.
You can invite anyone, even if they don't have a Mailtrap account yet.
1. Click the gear icon on the far right of the sandbox you'd like to share.
2. Go to the Access Rights tab.
3. Enter the email address of your team member.
4. Choose the invitee's permission level (e.g. Sandbox Viewer or Admin)
Once you click the **Add** button, the email invitation will be sent to the specified email address. The recipient should accept the email invitation.
But if a person is already in your account, the sandbox will immediately become visible to them.
Alternatively, you can use the **User Management** feature. Select it and click the **Add Member** button. Type the user's email address and tick the box under the permission level for a sandbox you'd like to share.
And yes, you can share multiple sandboxes at the same time. To finalize sharing, hit **Send Invite** and you're good to go.
### Sandboxes shared with you by others
Clicking on Sandboxes in the menu bar on the left reveals only the sandboxes associated with the account you're currently using.
If you want to access a different account and sandboxes that were shared with you, click on the account switcher in the upper right corner of the window, then select an account from the drop-down menu.
Note that you can be invited to any sandbox or project as a user, regardless of the subscription plan you currently use.
# Sharing Projects
Organize and share projects to collaborate with team members on email testing.
### How to organize projects
All incoming emails in Sandbox are organized into sandboxes, the folders that are grouped into projects. Usually, projects are used to separate companies, environments, or (surprisingly) projects.
### How to share your projects
Sharing options are available starting from the Team plan.
You can share any of the projects in your account. Users that receive access to your project also receive access to all of its sandboxes and can manage or view their content. To learn how to share a specific sandbox, check out the [Sharing sandboxes](/email-sandbox/collaboration/sharing-sandboxes) article.
To share a project including all of its sandboxes, you have three options:
* Use the three vertical dots next to My Project under Sandboxes
* Share a link from Project Team Members
* Utilize the User Management feature
It doesn't matter which option you choose. New users will be visible in the Sandbox Team Members, Project Team Members tab and in the User Management list. But to share a project, you need to be one of the following:
* Project or account admin
* Account owner
### Important notes
The User Management section is visible to Account Admins and the Account owner.
In the "Project Team Members" window, you see all people who have access to this project, whether they were invited directly to the project or they have access to it. For example, the users could be account admins and thus have access to all projects.
If you select the "Team Members" tab of an sandbox, you see all people who have access to this sandbox. That goes for those invited directly to the sandbox and users who have access to the sandbox. Again, they could be project admins and thus have access to all project sandboxes.
# Help & Support
Get help with Email Sandbox issues and find answers to common questions
Find answers to common questions and troubleshoot issues with Email Sandbox. Our comprehensive help resources are designed to get you back on track quickly.
## Resources
Frequently Asked Questions
Browse our comprehensive FAQ section for quick answers to common questions about Email Sandbox setup, integration, testing features, and best practices.
## Common issues & solutions
### Connection issues
#### Can't connect to Sandbox SMTP
1. **Verify credentials**: Check username and password
2. **Confirm port**: Use 2525, 25, 587, or 465
3. **Check firewall**: Ensure ports aren't blocked
4. **Test connection**: Use telnet or nc command
```bash
telnet sandbox.smtp.mailtrap.io 2525
```
#### Emails not appearing in Sandbox
1. **Check sandbox limits**: Free plan has 500 emails/month
2. **Verify credentials**: Ensure using correct sandbox
3. **Check spam folder**: Some emails may be filtered
4. **Review email size**: Maximum 5MB including attachments
5. **API rate limits**: Check if hitting rate limits
### Configuration problems
#### Framework integration not working
* **Laravel**: Clear config cache with `php artisan config:clear`
* **Rails**: Restart server after config changes
* **Django**: Check `EMAIL_BACKEND` setting
* **Node.js**: Verify environment variables loaded
#### Authentication failures
```
535 5.7.0 Invalid login or password
```
Solution:
* Copy credentials directly from Mailtrap dashboard
* Don't use email address as username
* Regenerate credentials if needed
### Testing issues
#### HTML not rendering correctly
* Use HTML Check tool to validate code
* Test with different email clients
* Check for missing closing tags
* Validate CSS compatibility
#### Attachments not working
* Verify file size < 5MB total
* Check MIME type configuration
* Ensure proper encoding (base64)
* Test with different file types
## Getting help
### Self-service resources
1. **Search documentation**: Use the search bar above
2. **Check FAQs**: [Frequently Asked Questions](/email-sandbox/help/faqs)
3. **Review troubleshooting**: [Common issues](/email-sandbox/help/troubleshooting)
4. **API reference**: [API Documentation](https://docs.mailtrap.io/developers)
### :comments-question-check:Contact Support
If you can’t find the answer you need in our documentation or something doesn’t work as expected, feel free to contact our support team and speak with an agent, we’re here to help.
If the information provided (including AI responses) doesn’t fully resolve your question or your case requires a closer look, our team can review your setup and assist further.
You can get in touch with the Mailtrap Support team using one of the following ways:
* **From your Mailtrap account**
1. Log in to your account [here](https://mailtrap.io/signin).
2. Go to the :circle-question:[**Help Center**](https://mailtrap.io/help-center) > :message-dots: Get Help
3. Click **Start conversation.**
* **Email us at** 📧
Whether you need technical assistance, help troubleshooting UI or account-specific issues, or simply want to talk to customer support, our team will be happy to assist you.
### Before contacting support
Please have the following information ready:
* Account email address
* Sandbox ID or name
* Error messages (exact wording)
* Steps to reproduce the issue
* Framework/language you're using
* Code snippets (if applicable)
## Quick solutions
### Email capture issues
| Problem | Solution |
| ------------------ | ------------------------------------ |
| No emails received | Check credentials and connection |
| Emails delayed | Normal processing time is < 1 second |
| Missing emails | Check inbox limits and filters |
| Partial content | Verify email size < 5MB |
### API issues
| Error Code | Meaning | Solution |
| ---------- | ------------ | ------------------------ |
| 401 | Unauthorized | Check API token |
| 403 | Forbidden | Verify permissions |
| 404 | Not found | Check inbox ID |
| 429 | Rate limited | Implement backoff |
| 500 | Server error | Retry or contact support |
### SMTP errors
| Error | Cause | Fix |
| --------------------- | ------------------- | --------------------------------- |
| Connection refused | Wrong port/host | Use sandbox.smtp.mailtrap.io:2525 |
| Authentication failed | Invalid credentials | Copy from dashboard |
| Message rejected | Size limit exceeded | Keep under 5MB |
| Timeout | Network issue | Check firewall/proxy |
## Debugging tools
### Connection testing
```bash
# Test SMTP connection
openssl s_client -connect sandbox.smtp.mailtrap.io:2525 -starttls smtp
# Test with curl
curl -v telnet://sandbox.smtp.mailtrap.io:2525
```
### Email testing
```python
# Python test script
import smtplib
from email.mime.text import MIMEText
def test_sandbox():
msg = MIMEText('Test email body')
msg['Subject'] = 'Test Subject'
msg['From'] = 'test@example.com'
msg['To'] = 'recipient@example.com'
with smtplib.SMTP('sandbox.smtp.mailtrap.io', 2525) as server:
server.login('YOUR_USERNAME', 'YOUR_PASSWORD')
server.send_message(msg)
print("Email sent successfully!")
test_sandbox()
```
## Best practices
### Optimal configuration
* Use port 2525 for best compatibility
* Enable STARTTLS for security
* Set reasonable timeout values
* Implement retry logic
* Use connection pooling
### Testing strategy
* Create separate sandboxes per environment
* Clear sandboxes regularly
* Use descriptive email subjects
* Tag emails with test IDs
* Automate common tests
### Team collaboration
* Share sandboxes appropriately
* Document sandbox purposes
* Use consistent naming
* Regular permission audits
* Communicate test schedules
## Community resources
### Tutorials & guides
* [Getting started video](https://www.youtube.com/watch?v=example)
* [Blog tutorials](https://mailtrap.io/blog/tag/sandbox/)
* [Integration examples](https://github.com/railsware/mailtrap-examples)
### Developer resources
* [API client libraries](https://github.com/railsware)
* [Postman collection](https://www.postman.com/mailtrap)
* [Code snippets](https://mailtrap.io/blog/test-emails-in-dev/)
## Feedback & suggestions
*We welcome technical feedback and contributions that help us improve Mailtrap’s functionality and documentation. Please use the appropriate channel depending on the type of request.*
#### :bug:Bug Reports
**If you encounter a product issue or unexpected behavior, please** [#contact-support](#contact-support "mention")**.**
To help us investigate efficiently, include:
* A detailed description of the issue
* Exact reproduction steps
* Relevant stream, domain, sandbox, or account details
* Timestamps (including timezone)
* Screenshots or logs if available
#### :file-circle-plus:Feature Requests
For product improvements or new feature proposals, use our [Public Roadmap](https://mailtrap.featurebase.app/en) portal.
There you can:
* **Submit a new feature request**
* **Upvote existing requests**
* **Subscribe to updates for specific requests**
:soon:**The following enhancements are currently planned:**
* GraphQL API
* Advanced search filters
* Email templates library
* Browser extension
* Mobile app
#### :file-doc:Documentation Improvements
If you identify unclear, incomplete, or outdated documentation:
1. Use the **feedback widget** located on the right-hand side of the page to rate the article:\
2. **Provide specific feedback** describing what should be corrected, clarified, or expanded\
This helps us continuously refine our docs.
#### :square-code:GitHub & Technical Collaboration
For open-source projects, SDKs, or public repositories, join us on [GitHub](https://github.com/mailtrap).
# FAQs
Frequently asked questions about Email Sandbox
This page covers frequently asked questions about Email Sandbox. For technical issues and error troubleshooting, see the [Troubleshooting section](/email-sandbox/help/troubleshooting).
#### Integration & setup
How do I integrate Email Sandbox with my application?
The integration is very simple and you can complete it in just a couple of minutes using SMTP credentials or code samples for over 20 frameworks.
**See our step-by-step guide**: [How to integrate Email Sandbox with your application](/email-sandbox/setup/sandbox-smtp-integration).
Do you need to view Sandbox emails only through its interface?
No, you don't have to stick to Email Sandbox web interface. You can forward every single email to your or a teammate's mailbox.
You can even enable automatic forwarding, and Email Sandbox will act as a proxy between your application and your email client. In this case, you won't miss important messages from the QA environment, such as exception notifications.
**Learn more**:
* [Automatic Email Forwarding](/email-sandbox/management/automatic-email-forwarding)
* [Manual Email Forwarding](/email-sandbox/management/manual-email-forwarding)
#### Technical specifications
How does Email Sandbox render emails?
Sandbox renders emails in the same way browsers do, which means no additional stylesheet or CSS presets are applied by default.
Can Email Sandbox show what emails look like in various email clients?
Email Sandbox is compatible with web email clients and renders HTML as-is, without external CSS styles.
Sandbox provides [HTML checks](/email-sandbox/testing/email-html) and demonstrates potential errors that different email clients may experience when rendering an HTML email. You can also get a preview of test emails for different devices (e.g., mobile, tablet, desktop).
You can also forward emails to Outlook, Thunderbird, etc., and use these desktop clients to view them.
What does Sandbox do with the <style> tag?
Sandbox doesn't remove the `