Ask

On this page

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.

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:

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:

Node.js

Python

PHP

Ruby

Java

.NET

AskCopy

npm install mailtrap

The .NET SDK is available via GitHub Packages. First, add the GitHub source:

AskCopy

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:

AskCopy

dotnet add package Mailtrap -s github-mailtrap

Send your first email

Below are minimal examples for sending an email:

Node.js

Python

PHP

Ruby

Java

.NET

AskCopy

import { MailtrapClient } from "mailtrap";

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

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

AskCopy

import mailtrap as mt

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

client = mt.MailtrapClient(token=API_TOKEN)

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

client.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.

Node.js

Python

PHP

Ruby

Java

.NET

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/sandboxes/2564102 Sandbox ID: 2564102

NextAuthentication

Last updated 1 month ago

Was this helpful?

AskCopy

<?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/settings/api-tokens
);

$email = (new MailtrapEmail())
    ->from(new Address('sender@example.com'))
    ->to(new Address('recipient@example.com'))
    ->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));

AskCopy

require 'mailtrap'

# Create mail object
mail = Mailtrap::Mail.from_content(
  from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
  to: [
    { email: 'your@email.com' }
  ],
  reply_to: { email: 'support@example.com', 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: 'mailtrap@example.com', name: 'Mailtrap Test' },
  to: [
    { email: 'your@email.com' }
  ],
  subject: 'You are awesome!',
  text: 'Congrats for sending test email with Mailtrap!'
)

AskCopy

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 SENDER_EMAIL = "sender@domain.com";
    private static final String RECIPIENT_EMAIL = "recipient@domain.com";

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

AskCopy

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("sender@yourdomain.com"),
      To = new[] { new EmailAddress("recipient@example.com") },
      Subject = "Hello from Mailtrap",
      TextBody = "Welcome to Mailtrap Email API!"
};

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

AskCopy

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 ? "sandbox@example.com" : "no-reply@your-domain.com",
    },
    to: [{ email: "recipient@example.com" }],
    subject: isSandbox ? "[SANDBOX] Demo email" : "Welcome onboard",
    text: "This is a minimal body for demonstration purposes.",
  })
  .then(console.log)
  .catch(console.error);

AskCopy

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="sender@example.com", name="John Smith"),
    to=[mt.Address(email="recipient@example.com")],
    subject="You are awesome!",
    text="Congrats for sending test email with Mailtrap!",
)

client.send(mail)

AskCopy

<?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 ? 'sandbox@example.com' : 'no-reply@your-domain.com'))
    ->to(new Address('recipient@example.com'))
    ->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));

AskCopy

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: 'mailtrap@example.com', name: 'Mailtrap Test' },
  to: [
    { email: 'your@email.com' }
  ],
  subject: 'You are awesome!',
  text: 'Congrats for sending test email with Mailtrap!'
)

AskCopy

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 SENDER_EMAIL = "sender@domain.com";
    private static final String RECIPIENT_EMAIL = "recipient@domain.com";
    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);
        }
    }
}

AskCopy

using var mailtrapClientFactory = new MailtrapClientFactory(apiToken);
IMailtrapClient mailtrapClient = mailtrapClientFactory.CreateClient();

SendEmailRequest request = SendEmailRequest
    .Create()
    .From("hello@demomailtrap.co", "Mailtrap Test")
    .To("world@demomailtrap.co")
    .Subject("You are awesome!")
    .Text("Congrats for sending test email with Mailtrap!");

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