Javascript Documentation

Send and receive emails in NodeJS and the browser. Create real email addresses on demand to test email processes with Jest, Mocha, Cypress, Webdriver and more.

MailSlurp JSGlobalsMailSlurp

Class: MailSlurp

Official MailSlurp Client

This is the recommended client for mailslurp.com.

Features

  • Create email addresses on demand
  • Receive emails and attachments in code
  • Send emails and attachments
  • Create custom domains and webhooks

Get started

MailSlurp is free for personal use but you must have an account and an API Key.

Installing

First you'll need to install the MailSlurp package from npm.

npm install --save mailslurp-client

Importing

Next import the client into your application or test.

Typescript or ES6

import { MailSlurp } from "mailslurp-client"

NodeJS require

const MailSlurp = require('mailslurp-client').MailSlurp;

// or default import
const MailSlurp = require('mailslurp-client').default;

Configure

Next configure an instance of MailSlurp using your API Key.

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

Example usage

Now that you have a configured client you can use it to interact with MailSlurp. Here are some common examples:

Create an inbox

// create a new inbox
// will assign a random email address ending in `@mailslurp.com`
try {
  const randomizedInbox = await mailslurp.createInbox();
} catch (e) {
  // handle errors
}

// Or you can use a specific email address ending in `@<yourdomain>`
// note you must verify the domain with MailSlurp before 
// you can create email addresses using it
try {
  const customInbox = await mailslurp.createInbox('myaddress@mydomain.com');
} catch (e) {
  // handle errors
}

List your inboxes

// get a list of your existing inboxes
try {
  const inboxes = await mailslurp.getInboxes()
} catch (e) {
  // handle errors
}

List emails in an inbox

Get an email

One way to receive an email is to fetch it by ID. You can find an emails ID by listing the emails in an inbox.

try {
    const fullEmail = mailslurp.getEmail(emailId)
    console.log(fullEmail.body, fullEmail.subject) // etc
} catch (e) {
    // handle errors
}

WaitFor methods

Another way to receive an email is by using a waitFor method. WaitFor methods hold open a connection until a condition is met. This is useful for situation in which an email has been sent and you expect it to arrive within a given time period.

/**
 * Call an inbox and return the last received email 
 * OR wait until an email is received or timeout is reached
 */
waitForLatestEmail(inboxId?: string, timeout?: number): Promise<Email>

/**
 * Hold connection until inbox contains at least
 * expected number of emails and then return them
 */
waitForEmailCount(count?: number, inboxId?: string, timeout?: number): Promise<EmailPreview[]>

/**
 * Hold connection until inbox contains at least
 * expected number of emails that match a given match option input and return them
 */
waitForMatchingEmails(matchOptions: MatchOptions, count?: number, inboxId?: string, timeout?: number): Promise<EmailPreview[]>

/**
 *  Call an inbox and return email number `n` or wait for it to be received
 */ 
waitForNthEmail(inboxId: string, index: number, timeout?: number): Promise<Email>

WaitFor in action

Here is an example of a waitFor method in action.

// inside some test
cons inbox = mailslurp.createInbox()
await myWelcomeEmailAction(inbox.emailAddress)

try {
 const email = await mailslurp.waitForLatestEmail(inbox.id)
 expect(email.body).toBe('Welcome')
} catch (e) {
 // handle timeout or email wasn't received
}

Send an email

try {
  await mailslurp.sendEmail(inboxId, { 
    to: ['test@example.com'], 
    subject: 'Welcome',
    body: 'Hello!' 
  })
} catch (e) {
  // handle errors
}

Next steps

See the methods below for more details.

Hierarchy

  • MailSlurp

Index

Constructors

Methods

Constructors

constructor

+ new MailSlurp(opts: Config): MailSlurp

Defined in index.ts:154

Create a new MailSlurp instance

Parameters:

Name Type Description
opts Config

Returns: MailSlurp

Methods

bulkCreateInboxes

bulkCreateInboxes(count: number): Promise‹Inbox[]›

Defined in index.ts:498

Bulk create inboxes

Parameters:

Name Type
count number

Returns: Promise‹Inbox[]›


bulkDeleteInboxes

bulkDeleteInboxes(inboxIds: string[]): Promise‹Response›

Defined in index.ts:507

Bulk delete inboxes

Parameters:

Name Type
inboxIds string[]

Returns: Promise‹Response›


bulkSendEmails

bulkSendEmails(bulkSendEmailOptions: BulkSendEmailOptions): Promise‹Response›

Defined in index.ts:487

Bulk send emails

Parameters:

Name Type
bulkSendEmailOptions BulkSendEmailOptions

Returns: Promise‹Response›


createDomain

createDomain(options: CreateDomainOptions): Promise‹DomainPlusVerificationRecordsAndStatus›

Defined in index.ts:587

Create a custom domain for use with MailSlurp You must own and have access to DNS setup for the domain in order to verify it

Parameters:

Name Type Description
options CreateDomainOptions

Returns: Promise‹DomainPlusVerificationRecordsAndStatus›


createInbox

createInbox(emailAddress?: string): Promise‹Inbox›

Defined in index.ts:363

Create an inbox. Pass an optional emailAddress to specify the email address. If not argument is passed MailSlurp will assign the inbox a random email address ending in @mailslurp.com.

// create a new inbox
// will assign a random email address ending in `@mailslurp.com`
try {
  const randomizedInbox = await mailslurp.createInbox();
} catch (e) {
  // handle errors
}

// Or you can use a specific email address ending in `@<yourdomain>`
// note you must verify the domain with MailSlurp before 
// you can create email addresses using it
try {
  const customInbox = await mailslurp.createInbox('myaddress@mydomain.com');
} catch (e) {
  // handle errors
}

Parameters:

Name Type
emailAddress? string

Returns: Promise‹Inbox›


createNewEmailAddress

createNewEmailAddress(): Promise‹Inbox›

Defined in index.ts:189

Create a new inbox

const { id, emailAddress } = await mailslurp.createNewEmailAddress()

Returns: Promise‹Inbox›


createWebhook

createWebhook(inboxId: string, createWebhookOptions: CreateWebhookOptions): Promise‹Webhook›

Defined in index.ts:516

Create a webhook for notifications

Parameters:

Name Type
inboxId string
createWebhookOptions CreateWebhookOptions

Returns: Promise‹Webhook›


deleteDomain

deleteDomain(domainId: string): Promise‹Response›

Defined in index.ts:614

Delete domain

Parameters:

Name Type
domainId string

Returns: Promise‹Response›


deleteEmail

deleteEmail(emailId: string): Promise‹Response›

Defined in index.ts:341

Delete an email by id

Parameters:

Name Type Description
emailId string

Returns: Promise‹Response›


deleteEmailAddress

deleteEmailAddress(emailId: string): Promise‹Response›

Defined in index.ts:351

Delete an email by id

Parameters:

Name Type Description
emailId string

Returns: Promise‹Response›


deleteInbox

deleteInbox(inboxId: string): Promise‹Response›

Defined in index.ts:373

Delete an inbox by id

Parameters:

Name Type Description
inboxId string

Returns: Promise‹Response›


deleteWebhook

deleteWebhook(inboxId: string, webhookId: string): Promise‹Response›

Defined in index.ts:540

Remove a webhook from an inbox

Parameters:

Name Type
inboxId string
webhookId string

Returns: Promise‹Response›


downloadAttachment

downloadAttachment(emailId: string, attachmentId: string): Promise‹Response›

Defined in index.ts:551

Get email attachment by id

Returns HTTP response containing byte stream

Parameters:

Name Type
emailId string
attachmentId string

Returns: Promise‹Response›


emptyInbox

emptyInbox(inboxId: string): Promise‹Response›

Defined in index.ts:331

Delete all emails in a given inbox

Parameters:

Name Type Description
inboxId string

Returns: Promise‹Response›


getAllEmails

getAllEmails(page?: number, size?: number): Promise‹PageEmailProjection›

Defined in index.ts:415

Get all emails Returns paginated email previews

Parameters:

Name Type
page? number
size? number

Returns: Promise‹PageEmailProjection›


getAllInboxes

getAllInboxes(page?: number, size?: number): Promise‹PageInboxProjection›

Defined in index.ts:405

Get all inboxes paginated Returns paginated inbox previews

Parameters:

Name Type
page? number
size? number

Returns: Promise‹PageInboxProjection›


getAttachmentMetaData

getAttachmentMetaData(attachmentId: string, emailId: string): Promise‹AttachmentMetaData›

Defined in index.ts:576

Get attachment MetaData

MetaData includes name, size (bytes) and content-type.

Parameters:

Name Type
attachmentId string
emailId string

Returns: Promise‹AttachmentMetaData›


getDomain

getDomain(domainId: string): Promise‹DomainPlusVerificationRecordsAndStatus›

Defined in index.ts:605

Get domain

Parameters:

Name Type
domainId string

Returns: Promise‹DomainPlusVerificationRecordsAndStatus›


getDomains

getDomains(): Promise‹Array‹DomainPreview››

Defined in index.ts:596

Get domains

Returns: Promise‹Array‹DomainPreview››


getEmail

getEmail(emailId: string): Promise‹Email›

Defined in index.ts:452

Get a full email from by id. To get an emails ID use the getEmails or waitFor methods with an inbox

try {
    const fullEmail = mailslurp.getEmail(emailId)
    console.log(fullEmail.body, fullEmail.subject) // etc
} catch (e) {
    // handle errors
}

Parameters:

Name Type Description
emailId string

Returns: Promise‹Email›


getEmails

getEmails(inboxId: string, args: GetMessagesOptions): Promise‹EmailPreview[]›

Defined in index.ts:429

Get all emails in an inbox as EmailPreviews. To get the full email, use the getEmail endpoint

try {
    // first get email previews for an inbox
    const emails = mailslurp.getEmails(inboxId, { limit: 1 })

    // then get the full email by id
    const fullEmail = mailslurp.getEmail(emails[0].id)

    console.log(fullEmail.body, fullEmail.subject) // etc
} catch (e) {
    // handle errors
}

Parameters:

Name Type Default Description
inboxId string - -
args GetMessagesOptions {}

Returns: Promise‹EmailPreview[]›


getInbox

getInbox(inboxId: string): Promise‹Inbox›

Defined in index.ts:383

Get an inbox by id

Parameters:

Name Type Description
inboxId string

Returns: Promise‹Inbox›


getInboxes

getInboxes(): Promise‹Inbox[]›

Defined in index.ts:394

Get all inboxes

// get a list of your existing inboxes
try {
  const inboxes = await mailslurp.getInboxes()
} catch (e) {
  // handle errors
}

Returns: Promise‹Inbox[]›


getRawEmail

getRawEmail(emailId: string): Promise‹string›

Defined in index.ts:462

Get an email's raw contents from by id

Parameters:

Name Type Description
emailId string

Returns: Promise‹string›


getWebhooks

getWebhooks(inboxId: string): Promise‹Webhook[]›

Defined in index.ts:529

Get webhooks for an inbox

Parameters:

Name Type Description
inboxId string

Returns: Promise‹Webhook[]›


sendEmail

sendEmail(inboxId: string, sendEmailOptions: SendEmailOptions): Promise‹Response›

Defined in index.ts:475

Send and email from a given inbox

try {
  await mailslurp.sendEmail(inboxId, { 
    to: ['test@example.com'], 
    subject: 'Welcome',
    body: 'Hello!' 
  })
} catch (e) {
  // handle errors
}

Parameters:

Name Type Description
inboxId string -
sendEmailOptions SendEmailOptions

Returns: Promise‹Response›


sendEmailSimple

sendEmailSimple(sendEmailOptions: SendEmailOptions): Promise‹Response›

Defined in index.ts:203

Send an email from a random address

To send from a known address first create an inbox and then use the sendEmail endpoints.

Parameters:

Name Type Description
sendEmailOptions SendEmailOptions

Returns: Promise‹Response›


uploadAttachment

uploadAttachment(options: UploadAttachmentOptions): Promise‹Array‹String››

Defined in index.ts:565

Upload an attachment for use in email sending

Attachment contents must be a base64 encoded string

Parameters:

Name Type
options UploadAttachmentOptions

Returns: Promise‹Array‹String››


waitForEmailCount

waitForEmailCount(count?: number, inboxId?: string, timeout?: number): Promise‹EmailPreview[]›

Defined in index.ts:317

Wait for and return list of emails with length of given count

try {
  // wait for 4 emails in an inbox then return them
  const emails = waitForEmailCount(4, inboxId)
} catch (e) {
  // handle error or timeout
}

Parameters:

Name Type Description
count? number -
inboxId? string -
timeout? number

Returns: Promise‹EmailPreview[]›


waitForLatestEmail

waitForLatestEmail(inboxId?: string, timeout?: number): Promise‹Email›

Defined in index.ts:226

Wait for an email to arrive at an inbox or return first found result Retries the call until at least one email is found or a maximum timeout is exceeded

try {
  const email = await mailslurp.waitForLatestEmail(inboxId)
} catch (e) {
  // handle timeout or email wasn't received
}

Parameters:

Name Type Description
inboxId? string uuid
timeout? number max milliseconds to wait

Returns: Promise‹Email›


waitForMatchingEmails

waitForMatchingEmails(matchOptions: MatchOptions, count?: number, inboxId?: string, timeout?: number): Promise‹EmailPreview[]›

Defined in index.ts:285

Wait until both count and match options are met and return list of emails. Match options are a bit verbose but allow for type safety on the API end. Match options allow simple CONTAINS or EQUALS filtering on SUBJECT, TO, BCC, CC, and FROM.

try {
  const matchingWelcomeEmails = await mailslurp.waitForMatchingEmails({
    matches: [
      {
        field: 'SUBJECT',
        should: 'CONTAIN',
        value: 'Welcome'
      }
    ]
  }, 1, inboxId)
} catch (e) {
  // handle timeout or no results
}

Parameters:

Name Type Description
matchOptions MatchOptions -
count? number -
inboxId? string -
timeout? number timeout max milliseconds to wait

Returns: Promise‹EmailPreview[]›


waitForNthEmail

waitForNthEmail(inboxId: string, index: number, timeout?: number): Promise‹Email›

Defined in index.ts:250

Return or wait for email number n in an inbox

try {
  const email3 = await mailslurp.waitForNthEmail(inboxId, 3)
} catch (e) {
  // handle timeout or email wasn't received
}

Parameters:

Name Type Description
inboxId string -
index number -
timeout? number

Returns: Promise‹Email›