api-docs

title	Mailtrap API Reference
description	Complete API documentation for the Mailtrap email platform
icon	code

Overview

Welcome to the Mailtrap API documentation. Our APIs provide comprehensive access to email sending, testing, contact management, and account administration features.

The Mailtrap API follows REST principles. Authenticated users can interact with any endpoint using standard HTTP methods. All requests must be sent over HTTPS, as TLS encryption is enforced.

LLM & AI Agent Integration

For AI assistants and coding agents: a structured, LLM-optimized version of this documentation is available at https://docs.mailtrap.io/llms.txt. It includes API routing instructions, endpoint summaries, and integration guidance formatted for accurate code generation.

Documentation structure

The API documentation is organized into the following sections:

{% columns %} {% column width="33.33333333333333%" %}

Email Sending

Endpoints to send transactional and bulk (promotional) emails, as well as manage sending domains, suppressions, and delivery statistics. {% endcolumn %}

{% column width="33.33333333333333%" %}

Templates

Endpoints to manage email templates used for email sending, email sandbox, and campaigns. {% endcolumn %}

{% column %}

Promotional

Endpoints to manage contacts. Contacts can be used to run campaigns and set up automations. {% endcolumn %} {% endcolumns %}

{% columns %} {% column %}

Email Sandbox

Endpoints for testing and inspecting emails in a safe environment.
Note: Email Sending and Email Sandbox use different base URLs. {% endcolumn %}

{% column %}

Account Management

Endpoints for programmatic management of account details and access permissions. {% endcolumn %}

{% column %}

{% endcolumn %} {% endcolumns %}

Quick Start

{% stepper %} {% step %}

Get API Credentials

Navigate to API Tokens.
Generate a new API token with the required permissions.

{% hint style="info" %} You must have a verified domain to send emails.

Keep your API token secure and never expose it in client-side code. {% endhint %} {% endstep %}

{% step %}

Install an SDK

Choose an SDK for your programming language, or use the API directly with cURL.

Supported SDKs:

{% tabs %} {% tab title="Node.js" %}

npm install mailtrap

{% endtab %}

{% tab title="Python" %}

pip install mailtrap

{% endtab %}

{% tab title="PHP" %}

composer require railsware/mailtrap-php

{% endtab %}

{% tab title="Ruby" %}

gem install mailtrap

{% endtab %}

{% tab title="Java" %}

<dependency>
    <groupId>io.mailtrap</groupId>
    <artifactId>mailtrap-java</artifactId>
    <version>2.0.0</version>
</dependency>

{% endtab %}

{% tab title=".NET" %} The .NET SDK is available via GitHub Packages. First, add the GitHub source:

dotnet nuget add source https://nuget.pkg.github.com/mailtrap/index.json \
  --name github-mailtrap \
  --username GITHUB_USERNAME \
  --password GITHUB_PAT

Then install the package:

dotnet add package Mailtrap -s github-mailtrap

{% endtab %} {% endtabs %} {% endstep %}

{% step %}

Send your first email

Below are minimal examples for sending an email:

{% tabs %} {% tab title="Node.js" %}

import { MailtrapClient } from "mailtrap";

const mailtrap = new MailtrapClient({
  token: process.env.MAILTRAP_API_KEY, // You can create your API key here https://mailtrap.io/api-tokens
});

mailtrap
  .send({
    from: { name: "Mailtrap Test", email: "[email protected]" },
    to: [{ email: "[email protected]" }],
    subject: "Hello from Mailtrap Node.js",
    text: "Plain text body",
  })
  .then(console.log)
  .catch(console.error);

{% endtab %}

{% tab title="Python" %}

import mailtrap as mt

API_TOKEN = "<YOUR_API_TOKEN>"  # your API key here https://mailtrap.io/api-tokens

client = mt.MailtrapClient(token=API_TOKEN)

# Create mail object
mail = mt.Mail(
    sender=mt.Address(email="[email protected]", name="John Smith"),
    to=[mt.Address(email="[email protected]")],
    subject="You are awesome!",
    text="Congrats for sending test email with Mailtrap!",
)

client.send(mail)

{% endtab %}

{% tab title="PHP" %}

<?php

use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;
use Mailtrap\Mime\MailtrapEmail;
use Symfony\Component\Mime\Address;

require __DIR__ . '/vendor/autoload.php';

$mailtrap = MailtrapClient::initSendingEmails(
    apiKey: getenv('MAILTRAP_API_KEY') // your API key here https://mailtrap.io/api-tokens
);

$email = (new MailtrapEmail())
    ->from(new Address('[email protected]'))
    ->to(new Address('[email protected]'))
    ->subject('Hello from Mailtrap PHP')
    ->text('Plain text body');

$response = $mailtrap->send($email);

// Access response body as array (helper optional)
var_dump(ResponseHelper::toArray($response));

{% endtab %}

{% tab title="Ruby" %}

require 'mailtrap'

# Create mail object
mail = Mailtrap::Mail.from_content(
  from: { email: '[email protected]', name: 'Mailtrap Test' },
  to: [
    { email: '[email protected]' }
  ],
  reply_to: { email: '[email protected]', name: 'Mailtrap Reply-To' },
  subject: 'You are awesome!',
  text: 'Congrats for sending test email with Mailtrap!'
)

# Create client and send
client = Mailtrap::Client.new(api_key: 'your-api-key')
client.send(mail)

# You can also pass the request parameters directly
client.send(
  from: { email: '[email protected]', name: 'Mailtrap Test' },
  to: [
    { email: '[email protected]' }
  ],
  subject: 'You are awesome!',
  text: 'Congrats for sending test email with Mailtrap!'
)

{% endtab %}

{% tab title="Java" %}

import io.mailtrap.client.MailtrapClient;
import io.mailtrap.config.MailtrapConfig;
import io.mailtrap.factory.MailtrapClientFactory;
import io.mailtrap.model.request.emails.Address;
import io.mailtrap.model.request.emails.MailtrapMail;

import java.util.List;

public class MailtrapJavaSDKTest {

    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
    private static final String SENDER_EMAIL = "[email protected]";
    private static final String RECIPIENT_EMAIL = "[email protected]";

    public static void main(String[] args) {
        final MailtrapConfig config = new MailtrapConfig.Builder()
            .token(TOKEN)
            .build();

        final MailtrapClient client = MailtrapClientFactory.createMailtrapClient(config);

        final MailtrapMail mail = MailtrapMail.builder()
            .from(new Address(SENDER_EMAIL))
            .to(List.of(new Address(RECIPIENT_EMAIL)))
            .subject("Hello from Mailtrap Sending!")
            .text("Welcome to Mailtrap Sending!")
            .build();

        // Send an email using Mailtrap Sending API
        try {
            System.out.println(client.send(mail));
        } catch (Exception e) {
            System.out.println("Caught exception : " + e);
        }
    }
}

{% endtab %}

{% tab title=".NET" %}

using Mailtrap;
using Mailtrap.Emails.Models;
using Mailtrap.Emails.Requests;

using var mailtrapClientFactory = new MailtrapClientFactory("YOUR_API_TOKEN");
var client = mailtrapClientFactory.CreateClient();

var mail = new SendEmailRequest
{
      From = new EmailAddress("[email protected]"),
      To = new[] { new EmailAddress("[email protected]") },
      Subject = "Hello from Mailtrap",
      TextBody = "Welcome to Mailtrap Email API!"
};

await client.Email().Send(mail);

{% endtab %} {% endtabs %} {% endstep %} {% endstepper %}

Email Sending Options

Transactional emails

Best suited for real-time, one-to-one emails triggered by user actions, such as:

Order confirmations
Password resets
Account notifications
System alerts
Welcome emails

Endpoint:

https://send.api.mailtrap.io/api/send

Bulk stream

Optimized for high-volume marketing and promotional campaigns, including:

Newsletters
Promotional campaigns
Product announcements
Marketing emails

Endpoint:

https://bulk.api.mailtrap.io/api/send

Batch sending

Send up to 500 emails in a single API call. Useful for:

Personalized notifications
Event invitations
Account updates
Targeted campaigns

Endpoints:

Transactional:
https://send.api.mailtrap.io/api/batch
Bulk:
https://bulk.api.mailtrap.io/api/batch

Testing with Email Sandbox

Before going to production, test your email integration using Email Sandbox. All official SDKs support Sandbox mode and allow you to easily switch between testing and production environments.

We recommend using environment variables to manage the switch between Sandbox and Production modes.

{% tabs %} {% tab title="Node.js" %}

import { MailtrapClient } from "mailtrap";

const apiKey = process.env.MAILTRAP_API_KEY;
const isSandbox = process.env.MAILTRAP_USE_SANDBOX === "true";
const inboxId = isSandbox ? Number(process.env.MAILTRAP_INBOX_ID) : undefined; // required only for sandbox

const client = new MailtrapClient({
  token: apiKey,
  sandbox: isSandbox,
  testInboxId: inboxId, // undefined is ignored for production
});

client
  .send({
    from: {
      name: "Mailtrap Test",
      email: isSandbox ? "[email protected]" : "[email protected]",
    },
    to: [{ email: "[email protected]" }],
    subject: isSandbox ? "[SANDBOX] Demo email" : "Welcome onboard",
    text: "This is a minimal body for demonstration purposes.",
  })
  .then(console.log)
  .catch(console.error);

{% endtab %}

{% tab title="Python" %}

import os
import mailtrap as mt

API_KEY = os.environ["MAILTRAP_API_KEY"]
IS_SANDBOX = os.environ.get("MAILTRAP_USE_SANDBOX", "true").lower() == "true"
INBOX_ID = os.environ.get("MAILTRAP_INBOX_ID")

client = mt.MailtrapClient(
  token=API_KEY,
  sandbox=IS_SANDBOX,
  inbox_id=INBOX_ID,  # None is ignored for production
)

# Create mail object
mail = mt.Mail(
    sender=mt.Address(email="[email protected]", name="John Smith"),
    to=[mt.Address(email="[email protected]")],
    subject="You are awesome!",
    text="Congrats for sending test email with Mailtrap!",
)

client.send(mail)

{% endtab %}

{% tab title="PHP" %}

<?php

use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;
use Mailtrap\Mime\MailtrapEmail;
use Symfony\Component\Mime\Address;

require __DIR__ . '/vendor/autoload.php';

$apiKey    = getenv('MAILTRAP_API_KEY');
$isSandbox = filter_var(getenv('MAILTRAP_USE_SANDBOX'), FILTER_VALIDATE_BOOL);
$inboxId   = $isSandbox ? getenv('MAILTRAP_INBOX_ID') : null; // required only for sandbox

$client = MailtrapClient::initSendingEmails(
    apiKey: $apiKey,
    isSandbox: $isSandbox,
    inboxId: $inboxId // null is ignored for production
);

$email = (new MailtrapEmail())
    ->from(new Address($isSandbox ? '[email protected]' : '[email protected]'))
    ->to(new Address('[email protected]'))
    ->subject($isSandbox ? '[SANDBOX] Demo email' : 'Welcome onboard')
    ->text('This is a minimal body for demonstration purposes.');

$response = $client->send($email);

// Access response body as array (helper optional)
var_dump(ResponseHelper::toArray($response));

{% endtab %}

{% tab title="Ruby" %}

require 'mailtrap'

client = Mailtrap::Client.new(api_key: 'your-api-key', sandbox: true, inbox_id: YOUR_INBOX_ID)
client.send(mail)

# You can also pass the request parameters directly
client.send(
  from: { email: '[email protected]', name: 'Mailtrap Test' },
  to: [
    { email: '[email protected]' }
  ],
  subject: 'You are awesome!',
  text: 'Congrats for sending test email with Mailtrap!'
)

{% endtab %}

{% tab title="Java" %}

import io.mailtrap.client.MailtrapClient;
import io.mailtrap.config.MailtrapConfig;
import io.mailtrap.factory.MailtrapClientFactory;
import io.mailtrap.model.request.emails.Address;
import io.mailtrap.model.request.emails.MailtrapMail;

import java.util.List;

public class MailtrapJavaSDKSandboxTest {

    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
    private static final String SENDER_EMAIL = "[email protected]";
    private static final String RECIPIENT_EMAIL = "[email protected]";
    private static final long INBOX_ID = 1L;

    public static void main(String[] args) {
        final MailtrapConfig config = new MailtrapConfig.Builder()
            .token(TOKEN)
            .sandbox(true)
            .inboxId(INBOX_ID)
            .build();

        final MailtrapClient client = MailtrapClientFactory.createMailtrapClient(config);

        final MailtrapMail mail = MailtrapMail.builder()
            .from(new Address(SENDER_EMAIL))
            .to(List.of(new Address(RECIPIENT_EMAIL)))
            .subject("Hello from Mailtrap Sandbox Sending!")
            .text("Welcome to Mailtrap Sandbox Sending!")
            .build();

        // Send an email using Mailtrap Sending API
        try {
            System.out.println(client.send(mail));
        } catch (Exception e) {
            System.out.println("Caught exception : " + e);
        }
    }
}

{% endtab %}

{% tab title=".NET" %}

var apiToken = "<API-TOKEN>";
var inboxId = <INBOX-ID>; // Only needed for sandbox
using var mailtrapClientFactory = new MailtrapClientFactory(apiToken);
IMailtrapClient mailtrapClient = mailtrapClientFactory.CreateClient();

SendEmailRequest request = SendEmailRequest
    .Create()
    .From("[email protected]", "Mailtrap Test")
    .To("[email protected]")
    .Subject("You are awesome!")
    .Text("Congrats for sending test email with Mailtrap!");

SendEmailResponse? response = await mailtrapClient
    .Test(inboxId)
    .Send(request);+

{% endtab %} {% endtabs %}

How Sandbox works

Sandbox emails are captured in your test inbox instead of being delivered to real recipients.

To find your Sandbox ID:

Open your Sandbox inbox in Mailtrap.
Copy the ID from the inbox URL.

Example: https://mailtrap.io/inboxes/2564102/messages
Sandbox ID: 2564102

Name		Name	Last commit message	Last commit date
parent directory ..
templates		templates
README.md		README.md
SUMMARY.md		SUMMARY.md
authentication.md		authentication.md
openapi-specs.md		openapi-specs.md
rate-limits.md		rate-limits.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

Overview

LLM & AI Agent Integration

Documentation structure

Email Sending

Templates

Promotional

Email Sandbox

Account Management

Quick Start

Get API Credentials

Install an SDK

Send your first email

Email Sending Options

Transactional emails

Bulk stream

Batch sending

Testing with Email Sandbox

How Sandbox works

FilesExpand file tree

api-docs

Directory actions

More options

Directory actions

More options

Latest commit

History

api-docs

Folders and files

parent directory

README.md

Overview

LLM & AI Agent Integration

Documentation structure

Email Sending

Templates

Promotional

Email Sandbox

Account Management

Quick Start

Get API Credentials

Install an SDK

Send your first email

Email Sending Options

Transactional emails

Bulk stream

Batch sending

Testing with Email Sandbox

How Sandbox works