Skip to content

Developer documentation


MailSlurp is a powerful mailserver and SMS API service for developers. Build and test email and TXT related applications and functionality. This domain contains the developer documentation and API reference. See the left hand sub-menu for documentation in your language or framework of choice or read ahead for key concepts.

Quick start

To start using MailSlurp first create a free account and obtain an API_KEY. Then select and configure an SDK client of your choice.

// create mailslurp client
const { MailSlurp } = require('mailslurp-client');
const mailslurp = new MailSlurp({ apiKey: process.env.API_KEY });

// create inboxes
const inbox1 = await mailslurp.createInbox();
const inbox2 = await mailslurp.createInbox();

// send email
await mailslurp.sendEmail(, {
  to: [inbox2.emailAddress],
  subject: "Test",
  body: "<span>Hello 👋</span>",
  isHTML: true

// receive email using wait methods
const email = await mailslurp.waitForLatestEmail(, 60000, true)

// list emails in inbox
const emails = await mailslurp.inboxController.getInboxEmailsPaginated({inboxId:})
// create client
var config = new Configuration();
config.ApiKey.Add("x-api-key", ApiKey);

// create inboxes
var inboxControllerApi = new InboxControllerApi(config);
var inbox1 = inboxControllerApi.CreateInbox();
var inbox2 = inboxControllerApi.CreateInbox();

// send email
inboxControllerApi.SendEmail(inbox1.Id, new SendEmailOptions(
    to: new List<string> { inbox2.EmailAddress },
    subject: "Test CSharp",
    body: "<span>Hello</span>",
    isHTML: true

// receive email with wait controller
var email = new WaitForControllerApi(config).WaitForLatestEmail(inbox2.Id, 60000, true);
StringAssert.Contains(email.Body, "Hello");

// list emails in inbox
var emails = inboxControllerApi.GetInboxEmailsPaginated(inbox2.Id);
Assert.AreEqual(emails.TotalElements, 1);
// create a context with your api key
ctx := context.WithValue(context.Background(), mailslurp.ContextAPIKey, mailslurp.APIKey{Key: apiKey})

// create mailslurp client
client := mailslurp.NewAPIClient(mailslurp.NewConfiguration())

// create inboxes
inbox1, _, err := client.InboxControllerApi.CreateInbox(ctx, &mailslurp.CreateInboxOpts{})
inbox2, _, err := client.InboxControllerApi.CreateInbox(ctx, &mailslurp.CreateInboxOpts{})
assert.Nil(t, err)

// send email from inbox 1 to inbox 2
_, err = client.InboxControllerApi.SendEmail(ctx, inbox1.Id, mailslurp.SendEmailOptions{
    To:      []string{inbox2.EmailAddress},
    Subject: "Test",
    Body:    "<span>Hello</span>",
    IsHTML:  true,
assert.Nil(t, err)

// now receive the email at inbox 2
email, _, err := client.WaitForControllerApi.WaitForLatestEmail(ctx, &mailslurp.WaitForLatestEmailOpts{
    InboxId:    optional.NewInterface(inbox2.Id),
    Timeout:    optional.NewInt64(60000),
    UnreadOnly: optional.NewBool(true),
assert.Nil(t, err)
assert.Contains(t, email.Body, "Hello")

// list emails
emails, _, err := client.InboxControllerApi.GetInboxEmailsPaginated(ctx, inbox2.Id, nil)
assert.Nil(t, err)
assert.Equal(t, emails.TotalElements, int64(1))
// create client
ApiClient client = Configuration.getDefaultApiClient();

// create inboxes
InboxControllerApi inboxControllerApi = new InboxControllerApi(client);
InboxDto inbox1 = inboxControllerApi.createInboxWithDefaults();
InboxDto inbox2 = inboxControllerApi.createInboxWithDefaults();

// send email
SendEmailOptions sendOptions = new SendEmailOptions();
inboxControllerApi.sendEmail(inbox1.getId(), sendOptions);

// receive email with wait for controller
Email email = new WaitForControllerApi(client).waitForLatestEmail(inbox2.getId(), 60000L, true, null, null, null, null);
assertEquals(email.getBody().contains("Hello"), true);

// list emails in inbox
PageEmailPreview emails = inboxControllerApi.getInboxEmailsPaginated(inbox2.getId(), null, null, null, null, null);
// configure client with api key
$config = MailSlurp\Configuration::getDefaultConfiguration()
    ->setApiKey('x-api-key', getenv('API_KEY'));

// create an inbox controller with config
$inboxController = new MailSlurp\Apis\InboxControllerApi(null, $config);

// create inboxes
$inbox1 = $inboxController->createInbox();
$inbox2 = $inboxController->createInbox();

// send an email
$inboxController->sendEmail($inbox1->getId(), new \MailSlurp\Models\SendEmailOptions(array(
    'to' => array($inbox2->getEmailAddress()),
    'subject' => 'Test email',
    'body' => '<span>Hello 👋</span>',
    'is_html' => true

// wait for email
$waitForController = new MailSlurp\Apis\WaitForControllerApi(null, $config);
$email = $waitForController->waitForLatestEmail($inbox2->getId(), 60_000, true);
PHPUnit\Framework\Assert::assertStringContainsString("Hello", $email->getBody());

// list emails in inbox
$emails = $inboxController->getInboxEmailsPaginated($inbox2->getId());
PHPUnit\Framework\Assert::assertEquals(1, $emails->getTotalElements());
import mailslurp_client
# create a mailslurp configuration
configuration = mailslurp_client.Configuration()
configuration.api_key['x-api-key'] = api_key
with mailslurp_client.ApiClient(configuration) as api_client:
    # create an inbox
    inbox_controller = mailslurp_client.InboxControllerApi(api_client)
    inbox_1 = inbox_controller.create_inbox()
    inbox_2 = inbox_controller.create_inbox()

    # send email
    opts = mailslurp_client.SendEmailOptions() = [inbox_2.email_address]
    opts.subject = "Hello"
    opts.body = "Email content <strong>supports HTML</strong>"
    opts.is_html = True
    inbox_controller.send_email(, send_email_options=opts)

    # receive email with wait controller
    wait_controller = mailslurp_client.WaitForControllerApi(api_client)
    email = wait_controller.wait_for_latest_email(, timeout=60000, unread_only=True)

    # assert that the message was received
    assert email.inbox_id ==
    assert email.subject == "Hello"
    assert "Email content" in email.body

    # list emails in inbox
    emails = inbox_controller.get_inbox_emails_paginated(
    assert emails.total_elements == 1
# configure mailslurp client
MailSlurpClient.configure do |config|
  config.api_key['x-api-key'] = API_KEY

# create inboxes
inbox_controller =
inbox_1 = inbox_controller.create_inbox
inbox_2 = inbox_controller.create_inbox

# send an email
  to: [inbox_2.email_address],
  subject: 'Test',
  isHTML: true,
  body: '<h1>Hello!</h1>'

# receive email with wait controller
wait_controller =
email = wait_controller.wait_for_latest_email({ inbox_id:, timeout: 60000 })
expect(email.body).to include("Hello")

# list inbox emails
emails = inbox_controller.get_emails(
expect(emails.length).to be(1)

You can control MailSlurp in many other ways. See the language sections in the navigation or try the following:

Key concepts

MailSlurp allows you to create email addresses and mailservers on demand and control them via HTTP REST, SMTP, IMAP, GraphQL, web dashboard and SDK clients in a wide range of languages. You can also receive email events directly to your server via webhooks.

Inbox email addresses

A key concept in MailSlurp is the inbox. An inbox has a real email address and can send and receive email. You can create inboxes with a randomly assigned email address (ending in or by using your own custom domain with and a specified custom address.

SMS and phone numbers

You can receive inbound SMS (TXT messages) using real phone numbers with our SMS API, web-app, or webhooks.

Programmatic access

MailSlurp gives you fine control over email accounts in code and tests. In your application you call the API directly or let MailSlurp post webhook events to your server endpoint.


SMTP and IMAP access

Inboxes can be either SMTP or HTTP type inboxes. Both have the same features but differ in access methods:

  • SMTP inboxes allow login with SMTP and IMAP clients such as Thunderbird
  • HTTP inboxes can only be controlled via the API clients or web dashboard

To access inboxes using SMTP or IMAP first create an SMTP type inbox, then use the IMAP or SMTP username and password attached and the server endpoints below.


Emails and attachments

MailSlurp can send and receive emails at scale via a number of protocols and API methods.

What is an email?

An email is a payload delivered via SMTP protocol in the form of an SMTP message. An SMTP message envelope has two main parts: the header (containing fields like Subject, To, From) and a body. The body is the content of the email (text, HTML, images) and is multipart encoded.

Email parsing process

When MailSlurp mail-servers receive an email that is destined for an inbox you have created several steps occur. The header fields and content are parsed, attachments and body content are saved to disk, and header fields plus metadata are stored in a database. You can then fetch the email using the API, dashboard, or via webhooks.


Attachments are uploaded and downloaded using either octet-streams or base-64 encoding. To send attachments first upload them and then use the associate attachment IDs with your send email options. Attachments can be downloaded from an email by passing the associated IDs.


You can create custom event webhooks for every inbox. These will be triggered by events such as NEW_EMAIL or EMAIL_OPENED and MailSlurp will send a related JSON payload to a server endpoint you provide. This means you can write event driven application code to handle inbound emails.


Webhooks send an event object to your server with an entity ID. Use the ID to fetch the full object for further processing.

See webhook documentation for more information.

Creating email addresses

You can create inboxes on demand. Each inbox has a real email address that by default is a randomly assigned address ending in

Custom domains

Register a domain and associate the domain with MailSlurp to enable the use of any email address ending in your domain name.

Sending emails

Emails can be sent from any inbox you create. To maintain a good delivery rate and spam reputation it is recommended to validate email addresses before or during sending.

Basic email sending

The simplest sending example using the Javascript client looks like so:

await mailslurp.sendEmail(inboxId, {
  to: [recipientEmail],
For more information see the sending guide.

Bounces and complaints

Emails sent to non-existing email addresses or to mail servers that did not expect your email may result in complaints or bounces. Bounces and complaints are recorded against your account and can result in suspension of sending capabilities. For this reason it is recommended to only email recipients you have verified or who have consented to your mail.

Receiving emails

MailSlurp provides multiple methods for receiving emails.

Waiting for emails

A key differentiating feature of MailSlurp is the ability to wait for emails to arrive in an inbox. The WaitForControllerApi endpoints provide various wait methods that will poll the email database until a timeout is exceeded or conditions are met. This is very useful in tests that expect an email to arrive after a given action and allow you to wait for that event. Available wait methods include as:

  • waitForLatestEmail: if inbox is empty wait for an email to arrive or else return latest email
  • waitForEmailCount: wait for n emails in an inbox and return a list of them or throw
  • waitForNthEmail: wait for email at a given count and return it or throw.

Receiving emails with webhooks

Another way to receive emails in by using webhooks that can be attached to inboxes. When a new email event occurs in an inbox each webhook associated with it will be sent a new email payload. Use the payload to look up the new email and process the event on your server:

mailslurp.webhookController.createWebhook(inboxId, {
    url: "",
    eventName: "NEW_EMAIL"

Then configure your server to receive the webhook push:

const express = require("express");
const app = express.createServer();

 * define your endpoint
 * here your webhook url should include the full protocol and domain.
 * i.e.:
 */"/my-webhook-endpoint", function (request, response) {
  // access the data on request body

  // return a 2xx status code so MailSlurp knows you received it


Testing frameworks

See testing guide or the examples page for more information.

Dashboards and GUI clients

Login to the MailSlurp web app to view emails online and manage your account.

More information

Please see the guides and examples sections for more information or the individual sections for each language: