Introduction

MailSlurp is a free API for sending and receiving emails from applications or tests. It is designed as a simpler, more powerful interface for SMTP mail servers. You can use MailSlurp for any email related process including testing and normal sending and receiving.

Questions

For any questions or issues please reach out any time via email.

API Key

All MailSlurp requests require an API Key. Get your API Key by signing up.

Install

MailSlurp can be used a REST API or with officially supported clients in Javascript, Ruby, Python, PHP, Java, C#, Golang and more libraries and SDKs.

This guide will use examples from the recommended Javascript client. For other languages and libraries please see the integrations page.

NPM Package

Configuration

Note: All requests require an API Key. Get yours free via the MailSlurp Dashboard

Create email addresses

MailSlurp uses the concept of an inbox. Inboxes have IDs and email addresses. If you want to receive emails you'll need to create an inbox first.

returns a randomly assigned email address such as . This address is unique, private, and only accessible by you. To use a specific address and domain see the custom domains guide.

What is an inbox?

An inbox has an and a unique . Free inboxes end in .

Any emails sent to an inbox's email address will be routed to the inbox. All emails are stored privately.

Custom domains

You can register any domain that you have control of. See the custom domains guide for more.

Send emails

You can send real emails with MailSlurp. Attachments, templating, and forwarding are all possible.

Minimal example

The most simple send action requires an inbox and an array of at least one valid recipient email addresses.

After executing the method MailSlurp will send a real email to the recipient provided.

Filtering bounced recipients

If a recipient you are emailing has rejected an email in the past or caused a bounce event then the sending of subsequent emails to that recipient may cause an error at send time. To avoid these errors use the option in the send email options.

Email content

With MailSlurp you can send simple strings or HTML. Both methods support templating, attachments, and custom charsets.

Email templating

MailSlurp supports email templating using moustache syntax:

If you provide in your send options MailSlurp will substitute any variables found in the subject or body.

For example:

Attachments

To send attachments first upload each attachment you wish to send.

Attachment content should be a Base 64 encoded string.

Once you have uploaded each attachment you can use the returned attachment IDs in the field of the .

Random test addresses

If you don't care what address an email is sent from (perhaps for testing) use the method. This will send emails from a random MailSlurp address.

More sending options

MailSlurp has many options for sending emails. Here are a few:

For full details see the method documentation.

Receive emails

MailSlurp makes receiving emails easy. There is one important concept to understand:

Email is asynchronous by nature. That means many MailSlurp methods use a function and return once expected criteria have been met.

Simple receive

The easiest way to receive emails is to create a new empty inbox and send an email to it.

Then use to hold a connection open until at least one email appears in the inbox.

Note: will return immediately if the inbox contains an email.

Receiving with non-empty inboxes

If your inbox already contains some emails you can tell MailSlurp how many emails you expect it to contain.

You can get the number of emails in an inbox before you expect it to receive a new email address using the method.

Other methods

You can also wait for an inbox to contain an expected count and return all those emails:

Note: MailSlurp will return immediately if the inbox already contains an email.

Advanced receiving

For more control over email fetching use the methods with extra parameters. MailSlurp will hang the connection until all conditions are met or the timeout is exceeded.

Receiving attachments

If an email contains an attachment MailSlurp will archive the file and make the file's ID available in the email response. Something like so:

Using Webhooks

Webhooks enable you to receive emails via push notifications to your server or app that contain an email ID.

Webhooks are scoped to individual inboxes and can be created like so:

Searching emails

MailSlurp has simple but powerful email matching features that let you wait for an email that matches a particular subject, recipient or more.

For more information on email matching see the documentation.

Deleting entities

You can empty an inbox easily with:

Or delete it completely like so:

You can also delete emails individually with:

Full documentation

This guide covers only the most common MailSlurp features. For more details please see API/SDK documentation.

License

All MailSlurp libraries use an open MIT License.