Create email addresses

Creating real email addresses on demand is a key feature of MailSlurp. Before you start sending and receiving emails you need an inbox.

What is an inbox?

An inbox is a private email account belonging to your API Key. Inboxes have real, unique email addresses that can send and receive emails and attachments. You can create inboxes in code or using the dashboard.

create-inbox

Inbox features:

Has real email address. Either custom or randomly assigned
Send emails and attachments
Receive emails (sent to their email addresses)
SMTP or HTTP type inboxes
Can be a virtual inbox to prevent sending
Permanent archive (permanent by default but you can set an expiration date)

Inbox types

Inboxes can be either HTTP or SMTP mailboxes. HTTP inboxes are the default and best for most cases. They can send and receive emails and are processed by AWS SES. SMTP inboxes are processed by a custom mail server running at mx.mailslurp.com. Use SMTP inboxes if you need SMTP and IMAP access or are supported older mail clients. For more information see the SMTP vs HTTP inbox guide.

Email addresses

Inboxes have an email address that is either randomly assigned by MailSlurp or specified by you when created. You can only use custom email addresses with a custom domain.

Creating an inbox

You can create inboxes using the dashboard or with the API. Inboxes are either given a randomly assigned email address at creation or use the email address you provide. Note you must verify your domain to use a custom address.

Here is how to create an inbox using the Javascript SDK.

const inbox = await mailslurp.createInbox();

console.log(inbox);

Pretty simple! Inboxes use HTTP type configuration by default meaning they are processed by AWS SES. HTTP inboxes are suitable for test email accounts and other use cases that require IMAP and SMTP access. To support all email clients use an SMTP type inbox. SMTP inboxes are slower but support all email clients and are more suited to client facing application that are receiving emails only.

SMTP/IMAP access

Inboxes created with SMTP type have access enabled via SMTP and IMAP but require a password and username. Configure this in your dashboard or see the access guide.

Virtual inboxes

Every inbox can be created with the virtualInbox setting to enable a fake SMTP server. Virtual inboxes allow inbound emails but prevent any emails from being sent to real users. You can use them to test emails safely without spamming users.

const MailSlurp = require('mailslurp-client').default;
const mailslurp = new MailSlurp({
  apiKey: process.env.API_KEY ?? 'your-api-key',
});

// create a virtual inbox
const inbox = await mailslurp.inboxController.createInbox({
  virtualInbox: true,
});

Virtual inboxes still create SentEmail records so you can check the result but no email will leave the fake SMTP server.

fake smtp server

Create inbox options

You can also create inboxes in other ways using the inboxController directly. An example in Javascript is as follows:

const MailSlurp = require('mailslurp-client').default;
const mailslurp = new MailSlurp({
  apiKey: process.env.API_KEY ?? 'your-api-key',
});

// create an inbox with options using the inbox controller
const inbox = await mailslurp.inboxController.createInbox({
  // name is used a contact name when sending
  name: 'John Doe',
  // use the expanded domain pool so randomly assigned email address is more varied
  useDomainPool: true,
  // permanent by default or supply an expires at time
  expiresAt: undefined,
});

Custom email addresses

By default inboxes are assigned a randomly-generated email address ending in @mailslurp.com.

For instance: 65b5ebf7f4fa@mailslurp.com. Use the MailSlurp domain pool options with inbox requests to generate email addresses with end domains selected randomly for a list of MailSlurp domains such as mailslurp.info, mailslurp.xyz etc.

You can specify custom email addresses by using a custom domain. For instance: invoices@myorg.com.

const inbox = await mailslurp.createInbox("invoices@myorg.com");

console.log(inbox.emailAddress);
// 'invoices@myorg.com'

Or using the inbox controller directly:

// create an inbox with options
const inbox = await inboxController.createInbox({
    emailAddress: 'anything@my-verified-domain.com',
})

To select your own email address you must use a custom domain. Custom domains can be purchased from any domain provider and then added to the MailSlurp dashboard.

If no email address is selected MailSlurp will by default use a randomly assigned email address ending in @mailslurp.com.

Short email addresses

Create email accounts with addresses less than 31 characters using the useShortAddress option:

const inbox = await mailslurp.inboxController.createInboxWithOptions({
  createInboxDto: {
    useShortAddress: true,
  },
});
expect(inbox.emailAddress.length).toBeLessThan(31);

Domain pool

Use the useDomainPool option when creating inboxes to generate email addresses with an email address ending in mailslurp.xyz, mailslurp.info etc. This is useful when receiving emails on corporate mail servers that may filter out the default MailSlurp domain.

Aliases, forwarding and plus suffix

MailSlurp does not support + suffix email addresses such as myinbox+test@mailslurp.com. This is because this is not a part of the SMTP standard and is instead a feature that Gmail and other providers added themselves. In MailSlurp every address is treated as distinct. Use the email aliases feature to create aliases for an inbox or address to allow auto-forwarding. These are forwarded to your underlying email just like + addresses.

MailSlurp has powerful inbox rulesets that can be attached to inboxes to allow control over which emails can be sent or receiving by an inbox. Rules allow wild card pattern matching such as:

{
    "action": "BLOCK",
    "scope": "SENDING_EMAILS",
    "target": "*"
}

See the inbox ruleset guide for more information.

Lifetime

All inboxes are permanent by default (provided your plan supports permanent inboxes). If you don't have a plan MailSlurp will expire inboxes after a default time for free users. For more information see expired inboxes guide. Emails that cannot be received due to a plan limit or an inbox ruleset are persisted as missed emails. These can be viewed in the dashboard or via the API so that you never lose an email.

// create an inbox that expires in 5 minutes
const inbox2 = await mailslurp.createInboxWithOptions({
  expiresIn: 5 * 60_000,
});

How inboxes work

Once you create an inbox any email sent to the inbox's email address will be received by MailSlurp, parsed, and stored. Inboxes and emails are private and permanent (unless otherwise specified). Inboxes can also send emails and route mail with webhooks.

Creating mailboxes with MailSlurp

Table of contents