Skip to main content

Overview

mailslurp

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.

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 @mailslurp.com) 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.

access

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.

smtp

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​

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.

Webhooks​

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.

webhoks-basic

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 @mailslurp.com.

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: "https://my-server.com/webhook",
    eventName: "NEW_EMAIL"
})

Then configure your server to receive the webhook push:

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

/**
 * define your endpoint
 * here your webhook url should include the full protocol and domain.
 * i.e.: https://myserver.com/my-webhook-endpoint
 */
app.post("/my-webhook-endpoint", function (request, response) {
  // access the data on request body
  console.log(request.body.inboxId);

  // return a 2xx status code so MailSlurp knows you received it
  response.sendStatus(200);
});

app.listen(80);

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: