The Mailosaur Developer Hub

Welcome to the Mailosaur developer hub. You'll find comprehensive guides and documentation to help you start working with Mailosaur as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Email testing

Learn how to automate email testing in Node.js.

Before you start

If you don't already have one, create a Mailosaur account.

Make sure you know how to send email to Mailosaur first. Once you have this working, you're ready to start testing!


Are you using Cypress?

Be sure to check out our guide to testing email with Cypress.

Installing Mailosaur

Mailosaur provides an official Node.js client library to make testing email in Node.js a lot easier.

Install via npm:

npm install mailosaur --save-dev

Authenticating with Mailosaur

In order to connect to Mailosaur, you need to add your API key to your tests. You access your API key via the account settings screen.

Retrieving an email

Once you have sent an email to test, for example by emailing something.{SERVER_ID}, you can now use the code below to retrieve the message in Node.js:

// 1. Import Mailosaur and create an instance of the MailosaurClient, using your API key
const MailosaurClient = require('mailosaur')
const client = new MailosaurClient('{API_KEY}')

// 2. Wait for the message (by default only looks for messages received in the last hour)
const message = await client.messages.get('{SERVER_ID}', {
    sentTo: 'something.{SERVER_ID}'

// 3. Assert that the email subject is what we expect
expect(message.subject).to.equal('Reset your password')

Following links from an email

Mailosaur extracts any links found within both the HTML and text content of an email. These are then made available via message.html.links and message.text.links.

You can use these links for many scenarios, such as completing a password reset process:

// Wait for the message
const message = await client.messages.get('{SERVER_ID}', {
    sentTo: 'something.{SERVER_ID}'

// Check that we have the password reset email
expect(message.subject).to.equal('Reset your password')

// Store the password reset link (e.g. to use in a test that completes the process)
const passwordResetLink = message.text.links[0].href;

Extracting content from email HTML

If you need to extract content from the body of an email, such as a verification code, then you can use a library in your tests.

Let's imagine that message.html.body contains:

  <h1>To activate your account, enter this code:</h1>
  <p class="verify-code">542163</p>

To work with the email's HTML, install jsdom via npm:

npm install jsdom --save-dev

Import jsdom at the top of your test file:

const { JSDOM } = require('jsdom')

Now, you can extract the verification code as follows:

// Wait for the message
const message = await client.messages.get('{SERVER_ID}', {
    sentTo: 'something.{SERVER_ID}'

// Extract the verification code from HTML
const dom = new JSDOM(message.body.html);
const el = dom.window.document.querySelector('.verify-code');
const verificationCode = el.textContent;


Updated about a month ago

Email testing

Learn how to automate email testing in Node.js.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.