Creating inboxes

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.

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
• Permanent archive (permanent by default but you can set an expiration date)

Inboxes can be either HTTP or SMTP mailboxes. HTTP inboxes are processed by AWS SES and are best used as test email accounts. SMTP inboxes are processed by a custom mail server running at mx.mailslurp.com. Use SMTP inboxes for customer facing mailboxes that receive emails as they are more reliable for older SMTP clients. For more information see the SMTP vs HTTP inbox guide.

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 andc most other use cases. 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.

Create inbox options

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

import MailSlurp from "mailslurp-client";

const mailslurp = new MailSlurp({ apiKey: "your-api-key"})

// create a controller
const inboxController = mailslurp.inboxController

// create an inbox with options
const inbox = await inboxController.createInbox({
    // 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: null,
    // use SMTP for public facing inboxes that support older clients
    inboxType: 'SMTP_INBOX'
})
// { id: '65b5ebf7f4fa', emailAddress: '65b5ebf7f4fa@mailslurp.xyz', ... }

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.

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.

Inbox routing rules (allow, block, filter)

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.

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.

Let’s see it in action!