How to test email and SMS with JavaScript

Using Cypress, Playwright, WebdriverIO or similar?

This guide shows how to perform email and SMS testing within a web browser session, but Mailosaur has an official Node.js library and Cypress plugin which we are strongly recommended for most testing cases.

You should also check out our specific guides for Cypress, Playwright, and WebdriverIO users.

However, if you have a specific case where you can only test in-browser read on.

Introducing Mailosaur.js

Mailosaur.js is the official client-side JavaScript library for testing email and SMS messages with Mailosaur.

It’s perfect when you’re using tools like Ghost Inspector that run fully client-side.

1. Create a Mailosaur account

If you already have an account, skip to step 2.

To create a new trial account, sign up here.

2. Verify the domain you intend to run your tests from

To protect your security, we only allow API calls to be made in a web browser from domains that you have verified.

For example, if you are running your JavaScript code at your-website.com, then we need to know that you own your-website.com before your tests will work.

You must first verify your website or web app’s domain name. To do this, go to the Domains section of the Mailosaur Dashboard, and follow the on-screen instructions to add a new verified domain. Learn more about.

3. Send email to your Mailosaur server

Servers allow you to group tests, permissions, and other settings together. Each server has a Server ID, a domain name. You need these values to both send email to Mailosaur, and to set up automated testing.

You also need an API key to use. You can learn more about creating API keys here.

Retrieve your server’s attributes

1. Go to the Servers page in the Mailosaur Dashboard.
2. Click on the name of the server you want to test with.
3. Click on the API tab.
4. Make a note of the Server ID, domain name and API key.

Send an email to your server

If the domain name of your server above was:

example.mailosaur.net

Then you can send an email to it with these steps:

1. Open up an email client and send an email to anything@example.mailosaur.net
2. Go to the Servers page in the Mailosaur Dashboard.
3. Click on the name of the server you sent an email to.
4. Confirm the email is there. Note that some services (like Gmail) may take 10-20 seconds to send a message through.

To learn more, read our guide on sending email to Mailosaur.

4. Initialize Mailosaur.js

Once you have verified the domain you want to test from, you can run the following code to activate the Mailosaur API within your web browser:

(function (e, m, a, i, l) {
  i = e.createElement(m), l = e.getElementsByTagName(m)[0];
  i.async = 1; i.src = a; e.body.appendChild(i)
})(document, 'script', 'https://mailosaur.com/v1/mailosaur.js');

5. Find an email for automated testing

Now that you have Mailosaur.js ready, your server’s credentials to hand, and an email to test, then you’re ready to continue.

To fetch your message, type or paste in this code sample to your browser, replacing the template code with the values from step 3 above:

(async() => {
  const apiKey = 'YOUR_API_KEY'
  const serverId = 'SERVER_ID'
  const serverDomain = 'SERVER_DOMAIN'

  const mailosaur = Mailosaur(apiKey);

  const message = await mailosaur.messages.get(serverId, {
    sentTo: 'anything@' + serverDomain
  });

  console.log(`Subject: ${message.subject}`);
})();

This code connects to Mailosaur and looks for any email that has been sent to the address provided in the search criteria.

If everything is set up correctly, you should see the subject line of the last email you sent, printed to screen:

Subject: My example email

Troubleshooting

If you see an error, e.g. ‘No matching messages found in time’:

• Make sure you have set the sent to address correctly in your code.
• Ensure that you have sent an email to the sent to address (check this is visible in the Mailosaur Dashboard).
• Note that by default, the get method will only look for messages that were received by Mailosaur within the last hour. You can override this using the receivedAfter option (see library reference below).

6. Narrowing your search results

Only find messages received after a certain time

By default, searchs include messages received in the last hour, but you can customise the search window with the receivedAfter option.

This example shows you how to only include emails received after your test started:

const testStart = new Date();

// Perform the steps that send a message here

const message = await mailosaur.messages.get('SERVER_ID', {
  sentTo: '...'
}, {
  receivedAfter: testStart
});

Search criteria

As you can see in the examples so far, you can search for the email address or phone number a message was sent to, but you can also search using this criteria too:

7. Start writing tests

Now that you have a working project that fetches an email, you can use this to begin writing tests for various pieces of functionality.

Check out these guides on the most common test cases:

SMS Testing

You can test SMS messages in much the same way as email. Take a look at our guide on testing SMS messages for more information.

Library reference

The Node.js client library gives you access to several other methods.

Messages

Messages is the collective name given to the email and/or SMS messages that are sent into Mailosaur for testing. The message object contains everything you need to perform in-depth automated testing.

messages.get(server, criteria, options)

Waits for a message to be found. Returns as soon as a message matching the specified search criteria is found.

Recommended: This is the most efficient method of looking up a message, therefore we recommend using it wherever possible.

const message = await mailosaur.messages.get('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
});

To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.

Criteria

Options

const message = await mailosaur.messages.get('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}, {
  // Search all messages received after midnight 5th Feb 2020
  receivedAfter: new Date(2020, 1, 5)
});

messages.list(server, options)

Returns a list of your messages in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first.

// List the most recent messages
const result = await mailosaur.messages.list('SERVER_ID');

// Get the most recent message (the first one in the list)
const message = result.items[0];

console.log('Subject:', message.subject);

Options

• receivedAfter Allows you to customise how far back to look for messages.
• page Used alongside itemsPerPage to paginate through results. This is zero-based, meaning 0 is the first page of results.
• itemsPerPage A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50.
• dir Optionally limits results based on the direction (Sent or Received), with the default being Received.

// List all results received after midnight on 3rd Feb 2020
const result = await mailosaur.messages.list('SERVER_ID', {
  page: 0,
  itemsPerPage: 10,
  receivedAfter: new Date(2020, 1, 3)
});

messages.search(server, criteria, options)

Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.

const result = await mailosaur.messages.search('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
});

// Get the most recent match
const message = result.items[0];

console.log('Subject:', message.subject);

Criteria

Options

// Search for all messages sent to someone@SERVER_ID.mailosaur.net,
// received after midnight on 3rd Feb 2020. Limit results to
// the first 10 matches only.
const result = await mailosaur.messages.search('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}, {
  page: 0,
  itemsPerPage: 10,
  receivedAfter: new Date(2020, 1, 3)
});

messages.getById(id)

Retrieves the detail for a single email message. Must be used in conjunction with either ```list``` or ```search``` in order to get the unique identifier for the required message. We always recommend using the ```get``` method instead.

const result = await mailosaur.messages.list('SERVER_ID');
const messageId = result.items[0].id;

const message = await mailosaur.messages.getById(messageId);

console.log('Subject:', message.subject);

messages.del(id)

Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.

await mailosaur.messages.del(messageId)

messages.deleteAll(server)

Permanently deletes all messages held by the specified server. Also deletes any attachments related to each message. This operation cannot be undone.

await mailosaur.messages.deleteAll('SERVER_ID')

messages.create(server, messageCreateOptions)

Creates a new message that can be sent to a verified email address. This is useful in scenarios where you want an email to trigger a workflow in your product.

await mailosaur.messages.create('SERVER_ID', {
  to: 'verified-address@example.com',
  send: true,
  subject: 'Request',
  text: 'Please can you give us a call back?'
})

Options

• to The email address to which the email will be sent. Must be a verified email address.
• send If true, email will be sent upon creation.
• subject The email subject line.
• text The plain text body of the email.
• html The HTML body of the email.

messages.forward(messageId, messageForwardOptions)

Forwards the specified email to a verified email address.

await mailosaur.messages.forward('MESSAGE_ID', {
  to: 'verified-address@example.com',
  text: 'FYI'
})

Options

• to The email address to which the email will be sent. Must be a verified email address.
• text Any additional HTML content to forward the email with.
• html Any additional plain text content to forward the email with.

messages.reply(messageId, messageReplyOptions)

Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails.

await mailosaur.messages.reply('MESSAGE_ID', {
  text: 'FYI'
})

Options

• text Any additional plain text content to include in the reply.
• html Any additional HTML content to include in the reply.

Servers

Servers contain all the configuration and set up for.

servers.list()

Returns a list of your virtual servers. Servers are returned sorted in alphabetical order.

const result = mailosaur.servers.list();

console.log('You have a server called:', result.items[0].name);

servers.create(server)

Creates a new virtual server. Only the name property is required to create a new server via the API.

await mailosaur.servers.create({
  name: 'My email tests'
});

servers.get(id)

Retrieves the detail for a single server. Simply supply the unique identifier for the required server.

const server = await mailosaur.servers.get('SERVER_ID');

servers.getPassword(id)

Retrieves the password, for use with SMTP and POP3, for a single server. Simply supply the unique identifier for the required server.

const password = await mailosaur.servers.getPassword('SERVER_ID');

servers.update(id, server)

Updates a single server.

await mailosaur.servers.update('SERVER_ID', {
  name: 'Updated server name'
});

servers.del(id)

Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.

await mailosaur.servers.del('SERVER_ID');

servers.generateEmailAddress(id)

Utility method to help you generate a random email address for a given server.

const emailAddress = mailosaur.servers.generateEmailAddress('SERVER_ID');

console.log(emailAddress); // "bgwqj@SERVER_ID.mailosaur.net"

To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.

Files

files.getEmail(messageId)

Downloads an EML file representing the specified email. Simply supply the unique identifier for the required email.

files.getAttachment(attachmentId)

Downloads a single attachment. Simply supply the unique identifier for the required attachment.

Analysis

analysis.spam(messageId)

Perform spam testing on the specified email.

Usage

usage.limits()

Retrieve account usage limits. Details the current limits and usage for your account. This endpoint requires authentication with an account-level API key.

usage.transactions()

Retrieves the last 31 days of transactional usage. This endpoint requires authentication with an account-level API key.