Documentation

Introduction

MailSlurp is a free API for sending and receiving emails from applications or tests. It is designed as a simpler, more powerful interface for SMTP mail servers.

This repository hosts the recommended MailSlurp client. MailSlurp can also be used as a REST API or with officially supported clients in Javascript, Ruby, Python, PHP, Java, C#, Go and more.

Installing

npm install --save mailslurp-client

Configuration

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

🔑 Note: All requests require an API Key. Get yours free via the MailSlurp Dashboard

Documentation

Please see generated method documentation for this repository or view the developers page.

Questions

Please reach out any time using live chat or email.

Issues

For anything related to this client please open an issue. For all other issues please contact support.

Examples

📫 Creating email addresses

MailSlurp uses the concept of an inbox. Inboxes have IDs and email addresses. If you want to receive emails you'll need to create an inbox first.

const { id, emailAddress } = await mailslurp.createInbox()
// or if you prefer
const { id, emailAddress } = await mailslurp.createNewEmailAddress()

📤 Sending emails

You can send real emails with MailSlurp. If you don't care what address it is sent from use the sendEmailSimple method. This will send emails from a random MailSlurp address.

mailslurp.sendEmailSimple({ to: ['recipient@domain.com'], body: '', subject: '' })

If you want to send email from a specific address, first create an inbox. Then use that inbox's ID to send emails.

mailslurp.sendEmail(inbox.id, { to: ['recipient@domain.com'], ...otherOptions })

For a full list of email sending options see the documentation. If you wish to send from custom domains see the pricing page.

To send attachments first upload each attachment you wish to send.

const [id] = await mailslurp.uploadAttachment({
    base64Contents: 'base64-encoded-file-contents',
    contentType: "optional/content-type",
    filename: "optional-filename"
})

Then use the returned attachment IDs in the attachments field of the send email options.

📥 Receiving emails

MailSlurp is an asynchronous service. That means certain API calls will wait until a condition is met. This saves you from having to poll the API. (Webhooks are also available).

To receive an email first make sure you have an inbox with an email address. Then send an email to that address with any service (including MailSlurp itself). Now you can wait for the email to arrive.

let email = await mailslurp.waitForLatestEmail(inbox.id)

// other methods
email = await mailslurp.waitForNthEmail(inbox.id, index)
const emails = await mailslurp.waitForEmailCount(count, inbox.id)

⚠️ Note: MailSlurp will return immediately if the inbox already contains an email.

For more control over email fetching use the getEmails methods. MailSlurp will hang the connection until all conditions are met or the timeout is exceeded.

// get a list of matching emails in preview form
const emailPreviews = await mailslurp.getEmails(inbox.id, {
    minCount: 2, // wait until 2 emails present
    retryTimeout: 60000 // max milliseconds to wait
})
// then get the email you want in full form
const email = await mailslurp.getEmail(emailPreviews[0].id)

🔍 Searching emails

MailSlurp has simple email matching features that let you wait for an email that matches a particular subject, recipient or more.

const matchOptions = {
  matches: [
    {
      field: 'SUBJECT',
      should: 'CONTAIN',
      value: 'Welcome to my company'
    }
  ]
};
await mailslurp.waitForMatchingEmails(matchOptions, 1, inbox.id, 5000);

For more information on email matching see the documentation.

📭 Deleting entities

You can empty an inbox easily with:

await mailslurp.emptyInbox(inbox.id)

You can also delete emails individually:

await mailslurp.deleteEmail(email.id)

Paid features

MailSlurp is free for personal use but paid memberships gain access to many powerful features. These include

• Custom domains
• Unlimited usage
• Webhook notifications
• UI Web Interface
• Custom feature requests
• Rapid support

To arrange a call or to see all paid features checkout the pricing page.

More information

See mailslurp.com for all information.

License

MIT License