Class MailSlurp

The official MailSlurp Javascript library. A wrapper around the MailSlurp REST API.

Create an instance of this class to call MailSlurp API methods. Contains top level convenience functions. Access the full API controllers as properties on the instance.

Create instance

You must provide a configuration object with your API Key as the apiKey property when creating a new instance.

const MailSlurp = require('mailslurp-client').default;
const mailslurp = new MailSlurp({
 apiKey: 'xxxx'
})

Most methods are asynchronous and return Promises. You can await the results or use .then(result => {}) Common controllers include the InboxController, EmailController, SMSController and the WaitForController for receiving emails.

// call convenience functions
const email = await mailslurp.waitForLatestEmail(...args)

// call controllers to access full API methods
const alias = await mailslurp.aliasController.createAlias(...args)

// or create a controller
const inboxController = mailslurp.inboxController
const inbox = await inboxController.createInbox()

// use Promises methods if you prefer
mailslurp.getEmails(inbox.id).then(emails => {
   // handle emails
   console.log(emails))
 }

Hierarchy

MailSlurp

Constructors

constructor

new MailSlurp(opts: Config): MailSlurp
Create a new MailSlurp instance.

Contains top level convenience functions. Access the full API controllers as properties on the instance.
```
const MailSlurp = require('mailslurp-client').default
const mailslurp = new MailSlurp({ apiKey })
```
Parameters
- opts: Config
Returns MailSlurp

Properties

Methods

createInbox

createInbox(emailAddress?: string, name?: string, description?: string, expiresAt?: Date, favourite?: boolean, tags?: string[], teamAccess?: boolean, expiresIn?: number, useDomainPool?: boolean, inboxType?: "HTTP_INBOX" | "SMTP_INBOX"): Promise<InboxDto>
Create a new inbox and with a randomized email address to send and receive from. Pass emailAddress parameter if you wish to use a specific email address. Creating an inbox is required before sending or receiving emails. If writing tests it is recommended that you create a new inbox during each test method so that it is unique and empty.

Summary
Create an Inbox (email address)
Parameters
- Optional emailAddress: string
  
  Optional email address including domain you wish inbox to use (eg: test123@mydomain.com). Only supports domains that you have registered and verified with MailSlurp using dashboard or `createDomain` method.
- Optional name: string
  
  Optional name for an inbox.
- Optional description: string
  
  Optional description for an inbox.
- Optional expiresAt: Date
  
  Optional expires at timestamp. If your plan supports this feature you can specify when an inbox should expire. If left empty inbox will exist permanently or expire when your plan dictates
- Optional favourite: boolean
  
  Is inbox favourited.
- Optional tags: string[]
  
  Optional tags for an inbox. Can be used for searching and filtering inboxes.
- Optional teamAccess: boolean
  
  Optional flag to allow team access to inbox.
- Optional expiresIn: number
  
  Optional number of milliseconds to expire inbox after.
- Optional useDomainPool: boolean
  
  Optional flag to use the MailSlurp domain pool for domain endings.
- Optional inboxType: "HTTP_INBOX" | "SMTP_INBOX"
  
  Optional inbox type HTTP or SMTP
Returns Promise<InboxDto>

createInboxWithOptions

createInboxWithOptions(createInboxOptions: CreateInboxDto): Promise<InboxDto>
Create an inbox using CreateInboxDto options. More convenient that createInbox in some cases.
Parameters
- createInboxOptions: CreateInboxDto
Returns Promise<InboxDto>

deleteEmail

deleteEmail(emailId: string): Promise<void>
Deletes an email and removes it from the inbox. Deleted emails cannot be recovered.

Summary
Delete an email
Parameters
- emailId: string
  
  emailId
Returns Promise<void>

deleteInbox

deleteInbox(inboxId: string): Promise<void>
Permanently delete an inbox and associated email address as well as all emails within the given inbox. This action cannot be undone. Note: deleting an inbox will not affect your account usage. Monthly inbox usage is based on how many inboxes you create within 30 days, not how many exist at time of request.

Summary
Delete inbox
Parameters
- inboxId: string
  
  inboxId
Returns Promise<void>

downloadAttachment

downloadAttachment(emailId: string, attachmentId: string): Promise<String>
Returns the specified attachment for a given email as a byte stream (file download). You can find attachment ids in email responses endpoint responses. The response type is application/octet-stream.

Summary
Get email attachment bytes
Parameters
- emailId: string
  
  emailId
- attachmentId: string
  
  attachmentId
Returns Promise<String>

emptyInbox

emptyInbox(inboxId: string): Promise<void>
Deletes all emails

Summary
Delete all emails in an inbox
Parameters
- inboxId: string
  
  inboxId
Returns Promise<void>

getAllEmails

getAllEmails(page?: number, size?: number, inboxId?: string[], sort?: SortEnum, unreadOnly?: boolean, searchFilter?: string): Promise<PageEmailProjection>
By default returns all emails across all inboxes sorted by ascending created at date. Responses are paginated. You can restrict results to a list of inbox IDs. You can also filter out read messages

Summary
Get all emails
Parameters
- Optional page: number
  
  Optional page index in email list pagination
- Optional size: number
  
  Optional page size in email list pagination
- Optional inboxId: string[]
  
  Optional inbox ids to filter by. Can be repeated. By default will use all inboxes belonging to your account.
- Optional sort: SortEnum
  
  Optional createdAt sort direction ASC or DESC
- Optional unreadOnly: boolean
  
  Optional filter for unread emails only. All emails are considered unread until they are viewed in the dashboard or requested directly
- Optional searchFilter: string
  
  Optional search filter
Returns Promise<PageEmailProjection>

getAllInboxes

getAllInboxes(page?: number, size?: number, favourite?: boolean, search?: string, sort?: SortEnum, tag?: string): Promise<PageInboxProjection>
List inboxes in paginated form. Allows for page index, page size, and sort direction. Can also filter by favourited or email address like pattern.

Summary
List Inboxes Paginated
Parameters
- Optional page: number
  
  Optional page index in inbox list pagination
- Optional size: number
  
  Optional page size in inbox list pagination
- Optional favourite: boolean
  
  Optionally filter results for favourites only
- Optional search: string
  
  Optionally filter by search words partial matching ID, tags, name, and email address
- Optional sort: SortEnum
  
  Optional createdAt sort direction ASC or DESC
- Optional tag: string
  
  Optionally filter by tag
Returns Promise<PageInboxProjection>

getAttachmentMetaData

getAttachmentMetaData(attachmentId: string, emailId: string): Promise<AttachmentMetaData>
Get attachment MetaData

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

Summary
Get email attachment metadata
Parameters
- attachmentId: string
  
  attachmentId
- emailId: string
  
  emailId
Returns Promise<AttachmentMetaData>

getEmail

getEmail(emailId: string): Promise<Email>
Returns an EmailDto object with headers and content. To retrieve the raw unparsed email use the getRawEmail endpoints

Summary
Get email content
Parameters
- emailId: string
  
  emailId
Returns Promise<Email>

getEmails

getEmails(inboxId: string, args?: GetMessagesOptions): Promise<EmailPreview[]>
List emails that an inbox has received. Only emails that are sent to the inbox's email address will appear in the inbox. It may take several seconds for any email you send to an inbox's email address to appear in the inbox. To make this endpoint wait for a minimum number of emails use the minCount parameter. The server will retry the inbox database until the minCount is satisfied or the retryTimeout is reached

Summary
Get emails in an Inbox
Parameters
- inboxId: string
  
  Id of inbox that emails belongs to
- args: GetMessagesOptions = {}
Returns Promise<EmailPreview[]>

getImapSmtpAccessDetails

getImapSmtpAccessDetails(inboxId?: string): Promise<ImapSmtpAccessDetails>
Parameters
- Optional inboxId: string
Returns Promise<ImapSmtpAccessDetails>

getInbox

getInbox(inboxId: string): Promise<InboxDto>
Returns an inbox's properties, including its email address and ID.

Summary
Get Inbox
Parameters
- inboxId: string
  
  inboxId
Returns Promise<InboxDto>

getInboxes

getInboxes(): Promise<InboxDto[]>
List the inboxes you have created

Summary
List Inboxes / Email Addresses

Returns Promise<InboxDto[]>

getRawEmail

getRawEmail(emailId: string): Promise<string>
Returns a raw, unparsed, and unprocessed email. If your client has issues processing the response it is likely due to the response content-type which is text/plain. If you need a JSON response content-type use the getRawEmailJson endpoint

Summary
Get raw email string
Parameters
- emailId: string
  
  emailId
Returns Promise<string>

sendEmail

sendEmail(inboxId: string, sendEmailOptions?: SendEmailOptions): Promise<SentEmailDto>
Send an email from an inbox's email address. The request body should contain the SendEmailOptions that include recipients, attachments, body etc. See SendEmailOptions for all available properties. Note the inboxId refers to the inbox's id not the inbox's email address. See https://www.mailslurp.com/guides/ for more information on how to send emails.

Summary
Send Email
Parameters
- inboxId: string
  
  ID of the inbox you want to send the email from
- Optional sendEmailOptions: SendEmailOptions
  
  Options for the email
Returns Promise<SentEmailDto>

uploadAttachment

uploadAttachment(options: UploadAttachmentOptions): Promise<String[]>
Upload an attachment for use in email sending. Attachment contents must be a base64 encoded string. When sending emails with attachments first upload each attachment with this endpoint. Record the returned attachment IDs. Then use these attachment IDs in the SendEmailOptions when sending an email. This means that attachments can easily be reused.

Summary
Upload an attachment for sending
Parameters
- options: UploadAttachmentOptions
Returns Promise<String[]>

waitForEmailCount

waitForEmailCount(count?: number, inboxId?: string, timeout?: number, unreadOnly?: boolean): Promise<EmailPreview[]>
If inbox contains count or more emails at time of request then return count worth of emails. If not wait until the count is reached and return those or return an error if timeout is exceeded.

Summary
Wait for and return count number of emails
Parameters
- Optional count: number
  
  Number of emails to wait for. Must be greater that 1
- Optional inboxId: string
  
  Id of the inbox we are fetching emails from
- Optional timeout: number
  
  Max milliseconds to wait
- Optional unreadOnly: boolean
  
  Optional filter for unread only
Returns Promise<EmailPreview[]>

waitForLatestEmail

waitForLatestEmail(inboxId?: string, timeout?: number, unreadOnly?: boolean): Promise<Email>
Will return either the last received email or wait for an email to arrive and return that. If you need to wait for an email for a non-empty inbox see the other receive methods such as waitForNthEmail or waitForEmailCount.

Summary
Fetch inbox's latest email or if empty wait for an email to arrive
Parameters
- Optional inboxId: string
  
  Id of the inbox we are fetching emails from
- Optional timeout: number
  
  Max milliseconds to wait
- Optional unreadOnly: boolean
  
  Optional filter for unread only
Returns Promise<Email>

waitForMatchingEmails

waitForMatchingEmails(matchOptions: MatchOptions, count?: number, inboxId?: string, timeout?: number, unreadOnly?: boolean): Promise<EmailPreview[]>
Perform a search of emails in an inbox with the given patterns. If results match expected count then return or else retry the search until results are found or timeout is reached. Match options allow simple CONTAINS or EQUALS filtering on SUBJECT, TO, BCC, CC, and FROM. See the MatchOptions object for options.

Summary
Wait or return list of emails that match simple matching patterns
Parameters
- matchOptions: MatchOptions
  
  matchOptions
- Optional count: number
  
  Number of emails to wait for. Must be greater that 1
- Optional inboxId: string
  
  Id of the inbox we are fetching emails from
- Optional timeout: number
  
  Max milliseconds to wait
- Optional unreadOnly: boolean
  
  Optional filter for unread only
Returns Promise<EmailPreview[]>

waitForNthEmail

waitForNthEmail(inboxId?: string, index?: number, timeout?: number, unreadOnly?: boolean): Promise<Email>
If nth email is already present in inbox then return it. If not hold the connection open until timeout expires or the nth email is received and returned.

Summary
Wait for or fetch the email with a given index in the inbox specified
Parameters
- Optional inboxId: string
  
  Id of the inbox you are fetching emails from
- Optional index: number
  
  Zero based index of the email to wait for. If an inbox has 1 email already and you want to wait for the 2nd email pass index=1
- Optional timeout: number
  
  Max milliseconds to wait for the nth email if not already present
- Optional unreadOnly: boolean
  
  Optional filter for unread only
Returns Promise<Email>

Class MailSlurp

Create instance

Call methods

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

opts: Config

Returns MailSlurp

Properties

Readonly aliasController

Readonly attachmentController

Readonly bounceController

Readonly bulkController

Readonly commonController

Readonly contactController

Readonly domainController

Readonly emailController

Readonly emailVerificationController

Readonly formController

Readonly groupController

Readonly inboxController

Readonly inboxForwarderController

Readonly inboxReplierController

Readonly inboxRulesetController

Readonly mailServerController

Readonly missedEmailController

Readonly phoneController

Readonly sentController

Readonly smsController

Readonly templateController

Readonly trackingController

Readonly userController

Readonly waitController

Readonly webhookController

Methods

createInbox

Summary

Parameters

Optional emailAddress: string

Optional name: string

Optional description: string

Optional expiresAt: Date

Optional favourite: boolean

Optional tags: string[]

Optional teamAccess: boolean

Optional expiresIn: number

Optional useDomainPool: boolean

Optional inboxType: "HTTP_INBOX" | "SMTP_INBOX"

Returns Promise<InboxDto>

createInboxWithOptions

Parameters

createInboxOptions: CreateInboxDto

Returns Promise<InboxDto>

deleteEmail

Summary

Parameters

emailId: string

Returns Promise<void>

deleteInbox

Summary

Parameters

inboxId: string

Returns Promise<void>

downloadAttachment

Summary

Parameters

emailId: string

attachmentId: string

Returns Promise<String>

emptyInbox

Summary

Parameters

inboxId: string

Returns Promise<void>

getAllEmails

`Readonly` aliasController

`Readonly` attachmentController

`Readonly` bounceController

`Readonly` bulkController

`Readonly` commonController

`Readonly` contactController

`Readonly` domainController

`Readonly` emailController

`Readonly` emailVerificationController

`Readonly` formController

`Readonly` groupController

`Readonly` inboxController

`Readonly` inboxForwarderController

`Readonly` inboxReplierController

`Readonly` inboxRulesetController

`Readonly` mailServerController

`Readonly` missedEmailController

`Readonly` phoneController

`Readonly` sentController

`Readonly` smsController

`Readonly` templateController

`Readonly` trackingController

`Readonly` userController

`Readonly` waitController

`Readonly` webhookController

`Optional` emailAddress: string

`Optional` name: string

`Optional` description: string

`Optional` expiresAt: Date

`Optional` favourite: boolean

`Optional` tags: string[]

`Optional` teamAccess: boolean

`Optional` expiresIn: number

`Optional` useDomainPool: boolean

`Optional` inboxType: "HTTP_INBOX" | "SMTP_INBOX"

`Optional` page: number

`Optional` size: number

`Optional` inboxId: string[]

`Optional` sort: SortEnum

`Optional` unreadOnly: boolean

`Optional` searchFilter: string

`Optional` page: number

`Optional` size: number

`Optional` favourite: boolean

`Optional` search: string

`Optional` sort: SortEnum

`Optional` tag: string

`Optional` inboxId: string

`Optional` sendEmailOptions: SendEmailOptions

`Optional` count: number

`Optional` inboxId: string

`Optional` timeout: number