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'
})

Call methods

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

  • 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

    Returns MailSlurp

Properties

aliasController: AliasControllerApi
attachmentController: AttachmentControllerApi
bounceController: BounceControllerApi
bulkController: BulkActionsControllerApi
commonController: CommonActionsControllerApi
contactController: ContactControllerApi
domainController: DomainControllerApi
emailController: EmailControllerApi
emailVerificationController: EmailVerificationControllerApi
formController: FormControllerApi
groupController: GroupControllerApi
inboxController: InboxControllerApi
inboxForwarderController: InboxForwarderControllerApi
inboxReplierController: InboxReplierControllerApi
inboxRulesetController: InboxRulesetControllerApi
mailServerController: MailServerControllerApi
missedEmailController: MissedEmailControllerApi
phoneController: PhoneControllerApi
sentController: SentEmailsControllerApi
smsController: SmsControllerApi
templateController: TemplateControllerApi
trackingController: TrackingControllerApi
userController: UserControllerApi
waitController: WaitForControllerApi
webhookController: WebhookControllerApi

Methods

  • 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>

  • 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>

  • 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>

  • 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>

  • Deletes all emails

    Summary

    Delete all emails in an inbox

    Parameters

    • inboxId: string

      inboxId

    Returns Promise<void>

  • 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>

  • 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>

  • 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>

  • 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>

  • 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

    Returns Promise<EmailPreview[]>

  • Returns an inbox's properties, including its email address and ID.

    Summary

    Get Inbox

    Parameters

    • inboxId: string

      inboxId

    Returns Promise<InboxDto>

  • 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>

  • 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>

  • 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

    Returns Promise<String[]>

  • 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[]>

  • 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>

  • 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[]>

  • 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>