Skip to content
📫 MailSlurp is an API for send and receiving real emails in code.
TypeScript JavaScript Makefile
Branch: master
Clone or download
Jack Mahoney
Jack Mahoney add changelog
Latest commit 0af574d Sep 18, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
dist
docs
.gitignore
CHANGELOG.md
LICENSE v4 Aug 27, 2019
Makefile
README.md
index.ts
integration.spec.ts
jest.config.js
package-lock.json
package.json add docs Sep 18, 2019
tsconfig.json fix readme Sep 9, 2019
typedoc.json

README.md

Vue logo

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.

For more integrations see mailslurp.com

Documentation

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

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)

More information

See mailslurp.com for all information.

License

MIT License

You can’t perform that action at this time.