Overview

Complete API documentation for the Mailtrap email platform

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.

Documentation structure

The API documentation is organized into the following sections:

Email Sending

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

Templates

Endpoints to manage email templates used for email sending, email sandbox, and campaigns.

Promotional

Endpoints to manage contacts. Contacts can be used to run campaigns and set up automations.

Email Sandbox

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

Account Management

Endpoints for programmatic management of account details and access permissions.

Quick Start

Get API Credentials

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

You must have a verified domain to send emails.

Keep your API token secure and never expose it in client-side code.

Install an SDK

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

Supported SDKs:

npm install mailtrap

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

Send your first email

Below are minimal examples for sending an email:

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);

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)

<?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));

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!'
)

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);
        }
    }
}

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);

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.

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);

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)

<?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));

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!'
)

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);
        }
    }
}

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);+

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

NextAuthentication

Last updated 9 days ago

Was this helpful?

Good afternoon

hashtagDocumentation structure

hashtagEmail Sending

hashtagTemplates

hashtagPromotional

hashtagEmail Sandbox

hashtagAccount Management

hashtag

hashtagQuick Start

hashtagGet API Credentials

hashtagInstall an SDK

hashtagSend your first email

hashtagEmail Sending Options

hashtagTransactional emails

hashtagBulk stream

hashtagBatch sending

hashtagTesting with Email Sandbox

hashtagHow Sandbox works