<h2 id="0-what-is-selenium"><a class="flex items-center group text-black hover:text-black" href="#0-what-is-selenium">What is Selenium?<div class="inline-block ml-2 align-middle w-3.5 h-3.5 opacity-0 transition-opacity group-hover:opacity-100"><img class="lazy" data-src="/images/icons/hashtag-regular.svg" height="18" width="18" alt="A hashtag icon"></div></a></h2>
<p>Selenium is a hugely popular open-source tool that automates web browsers.</p>
<p>If you’ve never heard about Selenium, we’d recommend checking out the the <a href="https://www.selenium.dev">Selenium website</a>.</p>
<h2 id="0-what-is-mailosaur"><a class="flex items-center group text-black hover:text-black" href="#0-what-is-mailosaur">What is Mailosaur?<div class="inline-block ml-2 align-middle w-3.5 h-3.5 opacity-0 transition-opacity group-hover:opacity-100"><img class="lazy" data-src="/images/icons/hashtag-regular.svg" height="18" width="18" alt="A hashtag icon"></div></a></h2>
<p>Mailosaur is a service that captures email and SMS messages and lets you test them, via it’s web dashboard and the Mailosaur email/SMS testing API.</p>
<p>If you don’t already have one, <a href="/app/signup">create a free account trial</a> now, and <a href="/docs/email-testing/sending-to-mailosaur">send an email into Mailosaur</a> first. Once you have this working, you’re ready to start testing!</p>
<h2 id="0-1-create-an-api-key"><a class="flex items-center group text-black hover:text-black" href="#0-1-create-an-api-key">1. Create an API key<div class="inline-block ml-2 align-middle w-3.5 h-3.5 opacity-0 transition-opacity group-hover:opacity-100"><img class="lazy" data-src="/images/icons/hashtag-regular.svg" height="18" width="18" alt="A hashtag icon"></div></a></h2>
<p>Account-level API keys allow you to access all the functions described in the <a href="/docs/api">API reference</a>, and have access to all the servers in your account.</p>
<p>To create an account-level API key, you must be an Administrator or Account Owner on the account in question.</p>
<ol>
<li>Go to the <strong>Settings</strong> page in the Mailosaur Dashboard.</li>
<li>Go to the <strong>API Keys</strong> page.</li>
<li>Click the <strong>Create a Key</strong> button.</li>
<li>In the dialog that appears, enter a name for your key.</li>
<li>When you are finished, click <strong>Create</strong>.</li>
</ol>
<p>For more information, see our guide on <a href="/docs/managing-your-account/api-keys">managing API keys</a>.</p>
<h2 id="0-2-use-the-guide-for-your-programming-language"><a class="flex items-center group text-black hover:text-black" href="#0-2-use-the-guide-for-your-programming-language">2. Use the guide for your programming language<div class="inline-block ml-2 align-middle w-3.5 h-3.5 opacity-0 transition-opacity group-hover:opacity-100"><img class="lazy" data-src="/images/icons/hashtag-regular.svg" height="18" width="18" alt="A hashtag icon"></div></a></h2>
<p>Selenium supports various languages. To begin integrating email and SMS into your Selenium tests, just follow the step-by-step guide for the language that applies to your Selenium setup:</p>
<ul>
<li><a href="/docs/languages/java#0-3-send-email-to-your-mailosaur-server">Java</a></li>
<li><a href="/docs/languages/python#0-3-send-email-to-your-mailosaur-server">Python</a></li>
<li><a href="/docs/languages/dotnet#0-3-send-email-to-your-mailosaur-server">C#</a></li>
<li><a href="/docs/languages/ruby#0-3-send-email-to-your-mailosaur-server">Ruby</a></li>
<li><a href="/docs/languages/nodejs#0-3-send-email-to-your-mailosaur-server">Node.js</a></li>
</ul>

Mailosaur

Twitter

GitHub

YouTube

Instagram

This article shows you how to test email and test SMS using Selenium and the Mailosaur API.

How to test email and SMS with Selenium

<p>This article shows you how to test email and test SMS using Selenium and the Mailosaur API.</p>

<h1>How to test email and SMS with Selenium</h1>

Before you begin

If you don’t already have one, create a Mailosaur account.
You will also need to choose what server you want to send email to. Servers allow you to group tests together (for example, by project, environment, team, etc.)

Test email addresses
When developing and testing products, you will often need a set of throwaway email addresses to test features, workflows, and email content itself.
Every Mailosaur plan provides an unlimited number of fully-functional email addresses to test with.
How do I create test email addresses?
You don’t need to create email addresses. Instead, every server within your account has its own, unique domain name, and any email sent to this domain will be captured.
For example, if your server had the domain abcd1234.mailosaur.net, then every one of these email addresses will work, with no setup required:
# Using build numbers
build-56@abcd1234.mailosaur.net
build-58@abcd1234.mailosaur.net

# Using random user names
jill.doe@abcd1234.mailosaur.net
jack.smith@abcd1234.mailosaur.net

# Using a random string
405fca91@abcd1234.mailosaur.net
You can make up an email address pattern that works your needs. However, if you just want a random address each time, Mailosaur’s client libraries each provide a helper method to generate one for you.
You can use these addresses in the same way you would any other email address.
Locating the domain name for a server
You can locate the domain name of a server by following these steps:

Go to the Servers page in the Mailosaur Dashboard.
Click on a server.
In the page that appears, the server domain is shown in the top-right corner of the screen.

Sending directly via SMTP
Every Mailosaur server is a full featured virtual email server. This means that instead of using test email addresses, you can point your product directly to your server via SMTP.
This is useful in cases where you want to prevent staging environments from sending email to real customers.
It is also a great way of reducing development costs, as you do not need to pay to send test emails via your regular Email Service Provider (ESP) on staging environments.
Check out our guide on testing directly via SMTP.

Discover efficient test email software with Mailosaur. Learn to send test emails seamlessly, create throwaway addresses, and use SMTP directly. Enhance your development process and cut costs.

Sending test email to Mailosaur

Teams often need to forward emails onto an email address outside of Mailosaur. For example, to send messages to colleagues for further review/analysis, or to test email handling functionality within an product.
You can forward messages from your Mailosaur account to external email addresses either one-by-one, or via the creation of automated forwarding rules.
Before you can forward messages, you must first verify external email addresses so that you can send email to them.
Forwarding individual emails
You can forward emails within the Mailosaur Dashboard, or via the API:## Forwarding rules
Forwarding rules allow messages to be automatically forwarded based on a set of criteria that you can configure, per server.
This feature is only available on our Business, Professional and Enterprise plans.
When a message is received by Mailosaur the forwarding rules are checked and, if there is a match, the message will automatically be sent to the email addresses specified in the rule.
With forwarding rules, messages are forwarded without alteration, to give an accurate representation of how they were received by Mailosaur.
Creating forwarding rules
Forwarding rules can be setup for any server, by following these steps:### Deleting forwarding rules
Once a forwarding rule is deleted, no further messages will be forwarded. Rules cannot be restored once they are deleted, and would have to be created again.

Learn how to forward individual emails as well as setting up automatic forwarding rules to send emails outside of Mailosaur.

Forwarding email

If your product is capable of handling email replies from your customers, you can use Mailosaur’s reply feature to simulate such a scenario.
When you reply, the email is obviously sent back to the email address it was originally sent to Mailosaur from. Before you can reply, you must first add this address as a verified external email address.
Replying to a test email
You can reply to emails within the Mailosaur Dashboard, or via the API:## Attachments
You can include attachments in replies requested via the API, by including an array of base64-encoded attachment objects:The content property of an attachment should be the base64-encoded content of the file you want to attach. Here’s an example of how to base64-encode a file:

Improve your email testing with Mailosaur&#39;s reply function. Simulate user responses seamlessly, enhancing your product&#39;s capabilities.

Replying to email

If your product is capable of handling inbound emails, you can use Mailosaur’s sending feature to trigger this functionality in your product.
Sending an email to start a test
You can send emails within the Mailosaur Dashboard, or via the API:## Attachments
You can include attachments in emails sent via the API, by including an array of base64-encoded attachment objects:The content property of an attachment should be the base64-encoded content of the file you want to attach. Here’s an example of how to base64-encode a file:

Simulate test email sending with Mailosaur&#39;s feature to trigger functionality in your product. Send test emails via the Dashboard or API, including attachments. 

Sending email out from Mailosaur

Overview
When testing email with Mailosaur, you can generate Email Previews to see what your creation looks like in various, real email clients, on different devices. However, if you need to interact with email in real-time, within an email client or other service, you can connect using POP3.
What is POP3?
POP3 is one of the most common ways for a computer program (e.g. an email client) to connect to an email server and retrieve email.
A recipient or their email client can download mail periodically from the server using POP3. As POP3 is a one-way system, when you an email is received, it remains held on the email server by default.
How do I connect to my Mailosaur server with POP3?
Every Mailosaur server has a unique set of POP3 credentials, which you can find within the Mailosaur Dashboard:

Log into the Mailosaur Dashboard.
Navigate to the server you want to connect to.
Click the Settings button
Select Fetch via POP3.
Copy the credentials from this screen.

You can then use these credentials with any email client or service that supports POP3.

est emails in real-time by connecting to your Mailosaur server with POP3. Retrieve and interact with emails using popular email clients.

Testing with POP3

The benefits of testing with SMTP
Whilst you can always use your server’s wildcard domain to create an unlimited number of email addresses, it is sometimes better to just send directly to Mailosaur via SMTP.
Cheaper than sending via your Email Service Provider (ESP)
If you have thousands of emails to test each day, sending these via your usual ESP (e.g. SendGrid or Amazon SES) can be unnecessarily expensive, as you’ll pay for each email you send, regardless of whether it is simply for testing purposes or not.
Sending lots of test emails via your email service provider can also be slow, as ESPs will often queue up emails and send them out in batches.
Prevent development and staging environments sending to real customers
When connecting directly to Mailosaur, every email you send is captured, regardless of who the email is sent “to”. This is great for protecting yourself from accidentally sending emails to real customers.
Where do I find my SMTP credentials?
Each server has a unique username and password usable for SMTP. To get this:

Log into the Mailosaur Dashboard.
Navigate to the server you want to use.
Click the Settings button
Select Send via SMTP.
Copy the credentials from this screen.

How do I send via SMTP?
You can use these code snippets to conditionally send directly to Mailosaur in your development and/or staging environments:

Efficiently test your product&#39;s emails with Mailosaur&#39;s dummy/ virtual SMTP. Save costs, prevent unintended customer emails, and easily find SMTP credentials in the Mailosaur Dashboard. 

Testing with SMTP

What is Cypress?
Cypress is an end-to-end testing framework that has won over developers and testers for its ease of use and flexibility. To use Cypress for your browser test automation, you’ll need to write your tests in JavaScript. Once your code is ready, you’ll be able to repeatedly run test cases using a real browser.
What makes Cypress unique is its batteries-included approach: all the tools required for end-to-end testing are already part of the Cypress framework, and there’s no need for anything extra. Fewer tools to install means faster setup and more time to write tests. Because Cypress’s components are well-integrated, its tests are usually more stable than end-to-end tests using other frameworks.
What is Mailosaur?
Mailosaur is a testing suite that lets you automate email testing with Cypress and other testing frameworks. This is important for websites and web apps that send email (password resets, account setup, marketing emails, etc.). Mailosaur also lets you test SMS messages with Cypress too!
If you don’t already have one, you’ll need to create a free trial account. Once you’re in, just familiarize yourself with sending email into Mailosaur and you’ll be ready to start testing!
Install the Mailosaur plugin
Mailosaur provides an official set of custom commands that let you easily automate email testing in Cypress.
Extend Cypress by installing Mailosaur’s custom commands package: cypress-mailosaur.
1. Install the plugin via npm
npm install cypress-mailosaur
2. Import Mailosaur into your Cypress project
Once installed, open cypress/support/e2e.js in your project folder, and add the following line of code to it:
import "cypress-mailosaur";
Note: In older versions of Cypress, the file may be called cypress/support/index.js.
3. Configure your API key
In order to connect to Mailosaur, you need to add an API key to your tests. You access your API key via in the account settings area.
Add your Mailosaur API key to cypress.config.js, in your project folder:
module.exports = defineConfig({
  env: {
    MAILOSAUR_API_KEY: "your-key-here",
  },

  // ...
});
Note: We strongly recommend against storing API keys in source control. Therefore you can also set your API key using the environment variable CYPRESS_MAILOSAUR_API_KEY.
Basic usage
The mailosaurGetMessage command automatically waits for the first email to arrive that matches the search criteria you provide.
cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "anything@SERVER_ID.mailosaur.net",
}).then((email) =&gt; {
  cy.log(email.subject);
});
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
This example searches for the email address a message was sent to, but you can also search using any of this criteria too:



PARAMETER
DESCRIPTION



sentTo
The full email address to which the target message was sent.


sentFrom
The full email address from which the target message was sent.


subject
Find emails where the subject line contains this text.


body
Finds messages where the message body contains this text.


The mailosaurGetMessage command returns the message object, which contains everything you need to perform in-depth automated testing.
Increasing the wait time
By default, the mailosaurGetMessage command will wait for 10 seconds for a matching message to arrive. You can increase this wait time by using the timeout option:
cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "anything@SERVER_ID.mailosaur.net",
}, {
  timeout: 20000, // 20 seconds (in milliseconds)
}).then((email) =&gt; {
  cy.log(email.subject);
});
Searching for older messages
By default, the mailosaurGetMessage command will only find messages received in the last hour. You can change this by setting the receivedAfter option.
const testStart = new Date();

// TODO Do something here to send an email into your account

// Find any email received after `testStart` was set
cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "anything@SERVER_ID.mailosaur.net",
}, {
  receivedAfter: testStart,
}).then((email) =&gt; {
  cy.log(email.subject);
});
Test email addresses
Because Mailosaur email addresses use a wildcard pattern, all plans give you access to unlimited test email addresses. Any address ending @YOUR_SERVER_ID.mailosaur.net will work.
You can use your own logic to make up an email address, or use the mailosaurGenerateEmailAddress helper method to generate a random string for you:
cy.mailosaurGenerateEmailAddress("SERVER_ID").then((emailAddress) =&gt; {
  cy.log(emailAddress); // "bgwqj@SERVER_ID.mailosaur.net"
});
Testing basic properties
Once you have fetched an email (e.g. using mailosaurGetMessage), you can easily test the properties of that email:
.then((email) =&gt; {
  // Test the email subject line
  expect(email.subject).to.equal("Password reset");

  // Test sender information
  expect(email.from[0].name).to.equal("Support");
  expect(email.from[0].email).to.equal("noreply@acme.com");

  // Test recipient information
  expect(email.to[0].name).to.equal("John Smith");
  expect(email.to[0].email).to.equal("john.smith@example.com");
});
Testing carbon-copy recipients
.then((email) =&gt; {
  // Carbon copy (CC) recipients
  expect(email.cc[0].name).to.equal("Jane Smith");
  expect(email.cc[0].email).to.equal("jane.smith@example.com");

  // Blind carbon copy (BCC) recipients
  expect(email.bcc[0].name).to.equal("Jill Smith");
  expect(email.bcc[0].email).to.equal("jill.smith@example.com");
});
Testing email contents
Most emails will contain separate HTML and plain text content. You can see below how to test either content type:
Plain text content
.then((email) =&gt; {
  // Check that the email contains some text
  expect(email.text.body).to.contain("Expected text");
});
HTML content
When testing HTML content, you can perform basic contains or equals assertions in the same way as with plain text content:
.then((email) =&gt; {
  // Check that raw HTML contains some expected content
  expect(email.html.body).to.contain("&lt;span&gt;Hello world&lt;/span&gt;");
});
In addition, if you want to perform lookups using CSS selectors, etc. you can use jsdom alongside Mailosaur.
You can install jsdom using npm:
npm install jsdom
Import the library at the start of your test file:
const jsdom = require("jsdom");
Now perform HTML operations like this:
.then((email) =&gt; {
  // Use a CSS selector to find the target element
  const dom = new JSDOM(email.html.body);
  const el = dom.window.document.querySelector('.customer-ref');

  // Check the contents of the target element
  expect(el.textContent).to.equal('XYZ123');
});
Testing links
Any links that are found in the content of your email are instantly available via the html.links or text.links arrays, depending on which content the link was found in:
.then((email) =&gt; {
  cy.log(`${email.html.links.length} links found in HTML content`);
  cy.log(`${email.text.links.length} links found in plain text content`);

  // Check the first link found in HTML content
  expect(email.html.links[0].href).to.equal('https://google.com');
  expect(email.html.links[0].text).to.equal('Google');
});
Navigating to a link
You can navigate to any link using the Cypress command cy.visit:
.then((email) =&gt; {
  // If the link is on a different domain you will also need to use `cy.origin`.
  // See https://docs.cypress.io/api/commands/visit#Visiting-cross-origin-sites
  return cy.visit(email.html.links[0].href);
})
.then(() =&gt; {
  // Do something on the new page
});
Clicking a link
If you just need to simulate a link being clicked and do not need to do anything on the target page, you can do this with https.
Import https at the top of your test file:
const https = require("https");
Then use this in your test to perform a &#39;click&#39;:
.then((email) =&gt; {
  // Make an HTTP call to simulate someone clicking a link
  https.get(email.html.links[0].href, r =&gt; cy.log(r.statusCode)) // 200
})
Testing verification codes
Codes are automatically extracted from the content of your email. Just like links, codes are made available via the html.codes or text.codes arrays, depending on which content the code was found in:
.then((email) =&gt; {
  cy.log(`${email.html.codes.length} codes found in HTML content`);
  cy.log(`${email.text.codes.length} codes found in plain text content`);

  // Check the first code found in HTML content
  expect(email.html.codes[0].value).to.equal('432123');
});
Testing attachments
Any email attachments are made available via the attachments array:
.then((email) =&gt; {
  cy.log(`${email.attachments.length} attachments found`);

  // Get the first attachment
  const attachment = email.attachments[0];

  // Check attachment attributes
  expect(attachment.fileName).to.equal('example.pdf');
  expect(attachment.contentType).to.equal('application/pdf');

  // Check the file size (in bytes)
  expect(attachment.length).to.equal(4028);
});
Save an attachment to disk
You can download and save attachments using the mailosaurDownloadAttachment and writeFile commands:
.then((email) =&gt; {
  cy.log(`${email.attachments.length} attachments found`);

  return cy.mailosaurDownloadAttachment(email.attachments[0].id);
})
.then((file) =&gt; {
  // Save file to disk
  cy.writeFile('some-file.pdf', file, 'binary');
});
Encoding attachments
In some scenarios you may need a base64-encoded copy of an attachment. You can achieve this using toString(&#39;base64&#39;):
.then((email) =&gt; {
  cy.log(`${email.attachments.length} attachments found`);

  return cy.mailosaurDownloadAttachment(email.attachments[0].id);
})
.then((file) =&gt; {
  const base64 = file.toString('base64');
});
Testing images and web beacons
Any images found within the HTML content of an email are made available via the html.images array:
.then((email) =&gt; {
  cy.log(`${email.html.images.length} images found`);

  // Get the first attachment
  const image = email.html.images[0];

  // Check image attributes
  expect(image.src).to.equal('https://example.com/balloon.png');
  expect(image.alt).to.equal('A green hot air balloon in the sky');
});
To test whether an image is accessible online, or that a web beacon is working as expected, you can simply perform an HTTP request, using https.
Import https at the top of your test file:
const https = require("https");
Then use this in your test to fetch the image:
.then((email) =&gt; {
  cy.log(`${email.html.images.length} images found`);

  // Get the first attachment
  const image = email.html.images[0];

  // Fetch the image
  https.get(image.src, r =&gt; cy.log(r.statusCode)) // 200
})
Testing deliverability
The mailosaurGetSpamAnalysis command runs a SpamAssassin test against an email. This will return an overall SpamAssassin score (see understand your SpamAssassin score).
The lower the score the better and, in most cases, a score higher than 5.0 will result in an email being seen as spam.
.then((email) =&gt; {
  return cy.mailosaurGetSpamAnalysis(email.id);
})
.then((result) =&gt; {
  // Overall SpamAssassin score. In most cases a score of
  expect(result.score).to.be.lessThan(3);

  result.spamFilterResults.spamAssassin.forEach(r =&gt; {
    cy.log(r.rule);
    cy.log(r.description);
    cy.log(r.score);
  });
})
List all messages
Recommendation: We strongly recommend using the mailosaurGetMessage command for most use cases. This command has been purposely optimised for the most common automated testing scenarios.
If you simply need to list the current emails in an inbox, you can use mailosaurListMessages:
cy.mailosaurListMessages("SERVER_ID")
  .then((result) =&gt; {
    cy.log(`${result.items.length} messages in inbox`);

    const email = result.items[0];

    expect(email.subject).to.equal("Password reset");

    // Note: List results only contain summary information. To get
    // the HTML/text content of an email, use `mailosaurGetMessageById`
    return cy.mailosaurGetMessageById(email.id);
  })
  .then((email) =&gt; {
    cy.log(email.html.body);
  });
Alternative search for messages
Recommendation: We strongly recommend using the mailosaurGetMessage command for most use cases. This command automatically waits for a matching result, and also returns the whole message object in the result, rather than just a summary.
Using the mailosaurSearchMessages command:
cy.mailosaurSearchMessages("SERVER_ID", {
  sentTo: "anything@SERVER_ID.mailosaur.net",
})
  .then((result) =&gt; {
    cy.log(`${result.items.length} matching messages found`);

    // Get the first result
    const email = result.items[0];

    expect(email.subject).to.equal("Password reset");

    // Note: Results only contain summary information. To get
    // the HTML/text content of an email, use `mailosaurGetMessageById`
    return cy.mailosaurGetMessageById(email.id);
  })
  .then((email) =&gt; {
    cy.log(email.html.body);
  });
Wait for matches to arrive
By default the mailosaurSearchMessages command will only return current matches. By setting the timeout option, the command will automatically wait for a match:
cy.mailosaurSearchMessages("SERVER_ID", {
  sentTo: "anything@SERVER_ID.mailosaur.net",
}, {
  timeout: 10000, // Wait 10 seconds (in milliseconds) for a match
});
Testing that no matching messages are found
By default, an error will be thrown if no matches are found in time. However, if you are expecting no messages to arrive in a certain period of time, then simply set errorOnTimeout: false to prevent an exception being thrown:
cy.mailosaurSearchMessages("SERVER_ID", {
  sentTo: "anything@SERVER_ID.mailosaur.net",
}, {
  timeout: 10000,
  errorOnTimeout: false,
});
Deleting messages
Delete all messages
To permanently delete all messages held in a specific server/inbox, use the mailosaurDeleteAllMessages command. This also deletes any attachments related to each message. This operation cannot be undone.
cy.mailosaurDeleteAllMessages("SERVER_ID");
Deleting an individual message
To permanently delete a single message, use mailosaurDeleteMessage. This also deletes any attachments related to the message. This operation cannot be undone.
cy.mailosaurDeleteMessage("MESSAGE_ID");
Download an email (.EML)
If you need to download a copy of an email, you can do this using the mailosaurDownloadMessage command.
This will download a .EML format file, allowing you to save an email offline and outside of Mailosaur or any other email software.
.then((email) =&gt; {
  return cy.mailosaurDownloadMessage(email.id);
})
.then((file) =&gt; {
  // Save file to disk
  cy.writeFile('email.eml', file, 'binary');
});
Replying to an email
If your product is capable of handling email replies from your customers, you can use Mailosaur’s reply feature to simulate such a scenario.
When you reply, the email is sent back to the email address it was originally sent to Mailosaur from. Before you can reply, you must first add this address as a verified external email address.
cy.mailosaurReplyToMessage("MESSAGE_ID", {
  text: "FYI",
});
The options available to use with the mailosaurReplyToMessage command are:



PARAMETER
DESCRIPTION



text
Any additional text content to reply to the email with.


html
Any additional HTML content to reply to the email with.


subject
Optionally override the default subject line.


attachments
Optional attachments (see &#39;inline attachments&#39; below).


Include attachments
You can include attachments in emails sent via the API, by including an array of base64-encoded attachment objects:
const attachments = [
  {
    fileName: "cat.png",
    contentType: "image/png",
    content: "{BASE64_ENCODED_FILE}",
  },
];

cy.mailosaurReplyToMessage("MESSAGE_ID", {
  to: "verified-address@example.com",
  subject: "Email from Mailosaur",
  html: "&lt;p&gt;Hello world.&lt;/p&gt;",
  attachments: attachments,
});
Forwarding an email
Teams often need to forward emails onto an email address outside of Mailosaur. For example, to send messages to colleagues for further review/analysis, or to test email handling functionality within an product.
You can forward messages from your Mailosaur account to external email addresses either one-by-one, or via the creation of automated forwarding rules.
Before you can forward messages, you must set up a verified external email address, so that you can send email to it.
cy.mailosaurForwardMessage("MESSAGE_ID", {
  to: "verified-address@example.com",
  text: "Hello world",
});
The options available to use with the mailosaurForwardMessage command are:



PARAMETER
DESCRIPTION



to
The email address to which the email will be sent. Must be a verified email address.


text
Any additional text content to forward the email with.


html
Any additional HTML content to forward the email with.


subject
Optionally override the default subject line.


Sending an email
If your product is capable of handling inbound emails, you can use Mailosaur’s sending feature to trigger this functionality in your product.
The mailosaurCreateMessage command creates and and sends an email to a verified external email address:
cy.mailosaurCreateMessage("SERVER_ID", {
  to: "verified-address@example.com",
  send: true,
  subject: "Request",
  text: "Please can you give us a call back?",
});
The options available to use with the mailosaurCreateMessage command are:



PARAMETER
DESCRIPTION



send
This must be set to true if you are sending an outbound email.


to
The email address to which the email will be sent. Must be a verified email address.


subject
The email subject line.


text
Any additional text content to forward the email with.


html
Any additional HTML content to forward the email with.


attachments
Optional attachments (see &#39;inline attachments&#39; below).


Include attachments
You can include attachments in emails sent via the API, by including an array of base64-encoded attachment objects:
const attachments = [
  {
    fileName: "cat.png",
    contentType: "image/png",
    content: "{BASE64_ENCODED_FILE}",
  },
];

cy.mailosaurCreateMessage("SERVER_ID", {
  to: "verified-address@example.com",
  send: true,
  subject: "Email from Mailosaur",
  html: "&lt;p&gt;Hello world.&lt;/p&gt;",
  attachments: attachments,
});
Working with servers
List servers
Return a list of your servers/inboxes. Servers are returned sorted in alphabetical order:
cy.mailosaurListServers().then((result) =&gt; {
  cy.log("You have a server called:", result.items[0].name);
});
Create a new inbox
Create a new server (inbox). Only the name property is required to create a new server via the API:
cy.mailosaurCreateServer({
  name: "My email tests",
});
Retrieve a server
Retrieve the detail for a single server. Simply supply the unique identifier for the required server:
cy.mailosaurGetServer("SERVER_ID").then((server) =&gt; {
  cy.log(server.name);
});
Retrieve the SMTP/POP3 password for a server
Retrieve the password, for use with SMTP and POP3, for a single server. Simply supply the unique identifier for the required server:
cy.mailosaurGetServerPassword("SERVER_ID").then((password) =&gt; {
  cy.log(password);
});
Update an server
Updates a single server/inbox:
retrievedServer.name = "Updated server name";

cy.mailosaurUpdateServer(retrievedServer);
Delete an inbox
Permanently delete a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone:
cy.mailosaurDeleteServer("SERVER_ID");


Learn how to automate email testing with Cypress by using Mailosaur

How to test email with Cypress

What is Mailosaur?
Mailosaur is a service that captures email and SMS messages and lets you test them, both via it’s web dashboard and via the Mailosaur testing API.
If you don’t already have one, create a free account trial now, and send an email into Mailosaur first. Once you have this working, you’re ready to start testing!
Install the Mailosaur API client
Mailosaur provides an official library with everything you need to easily automate email testing in Playwright or any other Node.js tests.
Install the Mailosaur Node.js library via npm
npm install mailosaur
Import Mailosaur into your project
In order to connect to Mailosaur, you need an API key. You access your API key via in the account settings area.
In your tests, simply import the Mailosaur library, using your API key:
const MailosaurClient = require("mailosaur");
const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");
Basic usage
The messages.get method automatically waits for the first email to arrive that matches the search criteria you provide.
const MailosaurClient = require("mailosaur");
const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");

const email = await mailosaur.messages.get("SERVER_ID", {
  sentTo: "anything@SERVER_ID.mailosaur.net",
});

console.log(email.subject);
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
This example searches for the email address a message was sent to, but you can also search using any of this criteria too:



PARAMETER
DESCRIPTION



sentTo
The full email address to which the target message was sent.


sentFrom
The full email address from which the target message was sent.


subject
Find emails where the subject line contains this text.


body
Finds messages where the message body contains this text.


The messages.get method returns the message object, which contains everything you need to perform in-depth automated testing.
Increasing the wait time
By default, the messages.get method will wait for 10 seconds for a matching message to arrive. You can increase this wait time by using the timeout option:
const email = await mailosaur.messages.get(
  "SERVER_ID",
  {
    sentTo: "anything@SERVER_ID.mailosaur.net",
  },
  {
    timeout: 20000, // 20 seconds (in milliseconds)
  }
);

console.log(email.subject);
Searching for older messages
By default, the messages.get method will only find messages received in the last hour. You can change this by setting the receivedAfter option.
const testStart = new Date();

// TODO Do something here to send an email into your account

// Find any email received after `testStart` was set
const email = await mailosaur.messages.get(
  "SERVER_ID",
  {
    sentTo: "anything@SERVER_ID.mailosaur.net",
  },
  {
    receivedAfter: testStart,
  }
);

console.log(email.subject);
Test email addresses
Because Mailosaur email addresses use a wildcard pattern, all plans give you access to unlimited test email addresses. Any address ending @YOUR_SERVER_ID.mailosaur.net will work.
You can use your own logic to make up an email address, or use the servers.generateEmailAddress helper method to generate a random string for you:
// Returns a random email address for this server, e.g. "bgwqj@SERVER_ID.mailosaur.net"
const emailAddress = mailosaur.servers.generateEmailAddress("SERVER_ID");
Testing basic properties
Once you have fetched an email (e.g. using messages.get), you can easily test the properties of that email:
// Test the email subject line
expect(email.subject).toBe("Password reset");

// Test sender information
expect(email.from[0].name).toBe("Support");
expect(email.from[0].email).toBe("noreply@acme.com");

// Test recipient information
expect(email.to[0].name).toBe("John Smith");
expect(email.to[0].email).toBe("john.smith@example.com");
Testing carbon-copy recipients
// Carbon copy (CC) recipients
expect(email.cc[0].name).toBe("Jane Smith");
expect(email.cc[0].email).toBe("jane.smith@example.com");

// Blind carbon copy (BCC) recipients
expect(email.bcc[0].name).toBe("Jill Smith");
expect(email.bcc[0].email).toBe("jill.smith@example.com");
Testing email contents
Most emails will contain separate HTML and plain text content. You can see below how to test either content type:
Plain text content
// Check that the email contains some text
expect(email.text.body).toContain("Expected text");
HTML content
When testing HTML content, you can perform basic contains or equals assertions in the same way as with plain text content:
// Check that raw HTML contains some expected content
expect(email.html.body).toContain("&lt;span&gt;Hello world&lt;/span&gt;");
In addition, if you want to perform lookups using CSS selectors, etc. you can use jsdom alongside Mailosaur.
You can install jsdom using npm:
npm install jsdom
Import the library at the start of your test file:
const jsdom = require("jsdom");
Now perform HTML operations like this:
// Use a CSS selector to find the target element
const dom = new JSDOM(email.html.body);
const el = dom.window.document.querySelector(".customer-ref");

// Check the contents of the target element
expect(el.textContent).toBe("XYZ123");
Testing links
Any links that are found in the content of your email are instantly available via the html.links or text.links arrays, depending on which content the link was found in:
console.log(`${email.html.links.length} links found in HTML content`);
console.log(`${email.text.links.length} links found in plain text content`);

// Check the first link found in HTML content
expect(email.html.links[0].href).toBe("https://google.com");
expect(email.html.links[0].text).toBe("Google");
Navigating to a link
If you using an automation framework like Playwright or Cypress, you can navigate the browser to links within your tests:
// Playwright Example: Navigating to a link found in an email
await page.goto(email.html.links[0].href);
Clicking a link
If you just need to simulate a link being clicked and do not need to do anything on the target page, you can do this with https.
Import https at the top of your test file:
const https = require("https");
Then use this in your test to perform a &#39;click&#39;:
// Make an HTTP call to simulate someone clicking a link
https.get(email.html.links[0].href, (r) =&gt; console.log(r.statusCode)); // 200
Testing verification codes
Codes are automatically extracted from the content of your email. Just like links, codes are made available via the html.codes or text.codes arrays, depending on which content the code was found in:
console.log(`${email.html.codes.length} codes found in HTML content`);
console.log(`${email.text.codes.length} codes found in plain text content`);

// Check the first code found in HTML content
expect(email.html.codes[0].value).toBe("432123");
Testing attachments
Any email attachments are made available via the attachments array:
console.log(`${email.attachments.length} attachments found`);

// Get the first attachment
const attachment = email.attachments[0];

// Check attachment attributes
expect(attachment.fileName).toBe("example.pdf");
expect(attachment.contentType).toBe("application/pdf");

// Check the file size (in bytes)
expect(attachment.length).toBe(4028);
Save an attachment to disk
You can download and save attachments using the files.getAttachment and writeFile methods:
console.log(`${email.attachments.length} attachments found`);

const file = await mailosaur.files.getAttachment(email.attachments[0].id);

// Save file to disk
fs.writeFile("some-file.pdf", file, () =&gt; console.log("File saved."));
Encoding attachments
In some scenarios you may need a base64-encoded copy of an attachment. You can achieve this using toString(&#39;base64&#39;):
console.log(`${email.attachments.length} attachments found`);

const file = await mailosaur.files.getAttachment(email.attachments[0].id);

const base64 = file.toString("base64");
Testing images and web beacons
Any images found within the HTML content of an email are made available via the html.images array:
console.log(`${email.html.images.length} images found`);

// Get the first attachment
const image = email.html.images[0];

// Check image attributes
expect(image.src).toBe("https://example.com/balloon.png");
expect(image.alt).toBe("A green hot air balloon in the sky");
To test whether an image is accessible online, or that a web beacon is working as expected, you can simply perform an HTTP request, using https.
Import https at the top of your test file:
const https = require("https");
Then use this in your test to fetch the image:
console.log(`${email.html.images.length} images found`);

// Get the first attachment
const image = email.html.images[0];

// Fetch the image
https.get(image.src, (r) =&gt; console.log(r.statusCode)); // 200
Testing deliverability
The analysis.spam method runs a SpamAssassin test against an email. This will return an overall SpamAssassin score (see understand your SpamAssassin score).
The lower the score the better and, in most cases, a score higher than 5.0 will result in an email being seen as spam.
const result = await mailosaur.analysis.spam(email.id);

// Overall SpamAssassin score. In most cases a score of
expect(result.score).toBeLessThan(3);

result.spamFilterResults.spamAssassin.forEach((r) =&gt; {
  console.log(r.rule);
  console.log(r.description);
  console.log(r.score);
});
List all messages
Recommendation: We strongly recommend using the messages.get method for most use cases. This method has been purposely optimised for the most common automated testing scenarios.
If you simply need to list the current emails in an inbox, you can use messages.list:
const result = await mailosaur.messages.list("SERVER_ID");

console.log(`${result.items.length} messages in inbox`);

const match = result.items[0];

expect(match.subject).toBe("Password reset");

// Note: List results only contain summary information. To get
// the HTML/text content of an email, use `messages.getById`
const email = await mailosaur.messages.getById(match.id);

console.log(email.html.body);
Alternative search for messages
Recommendation: We strongly recommend using the messages.get method for most use cases. This method automatically waits for a matching result, and also returns the whole message object in the result, rather than just a summary.
Using the messages.search method:
const result = await mailosaur.messages.search("SERVER_ID", {
  sentTo: "anything@SERVER_ID.mailosaur.net",
});

console.log(`${result.items.length} matching messages found`);

// Get the first result
const match = result.items[0];

expect(match.subject).toBe("Password reset");

// Note: Results only contain summary information. To get
// the HTML/text content of an email, use `messages.getById`
const email = await mailosaur.messages.getById(match.id);

console.log(email.html.body);
Wait for matches to arrive
By default the messages.search method will only return current matches. By setting the timeout option, the method will automatically wait for a match:
const result = await mailosaur.messages.search(
  "SERVER_ID",
  {
    sentTo: "anything@SERVER_ID.mailosaur.net",
  },
  {
    timeout: 10000, // Wait 10 seconds (in milliseconds) for a match
  }
);
Testing that no matching messages are found
By default, an error will be thrown if no matches are found in time. However, if you are expecting no messages to arrive in a certain period of time, then simply set errorOnTimeout: false to prevent an exception being thrown:
const result = await mailosaur.messages.search(
  "SERVER_ID",
  {
    sentTo: "anything@SERVER_ID.mailosaur.net",
  },
  {
    timeout: 10000,
    errorOnTimeout: false,
  }
);
Deleting messages
Delete all messages
To permanently delete all messages held in a specific server/inbox, use the messages.deleteAll method. This also deletes any attachments related to each message. This operation cannot be undone.
await mailosaur.messages.deleteAll("SERVER_ID");
Deleting an individual message
To permanently delete a single message, use messages.del. This also deletes any attachments related to the message. This operation cannot be undone.
await mailosaur.messages.del("MESSAGE_ID");
Download an email (.EML)
If you need to download a copy of an email, you can do this using the files.getEmail method.
This will download a .EML format file, allowing you to save an email offline and outside of Mailosaur or any other email software.
const file = await mailosaur.files.getEmail(email.id);

// Save file to disk
fs.writeFile("email.eml", file, () =&gt; console.log("Email saved."));
Replying to an email
If your product is capable of handling email replies from your customers, you can use Mailosaur’s reply feature to simulate such a scenario.
When you reply, the email is sent back to the email address it was originally sent to Mailosaur from. Before you can reply, you must first add this address as a verified external email address.
await mailosaur.messages.reply("MESSAGE_ID", {
  text: "FYI",
});
The options available to use with the messages.reply method are:



PARAMETER
DESCRIPTION



text
Any additional text content to reply to the email with.


html
Any additional HTML content to reply to the email with.


subject
Optionally override the default subject line.


attachments
Optional attachments (see &#39;inline attachments&#39; below).


Include attachments
You can include attachments in emails sent via the API, by including an array of base64-encoded attachment objects:
const attachments = [
  {
    fileName: "cat.png",
    contentType: "image/png",
    content: "{BASE64_ENCODED_FILE}",
  },
];

await mailosaur.messages.reply("MESSAGE_ID", {
  to: "verified-address@example.com",
  subject: "Email from Mailosaur",
  html: "&lt;p&gt;Hello world.&lt;/p&gt;",
  attachments: attachments,
});
Forwarding an email
Teams often need to forward emails onto an email address outside of Mailosaur. For example, to send messages to colleagues for further review/analysis, or to test email handling functionality within an product.
You can forward messages from your Mailosaur account to external email addresses either one-by-one, or via the creation of automated forwarding rules.
Before you can forward messages, you must set up a verified external email address, so that you can send email to it.
await mailosaur.messages.forward("MESSAGE_ID", {
  to: "verified-address@example.com",
  text: "Hello world",
});
The options available to use with the messages.forward method are:



PARAMETER
DESCRIPTION



to
The email address to which the email will be sent. Must be a verified email address.


text
Any additional text content to forward the email with.


html
Any additional HTML content to forward the email with.


subject
Optionally override the default subject line.


Sending an email
If your product is capable of handling inbound emails, you can use Mailosaur’s sending feature to trigger this functionality in your product.
The messages.create method creates and and sends an email to a verified external email address:
await mailosaur.messages.create("SERVER_ID", {
  to: "verified-address@example.com",
  send: true,
  subject: "Request",
  text: "Please can you give us a call back?",
});
The options available to use with the messages.create method are:



PARAMETER
DESCRIPTION



send
This must be set to true if you are sending an outbound email.


to
The email address to which the email will be sent. Must be a verified email address.


subject
The email subject line.


text
Any additional text content to forward the email with.


html
Any additional HTML content to forward the email with.


attachments
Optional attachments (see &#39;inline attachments&#39; below).


Include attachments
You can include attachments in emails sent via the API, by including an array of base64-encoded attachment objects:
const attachments = [
  {
    fileName: "cat.png",
    contentType: "image/png",
    content: "{BASE64_ENCODED_FILE}",
  },
];

await mailosaur.messages.create("SERVER_ID", {
  to: "verified-address@example.com",
  send: true,
  subject: "Email from Mailosaur",
  html: "&lt;p&gt;Hello world.&lt;/p&gt;",
  attachments: attachments,
});
Working with servers
List servers
Return a list of your servers/inboxes. Servers are returned sorted in alphabetical order:
const result = await mailosaur.servers.list();

console.log("You have a server called:", result.items[0].name);
Create a new inbox
Create a new server (inbox). Only the name property is required to create a new server via the API:
const result = await mailosaur.servers.create({
  name: "My email tests",
});
Retrieve a server
Retrieve the detail for a single server. Simply supply the unique identifier for the required server:
const server = await mailosaur.servers.get("SERVER_ID");

console.log(server.name);
Retrieve the SMTP/POP3 password for a server
Retrieve 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");

console.log(password);
Update an server
Updates a single server/inbox:
retrievedServer.name = "Updated server name";

await mailosaur.servers.update(retrievedServer.id, retrievedServer);
Delete an inbox
Permanently delete a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone:
await mailosaur.servers.del("SERVER_ID");


This guide shows you how to easily test email in Node.js and test frameworks like Playwright

Email testing with Node.js and Mailosaur

What is Playwright?
Playwright is a Node.js library that lets you automate modern web browsers. Playwright is made by Microsoft and is used as part of the Quality Assurance testing of Microsoft’s own service.
At this stage, we assume that you already know how to test with Playwright, however if you’re just getting started, check out the official Playwright guide, then come back here to start testing email and SMS!
What is Mailosaur?
Mailosaur is a service that captures email and SMS messages and lets you test them, both via it’s web dashboard and via the Mailosaur testing API.
If you don’t already have one, create a free account trial now, and send an email into Mailosaur first. Once you have this working, you’re ready to start testing!
Create a Playwright project
It only takes a few minutes to create a simple Playwright project to work with, but if you have an existing project you can skip this step.
First, initialise a new project with:
npm init playwright@latest
When prompted, select the following options:
Getting started with writing end-to-end tests with Playwright:
Initializing project in '.'
✔ Do you want to use TypeScript or JavaScript? · TypeScript
✔ Where to put your end-to-end tests? · tests
✔ Add a GitHub Actions workflow? (y/N) · false
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) · true
A simple Playwright project is created for you, with some example tests included within the file tests/example.spec.ts:
import { test, expect } from "@playwright/test";

test("has title", async ({ page }) =&gt; {
  await page.goto("https://playwright.dev/");

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

test("get started link", async ({ page }) =&gt; {
  await page.goto("https://playwright.dev/");

  // Click the get started link.
  await page.getByRole("link", { name: "Get started" }).click();

  // Expects page to have a heading with the name of Installation.
  await expect(
    page.getByRole("heading", { name: "Installation" })
  ).toBeVisible();
});
You can now run these tests using:
$ npx playwright test
The output looking something like this, with all tests passing:
Running 6 tests using 5 workers
  6 passed (5.1s)
Install the Mailosaur API client
To allow you to easily test email in Playwright, Mailosaur provides an official Node.js library with everything you need to easily automate email testing.
Install the Mailosaur Node.js library via npm
npm install mailosaur
Import Mailosaur into your project
In order to connect to Mailosaur, you need an API key. You access your API key via in the account settings area.
In your tests, simply import the Mailosaur library, using your API key, at the top of your spec file:
import { test, expect } from "@playwright/test";
import MailosaurClient from "mailosaur";

const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");
Basic usage
The messages.get method automatically waits for the first email to arrive that matches the search criteria you provide.
test("password reset", async ({ page }) =&gt; {
  const serverId = "YOUR_SERVER_ID_HERE";
  const testEmailAddress = `some-test-run123@${serverId}.mailosaur.net`;

  // Navigate to a password reset page, and submit the form to trigger an email
  await page.goto("https://example.mailosaur.com/password-reset");
  await page.fill("#email", testEmailAddress);
  await page.click('button[type="submit"]');

  // Connect to Mailosaur, and wait for that email to arrive
  const email = await mailosaur.messages.get(serverId, {
    sentTo: testEmailAddress,
  });

  expect(email.subject).toBe("Password reset");
});
Testing email with Playwright
Playwright users should use the official Node.js library for Mailosaur. Head over to our email testing guide for Node.js for examples on everyhing you could possibly want to test with Playwright, including:

Basic email properties
Email content
Testing links
Testing verification codes
Attachments
Images
Deliverability


This guide shows you how to easily test email in Node.js and Playwright

Email testing with Playwright and Mailosaur

Learn how to use our virtual SMTP servers to create test emails, account verification emails, password resets, email tracking, and more.

Email testing

How do I request a number?
You can request phone numbers within the Mailosaur Dashboard:

Select SMS in the main navigation bar.
Click the Request Number button.
Confirm which country you need the number for, and which server the number should be assigned to.If you are on a free trial, or have selected a country for which additional charges apply, your request will be referred to our support team, who will get it touch to guide you through.## Requesting numbers for countries that are not listed
Mailosaur is able to offer numbers in a wide array of countries, however many countries have specific requirements that mean we must handle these requests on a case-by-case basis. Contact our support team for more information.

How much do phone numbers cost?
US, UK and Canadian numbers are included in the prices listed on our pricing page. Numbers for other countries (such as France, Germany and Australia) cost more to operate and so additional charges apply. You can speak to a member of our team who will be able to take you through pricing.
How many numbers can I have?
Our Business plan includes 1 number, and our Professional plan includes 5 as standard. In both cases you can add additional numbers to your account from as low as $1 per number, per month.
To add more numbers to your plan, head to the Billing area of the Dashboard and click the Change Limit button at the top of Phone Numbers panel. Note that you must be a Billing Administrator on an account with an active Business or Professional plan to do this.
Proof of address and other requirements
Many countries have specific onboarding requirements, such as proving the existance of a physical address within the country. Our team can guide you through any specific requirements for the country you have selected during the onboarding process.
How can I test with my new phone number?
Once a number has been allocated to your server, you can start testing. Take a look at our simple SMS testing guide for more information.

Learn to test SMS functionality with Mailosaur. Request, cost, and allocate mobile phone numbers for testing. 

Test phone numbers

If your product is capable of handling SMS replies from your customers (e.g. to opt out of further messages), you can use Mailosaur’s reply feature to simulate such a scenario.
When you reply, the SMS message is obviously sent back to the phone number it was originally sent to Mailosaur from. Before you can reply to SMS for the first time, you should speak with our support team first, so that we can verify your account, and use case, in order to prevent fraud.
Approved phrases
In order to prevent fraud, Mailosaur restricts SMS replies to words and phrases that have been pre-approved by our SMS team. Our approved phrases are case-insenstive and already cover a wide array of use cases, however if you find that your reply is rejected, just contact our support team to request an addition.
In general, most single word replies (Stop, Yes, No, etc.) will work.
Replying to an SMS message
You can reply to SMS messages within the Mailosaur Dashboard, or via the API:

Enhance your SMS testing capabilities by simulating user replies. Utilize Mailosaur&#39;s reply function for a comprehensive SMS testing solution.

Replying to SMS messages

What is Cypress?
Cypress is an end-to-end testing framework that has won over developers and testers for its ease of use and flexibility. To use Cypress for your browser test automation, you’ll need to write your tests in JavaScript. Once your code is ready, you’ll be able to repeatedly run test cases using a real browser.
What makes Cypress unique is its batteries-included approach: all the tools required for end-to-end testing are already part of the Cypress framework, and there’s no need for anything extra. Fewer tools to install means faster setup and more time to write tests. Because Cypress’s components are well-integrated, its tests are usually more stable than end-to-end tests using other frameworks.
What is Mailosaur?
Mailosaur is a testing suite that lets you automate SMS testing with Cypress and other testing frameworks. This is important for websites and web apps that send SMS messages (account notifications, alerts, order tracking, verification codes, etc.). Mailosaur also lets you test email with Cypress too!
If you don’t already have one, you’ll need to create a free trial account.
Install the Mailosaur plugin
Mailosaur provides an official set of custom commands, that allow you to automate SMS testing seamlessly in Cypress.
Extend Cypress, by installing Mailosaur’s custom commands package cypress-mailosaur.
1. Install the plugin via npm
npm install cypress-mailosaur
2. Import Mailosaur into your Cypress project
Once installed, open cypress/support/e2e.js in your project folder, and add the following line of code to it:
import "cypress-mailosaur";
Note: In old versions of Cypress, the file may be called cypress/support/index.js.
3. Configure your API key
In order to connect to Mailosaur, you need to add an API key to your tests. You access your API key via in the account settings area.
Add your Mailosaur API key to cypress.config.js, in your project folder:
module.exports = defineConfig({
  env: {
    MAILOSAUR_API_KEY: "your-key-here",
  },

  // ...
});
Note: We strongly recommend against storing API keys in source control. Therefore you can also set your API key the environment variable CYPRESS_MAILOSAUR_API_KEY.
Basic usage
The mailosaurGetMessage command automatically waits for the first message to arrive that matches the provided search criteria.
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
cy.mailosaurGetMessage("SERVER_ID", {
  sentTo: "15551234444",
}).then((sms) =&gt; {
  cy.log(sms.text.body);
});
This example search for the phone number that a message was sent to, but you can also search using any of this criteria too:



PARAMETER
DESCRIPTION



sentTo
The full phone number to which the target message was sent.


sentFrom
The full phone number from which the target message was sent.


body
Finds messages where the message body contains this text.


The mailosaurGetMessage command returns the message object, which contains everything you need to perform in-depth automated testing.
Increasing the wait time
By default, the mailosaurGetMessage command will wait for 10 seconds for a matching message to arrive. You can increase this wait time by using the timeout option:
cy.mailosaurGetMessage(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 20000, // 20 seconds (in milliseconds)
  }
).then((sms) =&gt; {
  cy.log(sms.text.body);
});
Searching for older messages
By default, the mailosaurGetMessage command will only find messages received in the last hour. You can change this by setting the receivedAfter option.
const testStart = new Date();

// TODO Do something here to send an SMS message into your account

// Find any SMS received after `testStart` was set
cy.mailosaurGetMessage(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    receivedAfter: testStart,
  }
).then((sms) =&gt; {
  cy.log(sms.text.body);
});
Testing basic properties
.then((sms) =&gt; {
  // Test sender information
  expect(sms.from[0].name).toBe("ACME Corp.");
  expect(sms.from[0].phone).toBe("123456");

  // Test recipient information
  expect(sms.to[0].phone).toBe("15551234444");
});
Testing SMS contents
The content of an SMS message is available via the text.body property:
.then((sms) =&gt; {
  // Check that the SMS message contains some text
  expect(sms.text.body).to.contain("Expected text");
});
Testing links
Any links that are found in the content of your email are automatically available via the text.links array:
.then((sms) =&gt; {
  cy.log(`${sms.text.links.length} links found in text content`);

  // Check the first link found in message content
  expect(sms.html.links[0].href).to.equal('https://google.com');
});
Navigating to a link
You can navigate to any link using the Cypress command cy.visit:
.then((sms) =&gt; {
  // If the link is on a different domain you will also need to use `cy.origin`.
  // See https://docs.cypress.io/api/commands/visit#Visiting-cross-origin-sites
  return cy.visit(sms.text.links[0].href);
})
.then(() =&gt; {
  // Do something on the new page
});
Clicking a link
If you just need to simulate a link being clicked and do not need to do anything on the target page, you can do this with https.
Import https at the top of your test file:
const https = require("https");
Then use this in your test to perform a &#39;click&#39;:
.then((sms) =&gt; {
  // Make an HTTP call to simulate someone clicking a link
  https.get(sms.html.links[0].href, r =&gt; cy.log(r.statusCode)) // 200
})
Testing verification codes
Codes are automatically extracted from the content of your SMS message. Codes are made available via the text.codes array:
.then((sms) =&gt; {
  cy.log(`${sms.text.codes.length} codes found in plain text content`);

  // Check the first code found in text content
  expect(sms.text.codes[0].value).to.equal('432123');
});
List all messages
Recommendation: We strongly recommend using the mailosaurGetMessage command for most use cases. This command has been purposely optimised for the most common automated testing use cases.
If you simply need to list the current messages in an inbox, you can use mailosaurListMessages:
cy.mailosaurListMessages("SERVER_ID")
  .then((result) =&gt; {
    cy.log(`${result.items.length} messages in inbox`);

    // Note: List results only contain summary information. To get
    // the text content of a message, use `mailosaurGetMessageById`
    return cy.mailosaurGetMessageById(result.items[0].id);
  })
  .then((sms) =&gt; {
    cy.log(sms.text.body);
  });
Alternative search for messages
Recommendation: We strongly recommend using the mailosaurGetMessage command for most use cases. This command automatically waits for a matching result, and also returns the message in the result rather than just a summary.
The mailosaurSearchMessages command access:
cy.mailosaurSearchMessages("SERVER_ID", {
  sentTo: "15551234444",
})
  .then((result) =&gt; {
    cy.log(`${result.items.length} matching messages found`);

    // Note: Results only contain summary information. To get
    // the text content of a message, use `mailosaurGetMessageById`
    return cy.mailosaurGetMessageById(result.items[0].id);
  })
  .then((sms) =&gt; {
    cy.log(sms.text.body);
  });
Wait for matches to arrive
By default the mailosaurSearchMessages command will only return current matches. By setting the timeout option, the command will automatically wait for a match:
cy.mailosaurSearchMessages(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 10000, // Wait 10 seconds (in milliseconds) for a match
  }
);
Testing that no matching messages are found
By default, an error will be thrown if no matches are found in time. If you are expecting no message to arrive, then set errorOnTimeout: false to prevent an exception:
cy.mailosaurSearchMessages(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 10000,
    errorOnTimeout: false,
  }
);
Deleting messages
Delete all messages
Permanently deletes all messages held in the specified server/inbox. Also deletes any attachments related to each message. This operation cannot be undone.
cy.mailosaurDeleteAllMessages("SERVER_ID");
Deleting an individual message
Permanently deletes a single message. Also deletes any attachments related to the message. This operation cannot be undone.
cy.mailosaurDeleteMessage(messageId);
Replying to an SMS message
If your product is capable of handling SMS replies from your customers, you can use Mailosaur’s reply feature to simulate such a scenario.
When you reply, the SMS is sent back to the phone number it was originally sent to Mailosaur from.
cy.mailosaurReplyToMessage("MESSAGE_ID", {
  text: "FYI",
});
Forwarding a message to email
Teams often need to forward SMS messages onto an email address outside of Mailosaur. For example, to send messages to colleagues for further review/analysis.
You can forward messages from your Mailosaur account to external email addresses either one-by-one, or via the creation of automated forwarding rules.
Before you can forward messages, you must set up a verified external email address, so that you can send email to it.
cy.mailosaurForwardMessage("MESSAGE_ID", {
  to: "verified-address@example.com",
  text: "Hello world",
});
The options available to use with the mailosaurForwardMessage command are:



PARAMETER
DESCRIPTION



to
The email address to which the email will be sent. Must be a verified email address.


text
Any additional text content to forward the message with.


html
Any additional HTML content to forward the message with.


subject
Optionally override the default subject line.



Learn how to automate SMS testing with Cypress by using Mailosaur

SMS testing with Cypress

What is Mailosaur?
Mailosaur is a service that captures email and SMS messages and lets you test them, both via it’s web dashboard and via the Mailosaur testing API.
Install the Mailosaur API client
Mailosaur provides an official library with everything you need to easily automate SMS testing in Playwright or any other Node.js tests.
Install the Mailosaur Node.js library via npm
npm install mailosaur
Import Mailosaur into your project
In order to connect to Mailosaur, you need an API key. You access your API key via in the account settings area.
In your tests, simply import the Mailosaur library, using your API key:
const MailosaurClient = require("mailosaur");
const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");
Basic usage
The messages.get method automatically waits for the first SMS to arrive that matches the search criteria you provide.
const MailosaurClient = require("mailosaur");
const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");

const sms = await mailosaur.messages.get("SERVER_ID", {
  sentTo: "15551234444",
});

console.log(sms.text.body);
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
This example searches for the phone number a message was sent to, but you can also search using any of this criteria too:



PARAMETER
DESCRIPTION



sentTo
The full phone number to which the target message was sent.


sentFrom
The full phone number from which the target message was sent.


body
Finds messages where the message body contains this text.


The messages.get method returns the message object, which contains everything you need to perform in-depth automated testing.
Increasing the wait time
By default, the messages.get method will wait for 10 seconds for a matching message to arrive. You can increase this wait time by using the timeout option:
const sms = await mailosaur.messages.get(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 20000, // 20 seconds (in milliseconds)
  }
);

console.log(sms.text.body);
Searching for older messages
By default, the messages.get method will only find messages received in the last hour. You can change this by setting the receivedAfter option.
const testStart = new Date();

// TODO Do something here to send an SMS message into your account

// Find any SMS received after `testStart` was set
const sms = await mailosaur.messages.get(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    receivedAfter: testStart,
  }
);

console.log(sms.text.body);
Testing basic properties
Once you have fetched an SMS message (e.g. using messages.get), you can easily test the properties of that message:
// Test sender information
expect(sms.from[0].name).toBe("ACME Corp.");
expect(sms.from[0].phone).toBe("123456");

// Test recipient information
expect(sms.to[0].phone).toBe("15551234444");
Testing SMS contents
The content of an SMS message is available via the text.body property:
// Check that the SMS message contains some text
expect(sms.text.body).toContain("Expected text");
Testing links
Any links that are found in the content of your message are instantly available via the text.links array:
console.log(`${sms.text.links.length} links found in text content`);

// Check the first link found
expect(sms.text.links[0].href).toBe("https://google.com");
Navigating to a link
If you using an automation framework like Playwright or Cypress, you can navigate the browser to links within your tests:
// Playwright Example: Navigating to a link found in an SMS message
await page.goto(sms.text.links[0].href);
Clicking a link
If you just need to simulate a link being clicked and do not need to do anything on the target page, you can do this with https.
Import https at the top of your test file:
const https = require("https");
Then use this in your test to perform a &#39;click&#39;:
// Make an HTTP call to simulate someone clicking a link
https.get(sms.text.links[0].href, (r) =&gt; console.log(r.statusCode)); // 200
Testing verification codes
Codes are automatically extracted from the content of your SMS message. Codes are made available via the text.codes array:
console.log(`${sms.text.codes.length} codes found in text content`);

// Check the first code found in text content
expect(sms.text.codes[0].value).toBe("432123");
List all messages
Recommendation: We strongly recommend using the messages.get method for most use cases. This method has been purposely optimised for the most common automated testing scenarios.
If you simply need to list the current messages in an inbox, you can use messages.list:
const result = await mailosaur.messages.list("SERVER_ID");

console.log(`${result.items.length} messages in inbox`);

// Note: List results only contain summary information. To get
// the text content of a message, use `messages.getById`
const sms = await mailosaur.messages.getById(result.items[0].id);

console.log(sms.text.body);
Alternative search for messages
Recommendation: We strongly recommend using the messages.get method for most use cases. This method automatically waits for a matching result, and also returns the whole message object in the result, rather than just a summary.
Using the messages.search method:
const result = await mailosaur.messages.search("SERVER_ID", {
  sentTo: "15551234444",
});

console.log(`${result.items.length} messages in inbox`);

// Note: List results only contain summary information. To get
// the text content of a message, use `messages.getById`
const sms = await mailosaur.messages.getById(result.items[0].id);

console.log(sms.text.body);
Wait for matches to arrive
By default the messages.search method will only return current matches. By setting the timeout option, the method will automatically wait for a match:
const result = await mailosaur.messages.search(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 10000, // Wait 10 seconds (in milliseconds) for a match
  }
);
Testing that no matching messages are found
By default, an error will be thrown if no matches are found in time. However, if you are expecting no messages to arrive in a certain period of time, then simply set errorOnTimeout: false to prevent an exception being thrown:
const result = await mailosaur.messages.search(
  "SERVER_ID",
  {
    sentTo: "15551234444",
  },
  {
    timeout: 10000,
    errorOnTimeout: false,
  }
);
Deleting messages
Delete all messages
To permanently delete all messages held in a specific server/inbox, use the messages.deleteAll method. This also deletes any attachments related to each message. This operation cannot be undone.
await mailosaur.messages.deleteAll("SERVER_ID");
Deleting an individual message
To permanently delete a single message, use messages.del. This also deletes any attachments related to the message. This operation cannot be undone.
await mailosaur.messages.del("MESSAGE_ID");
Replying to an SMS message
If your product is capable of handling SMS replies from your customers, you can use Mailosaur’s reply feature to simulate such a scenario.
When you reply, the SMS is sent back to the phone number it was originally sent to Mailosaur from.
await mailosaur.messages.reply("MESSAGE_ID", {
  text: "FYI",
});
Forwarding a message to email
Teams often need to forward SMS messages onto an email address outside of Mailosaur. For example, to send messages to colleagues for further review/analysis.
You can forward messages from your Mailosaur account to external email addresses either one-by-one, or via the creation of automated forwarding rules.
Before you can forward messages, you must set up a verified external email address, so that you can send email to it.
await mailosaur.messages.forward("MESSAGE_ID", {
  to: "verified-address@example.com",
  text: "Hello world",
});
The options available to use with the messages.forward method are:



PARAMETER
DESCRIPTION



to
The email address to which the email will be sent. Must be a verified email address.


text
Any additional text content to forward the message with.


html
Any additional HTML content to forward the message with.


subject
Optionally override the default subject line.



This guide shows you how to easily test SMS in Node.js and test frameworks like Playwright

SMS testing with Node.js and Mailosaur

What is Playwright?
Playwright is a Node.js library that lets you automate modern web browsers. Playwright is made by Microsoft and is used as part of the Quality Assurance testing of Microsoft’s own service.
At this stage, we assume that you already know how to test with Playwright, however if you’re just getting started, check out the official Playwright guide, then come back here to start testing email and SMS!
What is Mailosaur?
Mailosaur is a service that captures email and SMS messages and lets you test them, both via it’s web dashboard and via the Mailosaur testing API.
If you don’t already have one, create a free account trial now.
Create a Playwright project
It only takes a few minutes to create a simple Playwright project to work with, but if you have an existing project you can skip this step.
First, initialise a new project with:
npm init playwright@latest
When prompted, select the following options:
Getting started with writing end-to-end tests with Playwright:
Initializing project in '.'
✔ Do you want to use TypeScript or JavaScript? · TypeScript
✔ Where to put your end-to-end tests? · tests
✔ Add a GitHub Actions workflow? (y/N) · false
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) · true
A simple Playwright project is created for you, with some example tests included within the file tests/example.spec.ts:
import { test, expect } from "@playwright/test";

test("has title", async ({ page }) =&gt; {
  await page.goto("https://playwright.dev/");

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

test("get started link", async ({ page }) =&gt; {
  await page.goto("https://playwright.dev/");

  // Click the get started link.
  await page.getByRole("link", { name: "Get started" }).click();

  // Expects page to have a heading with the name of Installation.
  await expect(
    page.getByRole("heading", { name: "Installation" })
  ).toBeVisible();
});
You can now run these tests using:
$ npx playwright test
The output looking something like this, with all tests passing:
Running 6 tests using 5 workers
  6 passed (5.1s)
Install the Mailosaur API client
To allow you to easily test SMS messages in Playwright, Mailosaur provides an official Node.js library with everything you need to easily automate SMS testing.
Install the Mailosaur Node.js library via npm
npm install mailosaur
Import Mailosaur into your project
In order to connect to Mailosaur, you need an API key. You access your API key via in the account settings area.
In your tests, simply import the Mailosaur library, using your API key, at the top of your spec file:
import { test, expect } from "@playwright/test";
import MailosaurClient from "mailosaur";

const mailosaur = new MailosaurClient("YOUR_API_KEY_HERE");
Basic usage
The messages.get method automatically waits for the first SMS message to arrive that matches the search criteria you provide.
test("SMS notifications", async ({ page }) =&gt; {
  const serverId = "YOUR_SERVER_ID_HERE";
  const testPhoneNumber = "15551234444";

  // TODO Do something here that will trigger an SMS message to `testPhoneNumber`

  // Connect to Mailosaur, and wait for that SMS message to arrive
  const sms = await mailosaur.messages.get(serverId, {
    sentTo: testPhoneNumber,
  });

  expect(sms.text.body).toBe("Your order is on the way!");
});
Testing SMS with Playwright
Playwright users should use the official Node.js library for Mailosaur. Head over to our SMS testing guide for Node.js for examples on everyhing you could possibly want to test with Playwright, including:

Sender and recipient properties
SMS message content
Testing links
Testing verification codes


This guide shows you how to easily test SMS in Playwright and test frameworks like Playwright

SMS testing with Playwright and Mailosaur

Using the Mailosaur API you can write SMS tests using common frameworks like Cypress, Playwright, Selenium, and Robot Framework, as well as in popular languages, using our SDKs for SMS testing.
How it works
Testing SMS messages is as simple as:

Assigning a phone number to one of your servers.
Send SMS messages to that number, just as you normally would.
Use the Mailosaur API to create end-to-end tests using the extracted content.

Testing SMS messages
Using Mailosaur’s client libraries you can fetch SMS messages with just a few lines of code.
The code for testing SMS messages is almost identical to testing emails, so you can follow our guides and common test cases to learn more.

Learn how to use Mailosaur mobile phone numbers to create end-to-end tests that cover identity verification, alerting, promotional messages and more.

How to test SMS messages with Mailosaur

What is Cypress?
Cypress is an end-to-end testing framework that has won over developers and testers for its ease of use and flexibility. To use Cypress for your browser test automation, you’ll need to write your tests in JavaScript. Once your code is ready, you’ll be able to repeatedly run test cases using a real browser. 
What makes Cypress unique is its batteries-included approach: all the tools required for end-to-end testing are already part of the Cypress framework, and there’s no need for anything extra. Fewer tools to install means faster setup and more time to write tests. Because Cypress’s components are well-integrated, its tests are usually more stable than end-to-end tests using other frameworks. 
What is Mailosaur?
Mailosaur lets you test email and SMS messages as part of your end-to-end automated testing. This is important for websites and web apps that send an email (password resets, account setup, marketing emails, etc.) or SMS message (multi-factor authentication, verification, etc.) 
If you don’t already have one, you’ll need to create a free trial account. Once you’re in, familiarize yourself with sending email into Mailosaur. Once you have this working, you’re ready to start testing! 
This guide assumes that you already know how to test with Cypress, however if you’re just getting started, check out the official Cypress documentation.
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!
Get Started

Learn how to test email and SMS messages in Cypress, using Mailosaur.

Using Cypress for email or SMS testing

What is Ghost Inspector?
Ghost Inspector lets you create automated website tests and set up monitoring suites. It makes automated testing for websites and web apps easier, especially with its web test recorder, which allows you to easily record tests from right within your web browser.
As you’re here, there is a good chance you know about Ghost Inspector already, but if you don’t we highly recommend their official getting started guide and video.
What is Mailosaur?
Mailosaur lets you test email and SMS messages as part of your end-to-end automated testing. This is particular important for websites and web apps that send an email (password resets, account setup, marketing emails, etc.) or SMS message (multi-factor authentication, verification, etc.)
If you don’t already have one, you’ll need to create a free trial account. Once you’re in, familiarize yourself with sending email into Mailosaur. Once you have this working, you’re ready to start testing!
1. Get Started
Creating an account
Create a free trial account for Mailosaur via the website.
Once you have this, navigate to the API tab to find the following values:

Server ID - Servers act like projects, which group your tests together. You need this ID whenever you interact with a server via the API.
Server Domain - Every server has its own domain name. You’ll need this to send email to your server.
API Key - You can create an API key per server (recommended), or an account-level API key to use across your whole account. Learn more about API keys.

Test email addresses with Mailosaur
Mailosaur gives you an unlimited number of test email addresses - with no setup or coding required!
This is because every server uses a catch-all/wildcard pattern. Here’s what that means:

When you create an account, you are given a server.
Every server has its own Server Domain name (e.g. abc123.mailosaur.net)
Any email address that ends with @{YOUR_SERVER_DOMAIN} will work with Mailosaur without any special setup. For example:
build-423@abc123.mailosaur.net
john.smith@abc123.mailosaur.net
rAnDoM63423@abc123.mailosaur.net


You can create more servers when you need them. Each one will have its own domain name.

Can’t use test email addresses? You can also use SMTP to test email. By connecting your product or website to Mailosaur via SMTP, Mailosaur will catch all email your application sends, regardless of the email address.
Understanding the API
Because Ghost Inspector runs all your tests in the browser, we’re going to use Mailosaur.js (our client-side API library). This guide will take you through all the key use cases, but it’s worth remembering that the library is powered by the Mailosaur email &amp; SMS testing API. You can easily check out the API itself by looking at our API reference documentation or via our Postman or Insomnia collections:## 2. Create a new Ghost Inspector test suite
Navigate to Ghost Inspector, and create a new test suite. This is done by clicking New &gt; New suite in the top-right of the page.
Give your suite a name and create Create Suite.

3. Add steps that trigger an email
You now need some test steps that will cause an email to be sent from your website or product. As discussed above, you have an unlimited number of usage test email addresses with Mailosaur.
In this example, we will navigate to the Mailosaur Playground to mimic a real world product that has a password reset feature.
Ghost Inspector has an awesome browser extension to allow you to quickly record these steps yourself in the browser, but in this guide we’re going to do this manually, because that’s how we roll… 💪

Under Create new test, on the right of the screen, we type “Request Password Reset”.
Next, input the starting URL (in our example, that’s https://example.mailosaur.com/password-reset).
Click Create.

Next, add a step to fill in the email address on the password reset form. In the screenshot below you can see we use an Assign step to set the input field (#email) to our test email address of ghost-inspector@abc123.mailosaur.net. Note that abc123.mailosaur.net is our Server Domain (from step 1 above), and ghost-inspector is any string we want (you don’t need to create email addresses with Mailosaur).
Finally, add a step to submit the password reset request - a simple button click is all we need.


Running this test allows us to successfully request a password reset. But to complete the process, we next to find that email and follow the link inside it.
4. Find the email
Using Mailosaur.js in a web browser
Mailosaur has libraries to write tests in various languages. As Ghost Inspector runs in the browser, we need to use Mailosaur.js which allows us to do email and SMS testing from within a web browser.
To do this, 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.
Execute JavaScript to import the Mailosaur.js library
To pull Mailosaur.js into our Ghost Inspector test, add an Execute JavaScript step, with the following code:
(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');
Extract the email into a variable
Next, we need to find our email and extract the result into a variable that we can use else where in our Ghost Inspector suite.
To do this, add an Extract from JavaScript step, with the following code (note that we discussed the values to use for apiKey and serverId above):
return new Promise(function (resolve, reject) {
  const apiKey = 'YOUR_API_KEY';
  const serverId = 'abc123';

  const mailosaur = Mailosaur(apiKey);

  const promise = mailosaur.messages.get(serverId, {
    sentTo: 'ghost-inspector@abc123.mailosaur.net' 
  });

  promise.then(resolve).catch(reject);
})
In the Variable name field, type “message”.
Let’s break down what the code above actually does:

First, it is an async method, so Ghost Inspector requires that we first return a Promise.
Inside that, we set variables for our apiKey and serverId, the values for which we discussed above.
Finally, we have an async method that searches for the email we sent (using mailosaur.messages.get) and resolves the result.

In this example we are searching for our message using the sentTo option. You can search using any of the criteria described in the API reference.
5. Create an assertion step
Now that we have our email in a variable, we can start creating assertions. This can be done by adding a JavaScript returns true step in Ghost Inspector. For example, this will test the email’s subject line:
const email = {{message}};
return email.subject === 'Set your new password for ACME Product';
You’re now ready to write whatever tests you need. The rest of this guide will take you through some of the most common things you might want to test.
Testing plain text content
Most emails, and all SMS messages, should have a plain text body. Mailosaur exposes this content via the text.body property on an email or SMS message:
console.log(message.text.body) // "Hi Jason, ..."

if (message.text.body.indexOf('Jason') &gt; -1) {
  console.log('Email contains "Jason"')
}
Extracting verification codes from plain text
You may have an email or SMS message that contains an account verification code, or some other one-time passcode. You can extract content like this using a simple regex.
Here is how to extract a 6-digit numeric code:
console.log(message.text.body) // "Your access code is 243546."

const regEx = new RegExp('([0-9]{6})')
const matches = regEx.exec(message.text.body)

console.log(matches[0]) // "243546"
Testing HTML content
Most emails also have an HTML body, as well as the plain text content. You can access HTML content in a very similar way to plain text:
console.log(message.html.body) // "&lt;html&gt;&lt;head ..."
Working with hyperlinks
When an email is sent with an HTML body, Mailosaur automatically extracts any hyperlinks found within anchor (&lt;a&gt;) and area (&lt;area&gt;) elements and makes these available via the html.links array.
Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL:
// How many links?
console.log(message.html.links.length) // 2

const firstLink = message.html.links[0]
console.log(firstLink.text) // "Google Search"
console.log(firstLink.href) // "https://www.google.com/"
Important: To ensure you always have valid emails. Mailosaur only extracts links that have been correctly marked up with &lt;a&gt; or &lt;area&gt; tags.
Links in plain text (including SMS messages)
Mailosaur auto-detects links in plain text content too, which is especially useful for SMS testing:
// How many links?
console.log(message.text.links.length) // 2

const firstLink = message.text.links[0]
console.log(firstLink.href) // "https://www.google.com/"
Working with attachments
If your email includes attachments, you can access these via the attachments property:
// How many attachments?
console.log(message.attachments.length) // 2
Each attachment contains metadata on the file name and content type:
const firstAttachment = message.attachments[0]
console.log(firstAttachment.fileName) // "contract.pdf"
console.log(firstAttachment.contentType) // "application/pdf"
The length property returns the size of the attached file (in bytes):
const firstAttachment = message.attachments[0]
console.log(firstAttachment.length) // 4028
Working with images and web beacons
The html.images property of a message contains an array of images found within the HTML content of an email. The length of this array corresponds to the number of images found within an email:
// How many images in the email?
console.log(message.html.images.length) // 1
Remotely-hosted images
Emails will often contain many images that are hosted elsewhere, such as on your website or product. It is recommended to check that these images are accessible by your recipients.
All images should have an alternative text description, which can be checked using the alt attribute.
const image = message.html.images[0]
console.log(image.alt) // "Hot air balloon"
Triggering web beacons
A web beacon is a small image that can be used to track whether an email has been opened by a recipient.
Because a web beacon is simply another form of remotely-hosted image, you can export the src attribute via an Extract from JavaScript step, then navigate to that URL using Ghost Inspector:
const image = message.html.images[0]
return image.src // Extract this value, so you can navigate to it
Spam checking
You can perform a SpamAssassin check against an email. The structure returned matches the spam test object:
const result = await mailosaur.analysis.spam(message.id)

console.log(result.score) // 0.5

result.spamFilterResults.spamAssassin.forEach(r =&gt; {
  console.log(r.rule)
  console.log(r.description)
  console.log(r.score)
})


Test email and SMS with Ghost Inspector - the all-in-one website test and monitoring service and Mailosaur, the number one email and SMS testing service.

How to test email and SMS using Ghost Inspector

What is Insomnia?
Insomnia a free, cross-platform desktop application that makes it easy to test, interact with and design HTTP-based APIs.
At this stage, we assume that you already know how to use Insomnia, however if not, you can learn more on Insomnia’s website.
What is Mailosaur?
Mailosaur is a service that captures email and SMS messages and lets you test them, via it’s web dashboard and the Mailosaur email/SMS testing API.
If you don’t already have one, create a free account trial now, and send an email into Mailosaur first. Once you have this working, you’re ready to start testing!
1. Create an API key
Account-level API keys allow you to access all the functions described in the API reference, and have access to all the servers in your account.
To create an account-level API key, you must be an Administrator or Account Owner on the account in question.

Go to the Settings page in the Mailosaur Dashboard.
Go to the API Keys page.
Click the Create a Key button.
In the dialog that appears, enter a name for your key.
When you are finished, click Create.

For more information, see our guide on managing API keys.
2. Import the Insomnia Collection
Mailosaur has a public Insomnia Collection which you can access by clicking the button below:Alternatively, you can import the collection and start testing email and SMS by following these steps:

Open Insomnia.
Click the Create button, in the top right of the screen.
Select URL.
Type in the URL https://mailosaur.com/insomnia.json and click Fetch and Import.

3. Make API requests using your API key
Once you have the collection loaded, you just need to add your Mailosaur API key to your base environment variables.
This can be done by navigating the Manage Environments, then adding your Mailosaur API key as follows:

That’s it, you’re ready to start testing email and SMS messages with Mailosaur and Insomnia!

This article shows you how to test email and test SMS using Insomnia and the Mailosaur API.

How to test email and SMS with Insomnia

What is Playwright?
Playwright is a Node.js library that lets you automate modern web browsers. Playwright is made by Microsoft and is used as part of the Quality Assurance testing of Microsoft’s own service.
At this stage, we assume that you already know how to test with Playwright, however if you’re just getting started, check out the official Playwright guide, then come back here to start testing email and SMS!
What is Mailosaur?
Mailosaur is a service that captures email and SMS messages and lets you test them, both via it’s web dashboard and via the Mailosaur testing API.
If you don’t already have one, create a free account trial now, and send an email into Mailosaur first. Once you have this working, you’re ready to start testing!
Get Started

Learn how to test email and SMS messages in Playwright, using Mailosaur.

How to test email and SMS with Playwright

Before you begin
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!
1. Create an API key
Account-level API keys allow you to access all the functions described in the API reference, and have access to all the servers in your account.
To create an account-level API key, you must be an Administrator or Account Owner on the account in question.For more information, see our guide on managing API keys.
2. Fork the Mailosaur Postman Collection
Mailosaur has a public Postman Collection which you can access by clicking the button below:Once you have the collection loaded, simply enter your API key from step 1 above into the Authorization tab, by ensuring the Basic Auth type is selected, with your API key entered as the Username. Once this is done you’re ready to start calling the endpoints in the collection!

How to await a message using Postman
It can sometimes take a few seconds for a new email or SMS message to arrive in your inbox. This is why our official API clients automatically wait for new matches. Using the steps below, you can configure your Postman tests to &#39;poll&#39; until a new message arrives or a timeout is reached. 
Assuming you&#39;re running your tests as part of a Postman collection, you can do the following:

Add a single request to your collection that calls the search endpoint.
Edit the &#39;Tests&#39; tab for that request, and add the code shown below. This code checks the API response and calls the endpoint again if no matches are found.
Once you&#39;ve saved this, you can then go to your Postman collection and run it.

Important: Remember that the &#39;search&#39; endpoint only returns a message summary and does not include the body content of each message. To get this, you just need to follow this up with a call to the retrieve message endpoint using the message ID from the search response.
if (!pm.environment.has("maxWait")) {
    pm.environment.set("maxWait", 0);
}

const timeout = 10; // Max seconds to wait for
const maxWait = parseInt(pm.environment.get("maxWait"), 10);
const response = pm.response.json();
const messages = response?.items;

if ((messages &amp;&amp; messages.length &gt; 0) || maxWait &gt;= timeout) {
    pm.test("match should have expected subject", function () {
        pm.expect(messages[0].subject).to.eq("My expected email subject");
    });
} else {
    // Wait 1 second to avoid rate limiting
    setTimeout(() =&gt; {}, 1000);
    pm.environment.set("maxWait", maxWait + 1);
    postman.setNextRequest(request.name);
}


This article teaches you how to test email and SMS messages using Postman with the Mailosaur API.

How to test email and SMS with Postman

What is PowerShell?
PowerShell is a cross-platform task automation solution from Microsoft, made up of a command-line shell, a scripting language, and a configuration management framework. PowerShell runs on Windows, Linux, and macOS. It can be used for any kind of QA test automation.
As you are reading an article about testing email and SMS in PowerShell, you probably already know how to use it, however if you are new to PowerShell, we would recommend reading the official product documentation for PowerShell to get started.
What is Mailosaur?
Mailosaur is a service that allows you to capture and test email and SMS messages. This is crucial for products and websites that send out emails (such as password resets, account setup, marketing emails, etc.) or SMS messages (such as multi-factor authentication, verification, etc.)
With Mailosaur you get an unlimited supply of test email addresses, plus virtual SMTP servers, test SMS numbers to work with, and more - all accessible within your PowerShell scripts.
Get Started
Install and load the Mailosaur NuGet package
Install the latest version of the Mailosaur package from nuget:
install-package Mailosaur -source https://www.nuget.org/api/v2
Next, load the assembly into PowerShell:
$pkgZip = [System.IO.Compression.ZipFile]::Open((Get-Package Mailosaur).Source,"Read")
$pkgStream = [System.IO.MemoryStream]::new()
$pkgReader = [System.IO.StreamReader]($pkgZip.entries[2]).Open()
$pkgReader.BaseStream.CopyTo($pkgStream)
[byte[]]$pkgBytes = $pkgStream.ToArray()
$pkgReader.Close()
$pkgZip.dispose()
[System.Reflection.Assembly]::Load($pkgBytes)
Instantiate the Mailosaur client
You are now ready to start using the package. The value for YOUR_API_KEY is covered in the next step (creating an account):
$mailosaur = [Mailosaur.MailosaurClient]::new("YOUR_API_KEY")
API Reference
The .NET library is powered by the Mailosaur email &amp; SMS testing API. You can easily check out the API itself by looking at our API reference documentation or via our Postman or Insomnia collections:## 1. Create an account
Create a free trial account for Mailosaur, via the website.
Once you have this, navigate to the API tab to find the following values:

Server ID - Servers act like projects, which group your tests together. You need this ID whenever you interact with a server via the API.
Server Domain - Every server has its own domain name. You’ll need this to send email to your server.
API Key - You can create an API key per server (recommended), or an account-level API key to use across your whole account. Learn more about API keys.

2. Test email addresses with Mailosaur
Mailosaur gives you an unlimited number of test email addresses - with no setup or code required!
Here’s how it works:

When you create an account, you are given a server.
Every server has its own Server Domain name (e.g. abc123.mailosaur.net)
Any email address that ends with @{YOUR_SERVER_DOMAIN} will work with Mailosaur without any special setup. For example:
build-423@abc123.mailosaur.net
john.smith@abc123.mailosaur.net
rAnDoM63423@abc123.mailosaur.net


You can create more servers when you need them. Each one will have its own domain name.

Can’t use test email addresses? You can also use SMTP to test email. By connecting your product or website to Mailosaur via SMTP, Mailosaur will catch all email your application sends, regardless of the email address.
3. Find an email
Now that you have a sample project, your server’s credentials, and an email to test, then you’re ready to continue.
Open the file in your new project called Program.cs and type or paste in this code sample, replacing the template code with the values from step 3 above:
# Available in the API tab of a server
$apiKey = "YOUR_API_KEY"
$serverId = "SERVER_ID"
$serverDomain = "SERVER_DOMAIN"

$mailosaur = [Mailosaur.MailosaurClient]::new($apiKey)

# Wait for an email to arrive, matching this search criteria
$criteria = [Mailosaur.Models.SearchCriteria]::new()
$criteria.SentTo = "anything@" + $serverDomain
$message = $mailosaur.Messages.Get($serverId, $criteria);
Find an SMS message
Important: Trial accounts do not automatically have SMS access. Please contact our support team to enable a trial of SMS functionality.
If your account has SMS testing enabled, you can reserve phone numbers to test with, then use the Mailosaur API in a very similar way to when testing email:
# ...

$criteria = [Mailosaur.Models.SearchCriteria]::new()
$criteria.SentTo = "4471235554444"
$mailosaur.Messages.Get($serverId, $criteria);
Testing plain text content
Most emails, and all SMS messages, should have a plain text body. Mailosaur exposes this content via the Text.Body property on an email or SMS message:
$message.Text.Body # "Hello world."
Testing HTML content
Most emails also have an HTML body, as well as the plain text content. You can access HTML content in a very similar way to plain text:
$message.Html.Body # "&lt;html&gt;&lt;head ..."
Working with hyperlinks
When an email is sent with an HTML body, Mailosaur automatically extracts any hyperlinks found within anchor (&lt;a&gt;) and area (&lt;area&gt;) elements and makes these available via the Html.Links array.
Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL:
$message.Html.Links.Count # 2

# Accessing the HTML link content
$firstLink = $message.Html.Links[0]
$firstLink.Text # "Google Search"
$firstLink.Href # "https://www.google.com/"
Important: To ensure you always have valid emails. Mailosaur only extracts links that have been correctly marked up with &lt;a&gt; or &lt;area&gt; tags.
Links in plain text (including SMS messages)
Mailosaur auto-detects links in plain text content too, which is especially useful for SMS testing:
$message.Text.Links.Count # 1

# Accessing the HTML link content
$firstLink = $message.Text.Links[0]
$firstLink.Href # "https://www.google.com/"
Working with attachments
If your email includes attachments, you can access these via the Attachments property:
# How many attachments?
$message.Attachments # 2
Each attachment contains metadata on the file name and content type:
$firstAttachment = $message.Attachments[0]
$firstAttachment.FileName # "contract.pdf"
$firstAttachment.ContentType # "application/pdf"
The Length property returns the size of the attached file (in bytes):
$firstAttachment = $message.Attachments[0]
$firstAttachment.Length # 4028
Working with images and web beacons
The Html.Images property of a message contains an array of images found within the HTML content of an email. The length of this array corresponds to the number of images found within an email:
# How many images in the email?
$message.Html.Images.Count # 1
Remotely-hosted images
Emails will often contain many images that are hosted elsewhere, such as on your website or product. It is recommended to check that these images are accessible by your recipients.
All images should have an alternative text description, which can be checked using the Alt attribute.
$image = $message.Html.Images[0]
$image.Alt # "Hot air balloon"
Triggering web beacons
A web beacon is a small image that can be used to track whether an email has been opened by a recipient.
Because a web beacon is simply another form of remotely-hosted image, you can use the Src attribute to make an HTTP request to that address using Invoke-WebRequest:
$image = $message.Html.Images[0]
$image.Src # "https://example.com/s.png?abc123"

# Make an HTTP call to trigger the web beacon
Invoke-WebRequest -URI $image.Src
Spam checking
You can perform a SpamAssassin check against an email. The structure returned matches the spam test object:
$result = $mailosaur.Analysis.Spam($message.Id)

$result.Score # 0.5

foreach($r in $result.SpamFilterResults.SpamAssassin) {
  $r.Rule
  $r.Description
  $r.Score
}


Learn how to test email and SMS messages in PowerShell, using Mailosaur.

How to test email and SMS with PowerShell

What is Robot Framework?
Robot Framework is a Python-based open source automation framework. It can be used for any kind of QA test automation. Robot Framework is in active use by many industry-leading companies as part of their software development lifecycle.
As you are reading an article about testing email and SMS in Robot Framework, you probably already know how to use Robot Framework, however if you are new to it, we would recommend reading the Robot Framework website and documentation to get started.
What is Mailosaur?
Mailosaur is a service that allows you to capture and test email and SMS messages. This is crucial for products and websites that send out emails (such as password resets, account setup, marketing emails, etc.) or SMS messages (such as multi-factor authentication, verification, etc.)
With Mailosaur you get an unlimited supply of test email addresses, plus virtual SMTP servers, test SMS numbers to work with, and more - all accessible within your Robot Framework test suite.
1. Install the Mailosaur Python library
As Robot Framework is Python-based, you can use our official Python library to quickly start testing email and SMS messages.
Installation
Install the Mailosaur Python library with pip:
pip install --upgrade mailosaur
Create a Python file to contain the code you want to expose to Robot Framework, then import the library into it. The value for YOUR_API_KEY is covered in the next step (creating an account):
from mailosaur import MailosaurClient
mailosaur = MailosaurClient("YOUR_API_KEY")
API Reference
This library is powered by the Mailosaur API. You can easily check out the API itself by looking at our API reference documentation or via our Postman or Insomnia collections:## 2. Create an account
Create a free trial account for Mailosaur, via the website.
Once you have this, navigate to the API tab to find the following values:

Server ID - Servers act like projects, which group your tests together. You need this ID whenever you interact with a server via the API.
Server Domain - Every server has its own domain name. You’ll need this to send email to your server.
API Key - You can create an API key per server (recommended), or an account-level API key to use across your whole account. Learn more about API keys.

3. Test email addresses with Mailosaur
Mailosaur gives you an unlimited number of test email addresses - with no setup or code required!
Here’s how it works:

When you create an account, you are given a server.
Every server has its own Server Domain name (e.g. abc123.mailosaur.net)
Any email address that ends with @{YOUR_SERVER_DOMAIN} will work with Mailosaur without any special setup. For example:
build-423@abc123.mailosaur.net
john.smith@abc123.mailosaur.net
rAnDoM63423@abc123.mailosaur.net


You can create more servers when you need them. Each one will have its own domain name.

Can’t use test email addresses? You can also use SMTP to test email. By connecting your product or website to Mailosaur via SMTP, Mailosaur will catch all email your application sends, regardless of the email address.
4. Find an email
Create a helper class
First, we need to create a helper class, which we’ll name Mailosaur.py. This file will let you write helper methods that expose the functionality of the Mailosaur Python library as keywords within your Robot Framework tests:
from mailosaur import MailosaurClient
from mailosaur.models import SearchCriteria

class Mailosaur(object):
  def __init__(self):
    self.client = MailosaurClient("YOUR_API_KEY")

  def find_email(self, server_id, email_address):
    criteria = SearchCriteria()
    criteria.sent_to = email_address
    return self.client.messages.get(server_id, criteria)

  def subject_should_equal(self, message, expected):
    assert(message.subject == expected)
Use the helper class in a Robot Framework test spec
Now we can use the helper methods we created above, in our Robot Framework tests. Simply include Mailosaur.py as a Library:
*** Settings ***
Library           SeleniumLibrary
Library           Mailosaur.py

*** Variables ***
${URL}                https://example.mailosaur.com/password-reset
${SERVER_ID}					abc123 # Value from https://mailosaur.com/app/project/api 
${SERVER_DOMAIN}    	abc123.mailosaur.net # Value from https://mailosaur.com/app/project/api

*** Test Cases ***
Test Password Reset
    Request Password Reset

*** Keywords ***
Request Password Reset
    ${TEST_EMAIL_ADDRESS}=  some-random-string@${SERVER_DOMAIN}
    Open Browser  ${URL}
    Input Text    name:email    ${TEST_EMAIL_ADDRESS}
    Click Button  css:button[type=&quot;submit&quot;]
    ${MESSAGE}=     Mailosaur.find_email   ${SERVER_ID}    ${TEST_EMAIL_ADDRESS}
    Mailosaur.subject_should_equal    ${MESSAGE}      Thanks for joining!
    [Teardown]    Close Browser
Find an SMS message
Important: Trial accounts do not automatically have SMS access. Please contact our support team to enable a trial of SMS functionality.
If your account has SMS testing enabled, you can reserve phone numbers to test with, then use the Mailosaur API in a very similar way to when testing email:
# ...

criteria = SearchCriteria()
criteria.sent_to = "4471235554444"
return self.client.messages.get(server_id, criteria)
Testing plain text content
Most emails, and all SMS messages, should have a plain text body. Mailosaur exposes this content via the text.body property on an email or SMS message:
def message_text_contains(self, message, expected):
  assert(expected in message.text.body)
Extracting verification codes from plain text
You may have an email or SMS message that contains an account verification code, or some other one-time passcode. You can extract content like this using a simple regex.
Here is how to extract a 6-digit numeric code:
print(message.text.body) # "Your access code is 243546."

match = re.search("([0-9]{6})", message.text.body)
print(match.group()) # "243546"
Read more
Testing HTML content
Most emails also have an HTML body, as well as the plain text content. You can access HTML content in a very similar way to plain text:
print(message.html.body) # "&lt;html&gt;&lt;head ..."
Working with HTML using Beautiful Soup
If you need to traverse the HTML content of an email. For example, finding an element via a CSS selector, you can use the Beautiful Soup library.
pip install beautifulsoup4
from bs4 import BeautifulSoup

// ...

dom = BeautifulSoup(message.html.body, 'html.parser')

el = dom.find('.verification-code')
verification_code = el.text

print(verification_code) # "542163"
Read more
Working with hyperlinks
When an email is sent with an HTML body, Mailosaur automatically extracts any hyperlinks found within anchor (&lt;a&gt;) and area (&lt;area&gt;) elements and makes these available via the html.links array.
Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL:
def count_html_links(self, message, expected):
  # Passes if message has the expected number of links
  assert(expected in len(message.html.links))

  # Accessing the HTML link content
  first_link = message.html.links[0]
  print(first_link.text) # "Google Search"
  print(first_link.href) # "https://www.google.com/"
Important: To ensure you always have valid emails. Mailosaur only extracts links that have been correctly marked up with &lt;a&gt; or &lt;area&gt; tags.
Links in plain text (including SMS messages)
Mailosaur auto-detects links in plain text content too, which is especially useful for SMS testing:
def count_text_links(self, message, expected):
  # Passes if message has the expected number of links
  assert(expected in len(message.text.links))

  # Accessing the HTML link content
  first_link = message.text.links[0]
  print(first_link.href) # "https://www.google.com/"
Working with attachments
If your email includes attachments, you can access these via the attachments property:
# How many attachments?
print(len(message.attachments)) # 2
Each attachment contains metadata on the file name and content type:
first_attachment = message.attachments[0]
print(first_attachment.file_name) # "contract.pdf"
print(first_attachment.content_type) # "application/pdf"
The length property returns the size of the attached file (in bytes):
first_attachment = message.attachments[0]
print(first_attachment.length) # 4028
Working with images and web beacons
The html.images property of a message contains an array of images found within the HTML content of an email. The length of this array corresponds to the number of images found within an email:
# How many images in the email?
print(len(message.html.images)) # 1
Remotely-hosted images
Emails will often contain many images that are hosted elsewhere, such as on your website or product. It is recommended to check that these images are accessible by your recipients.
All images should have an alternative text description, which can be checked using the alt attribute.
image = message.html.images[0]
print(image.alt) # "Hot air balloon"
Triggering web beacons
A web beacon is a small image that can be used to track whether an email has been opened by a recipient.
Because a web beacon is simply another form of remotely-hosted image, you can use the src attribute to navigate to that address with Robot Framework. Alternatively use can use the requests library to make a direct HTTP request:
import requests

# ...

const image = message.html.images[0]
print(image.src) # "https://example.com/s.png?abc123"

# Make an HTTP call to trigger the web beacon
response = requests.get(image.src)
print(response.status_code) # 200
Spam checking
You can perform a SpamAssassin check against an email. The structure returned matches the spam test object:
result = mailosaur.analysis.spam(message.id)

print(result.score) # 0.5

for r in result.spam_filter_results.spam_assassin:
  print(r.rule)
  print(r.description)
  print(r.score)


Learn how to test email and SMS messages in Robot Framework, using Mailosaur.

How to test email and SMS with Robot Framework

What is Selenium?
Selenium is a hugely popular open-source tool that automates web browsers.
If you’ve never heard about Selenium, we’d recommend checking out the the Selenium website.
What is Mailosaur?
Mailosaur is a service that captures email and SMS messages and lets you test them, via it’s web dashboard and the Mailosaur email/SMS testing API.
If you don’t already have one, create a free account trial now, and send an email into Mailosaur first. Once you have this working, you’re ready to start testing!
1. Create an API key
Account-level API keys allow you to access all the functions described in the API reference, and have access to all the servers in your account.
To create an account-level API key, you must be an Administrator or Account Owner on the account in question.

Go to the Settings page in the Mailosaur Dashboard.
Go to the API Keys page.
Click the Create a Key button.
In the dialog that appears, enter a name for your key.
When you are finished, click Create.

For more information, see our guide on managing API keys.
2. Use the guide for your programming language
Selenium supports various languages. To begin integrating email and SMS into your Selenium tests, just follow the step-by-step guide for the language that applies to your Selenium setup:

Java
Python
C#
Ruby
Node.js


What is TestCafe?
TestCafe is an easy to use Node.js library for cross-browser testing. TestCafe does not require WebDriver or other testing software, meaning you can get up and running in seconds.
As you’re reading this, there is a good chance you know all about TestCafe, but if not, we definitely recommend checking out the TestCafe documentation to get up and running.
What is Mailosaur?
Mailosaur lets you automate email and SMS tests as part of your end-to-end QA. This is particularly important for websites and apps that send an email (password resets, account setup, marketing emails, etc.) or SMS message (multi-factor authentication, verification, etc.)
Mailosaur gives you an endless set of test email addresses, plus virtual SMTP servers, to use with TestCafe.
Get Started
Installation
Install the Mailosaur Node.js library via npm or yarn:
npm i -D mailosaur
# or
yarn add -D mailosaur
Then import the library into your code. The value for YOUR_API_KEY is covered in the next step (creating an account):
const MailosaurClient = require('mailosaur')
const mailosaur = new MailosaurClient('YOUR_API_KEY')
API Reference
This library is powered by the Mailosaur email &amp; SMS testing API. You can easily check out the API itself by looking at our API reference documentation or via our Postman or Insomnia collections:## Creating an account
Create a free trial account for Mailosaur via the website.
Once you have this, navigate to the API tab to find the following values:

Server ID - Servers act like projects, which group your tests together. You need this ID whenever you interact with a server via the API.
Server Domain - Every server has its own domain name. You’ll need this to send email to your server.
API Key - You can create an API key per server (recommended), or an account-level API key to use across your whole account. Learn more about API keys.

Test email addresses with Mailosaur
Mailosaur gives you an unlimited number of test email addresses - with no setup or coding required!
Here’s how it works:

When you create an account, you are given a server.
Every server has its own Server Domain name (e.g. abc123.mailosaur.net)
Any email address that ends with @{YOUR_SERVER_DOMAIN} will work with Mailosaur without any special setup. For example:
build-423@abc123.mailosaur.net
john.smith@abc123.mailosaur.net
rAnDoM63423@abc123.mailosaur.net


You can create more servers when you need them. Each one will have its own domain name.

Can’t use test email addresses? You can also use SMTP to test email. By connecting your product or website to Mailosaur via SMTP, Mailosaur will catch all email your application sends, regardless of the email address.
Find an email
In automated tests you will want to wait for a new email to arrive. This library makes that easy with the messages.get method. Here’s how you use it:
fixture `Mailosaur Example`
    .page `https://example.mailosaur.com/password-reset`;

test('Request a password reset', async t =&gt; {
    const MailosaurClient = require('mailosaur')
    const mailosaur = new MailosaurClient('API_KEY')

    // See https://mailosaur.com/app/project/api
    const serverId = 'abc123'
    const serverDomain = 'abc123.mailosaur.net'
    
    const testEmailAddress = `testcafe123@${serverDomain}`

    // Submit the password reset request
    await t
      .typeText('#email', testEmailAddress)
      .click('button[type="submit"]')

    const searchCriteria = {
      sentTo: testEmailAddress
    }

    const message = await mailosaur.messages.get(serverId, searchCriteria)

    await t.expect(message.subject)
      .eql('Set your new password for ACME Product')
})
What is this code doing?

Sets up an instance of MailosaurClient with your API key.
Waits for an email to arrive at the server with ID abc123.
Performs an assertion on the subject line of the email.

My email wasn’t found
First, check that the email you sent is visible in the Mailosaur Dashboard.
If it is, the likely reason is that by default, message.get only searches emails received by Mailosaur in the last 1 hour. You can override this behavior (see the receivedAfter option below), however we only recommend doing this during setup, as your tests will generally run faster with the default settings:
const email = await mailosaur.messages.get(
  serverId,
  searchCriteria,
  // Override receivedAfter to search all messages since Feb 1st
  { receivedAfter: new Date(2021, 1, 1) }
)
Find an SMS message
Important: Trial accounts do not automatically have SMS access. Please contact our support team to enable a trial of SMS functionality.
If your account has SMS testing enabled, you can reserve phone numbers to test with, then use the Mailosaur API in a very similar way to when testing email:
// ...

const searchCriteria = {
  sentTo: '4471235554444'
}

const sms = await mailosaur.messages.get(serverId, searchCriteria)

console.log(sms.text.body)
Testing plain text content
Most emails, and all SMS messages, should have a plain text body. Mailosaur exposes this content via the text.body property on an email or SMS message:
console.log(message.text.body) // "Hi Jason, ..."

if (message.text.body.indexOf('Jason') &gt; -1) {
  console.log('Email contains "Jason"')
}
Extracting verification codes from plain text
You may have an email or SMS message that contains an account verification code, or some other one-time passcode. You can extract content like this using a simple regex.
Here is how to extract a 6-digit numeric code:
console.log(message.text.body) // "Your access code is 243546."

const regEx = new RegExp('([0-9]{6})')
const matches = regEx.exec(message.text.body)

console.log(matches[0]) // "243546"
Read more
Testing HTML content
Most emails also have an HTML body, as well as the plain text content. You can access HTML content in a very similar way to plain text:
console.log(message.html.body) // "&lt;html&gt;&lt;head ..."
Working with HTML using JSDOM
If you need to traverse the HTML content of an email. For example, finding an element via a CSS selector, you can use the JSDOM library.
npm i -D jsdom
# or
yarn add -D jsdom
const { JSDOM } = require('jsdom')

// ...

const dom = new JSDOM(message.html.body);

const el = dom.window.document.querySelector('.verification-code');
const verificationCode = el.textContent; // "542163"
Read more
Working with hyperlinks
When an email is sent with an HTML body, Mailosaur automatically extracts any hyperlinks found within anchor (&lt;a&gt;) and area (&lt;area&gt;) elements and makes these available via the html.links array.
Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL:
// How many links?
console.log(message.html.links.length) // 2

const firstLink = message.html.links[0]
console.log(firstLink.text) // "Google Search"
console.log(firstLink.href) // "https://www.google.com/"
Important: To ensure you always have valid emails. Mailosaur only extracts links that have been correctly marked up with &lt;a&gt; or &lt;area&gt; tags.
Links in plain text (including SMS messages)
Mailosaur auto-detects links in plain text content too, which is especially useful for SMS testing:
// How many links?
console.log(message.text.links.length) // 2

const firstLink = message.text.links[0]
console.log(firstLink.href) // "https://www.google.com/"
Working with attachments
If your email includes attachments, you can access these via the attachments property:
// How many attachments?
console.log(message.attachments.length) // 2
Each attachment contains metadata on the file name and content type:
const firstAttachment = message.attachments[0]
console.log(firstAttachment.fileName) // "contract.pdf"
console.log(firstAttachment.contentType) // "application/pdf"
The length property returns the size of the attached file (in bytes):
const firstAttachment = message.attachments[0]
console.log(firstAttachment.length) // 4028
Writing an attachment to disk
const fs = require('fs')

// ...

const firstAttachment = message.attachments[1]

const fileBytes = await mailosaur.files.getAttachment(firstAttachment.id)
fs.writeFileSync(firstAttachment.fileName, fileBytes)
Working with images and web beacons
The html.images property of a message contains an array of images found within the HTML content of an email. The length of this array corresponds to the number of images found within an email:
// How many images in the email?
console.log(message.html.images.length) // 1
Remotely-hosted images
Emails will often contain many images that are hosted elsewhere, such as on your website or product. It is recommended to check that these images are accessible by your recipients.
All images should have an alternative text description, which can be checked using the alt attribute.
const image = message.html.images[0]
console.log(image.alt) // "Hot air balloon"
Triggering web beacons
A web beacon is a small image that can be used to track whether an email has been opened by a recipient.
Because a web beacon is simply another form of remotely-hosted image, you can use the src attribute to navigate to that address:
const image = message.html.images[0]
console.log(image.src) // "https://example.com/s.png?abc123"

// Make an HTTP call to trigger the web beacon
await t.page(image.src)
Spam checking
You can perform a SpamAssassin check against an email. The structure returned matches the spam test object:
const result = await mailosaur.analysis.spam(message.id)

console.log(result.score) // 0.5

result.spamFilterResults.spamAssassin.forEach(r =&gt; {
  console.log(r.rule)
  console.log(r.description)
  console.log(r.score)
})


End-to-end testing using TestCafe and email and SMS testing using Mailosaur. Learn how to use TestCafe together with the Mailosaur API.

How to test email and SMS with TestCafe

What is WebdriverIO?
WebdriverIO (sometimes shortened to wdio) is a browser and mobile automation test framework for Node.js. It lets users automate any application written with modern web frameworks such as React, Angular, Polymer or Vue.js, as well as native mobile applications.
If you’re reading this, you likely already know to use WebdriverIO, however, if you are just getting started, take a look at the awesome getting started guide on the WebdriverIO website.
What is Mailosaur?
Mailosaur is a test automation service that lets you test email and SMS messages in frameworks like WebdriverIO. Allowing you to create end-to-end tests for account creation, password reset requests, identity verification and more!
If you don’t already have one, create a free account trial now, and send an email into Mailosaur first. Once you have this working, you’re ready to start testing!
Get Started
Installation
Install the Mailosaur Node.js library via npm or yarn:
npm i -D mailosaur
# or
yarn add -D mailosaur
Then import the library into your code. The value for YOUR_API_KEY is covered in the next step (creating an account):
const MailosaurClient = require('mailosaur')
const mailosaur = new MailosaurClient('YOUR_API_KEY')
API Reference
The Node.js library is powered by the Mailosaur email &amp; SMS testing API. You can easily check out the API itself by looking at our API reference documentation or via our Postman or Insomnia collections:## Creating an account
Create a free trial account for Mailosaur via the signup page.
Once you have this, navigate to the API tab to find the following values:

Server ID - Servers act like projects, which group your tests together. You need this ID whenever you interact with a server via the API.
Server Domain - Every server has its own domain name. You’ll need this to send email to your server.
API Key - You can create an API key per server (recommended), or an account-level API key to use across your whole account. Learn more about API keys.

Test email addresses with Mailosaur
Mailosaur gives you an unlimited number of test email addresses to use with WebDriverIO - with no setup or coding required!
Here’s how it works:

When you create an account, you are given a server.
Every server has its own Server Domain name (e.g. abc123.mailosaur.net)
Any email address that ends with @{YOUR_SERVER_DOMAIN} will work with Mailosaur without any special setup. For example:
build-423@abc123.mailosaur.net
john.smith@abc123.mailosaur.net
rAnDoM63423@abc123.mailosaur.net


You can create more servers when you need them. Each one will have its own domain name.

Can’t use test email addresses? You can also use SMTP to test email. By connecting your product or website to Mailosaur via SMTP, Mailosaur will catch all email your application sends, regardless of the email address.
Find an email
In automated tests you will want to wait for a new email to arrive. This library makes that easy with the messages.get method. Here’s how you use it:
const { remote } = require('webdriverio');
const MailosaurClient = require('mailosaur')
const mailosaur = new MailosaurClient('API_KEY')

;(async () =&gt; {
    const browser = await remote({
        capabilities: {
            browserName: 'chrome'
        }
    })

    await browser.url('https://example.mailosaur.com/password-reset')

    // See https://mailosaur.com/app/project/api
    const serverId = 'abc123'
    const serverDomain = 'abc123.mailosaur.net'
    
    const testEmailAddress = `some-random-string@${serverDomain}`

    // Submit the password reset request
    const email = await browser.$('#email')
    email.setValue(testEmailAddress)

    const btn = await browser.$('button[type="submit"]')
    btn.click()

    const searchCriteria = {
      sentTo: testEmailAddress
    }

    const message = await mailosaur.messages.get(serverId, searchCriteria)

    console.log(message.subject)

    await browser.deleteSession()
})()
What is this code doing?

Sets up an instance of MailosaurClient with your API key.
Waits for an email to arrive at the server with ID abc123.
Performs an assertion on the subject line of the email.

My email wasn’t found
First, check that the email you sent is visible in the Mailosaur Dashboard.
If it is, the likely reason is that by default, message.get only searches emails received by Mailosaur in the last 1 hour. You can override this behavior (see the receivedAfter option below), however we only recommend doing this during setup, as your tests will generally run faster with the default settings:
const email = await mailosaur.messages.get(
  serverId,
  searchCriteria,
  // Override receivedAfter to search all messages since Feb 1st
  { receivedAfter: new Date(2021, 1, 1) }
)
Find an SMS message
Important: Trial accounts do not automatically have SMS access. Please contact our support team to enable a trial of SMS functionality.
If your account has SMS testing enabled, you can reserve phone numbers to test with, then use the Mailosaur API in a very similar way to when testing email:
// ...

const searchCriteria = {
  sentTo: '4471235554444'
}

const sms = await mailosaur.messages.get(serverId, searchCriteria)

console.log(sms.text.body)
Testing plain text content
Most emails, and all SMS messages, should have a plain text body. Mailosaur exposes this content via the text.body property on an email or SMS message:
console.log(message.text.body) // "Hi Jason, ..."

if (message.text.body.indexOf('Jason') &gt; -1) {
  console.log('Email contains "Jason"')
}
Extracting verification codes from plain text
You may have an email or SMS message that contains an account verification code, or some other one-time passcode. You can extract content like this using a simple regex.
Here is how to extract a 6-digit numeric code:
console.log(message.text.body) // "Your access code is 243546."

const regEx = new RegExp('([0-9]{6})')
const matches = regEx.exec(message.text.body)

console.log(matches[0]) // "243546"
Read more
Testing HTML content
Most emails also have an HTML body, as well as the plain text content. You can access HTML content in a very similar way to plain text:
console.log(message.html.body) // "&lt;html&gt;&lt;head ..."
Working with HTML using JSDOM
If you need to traverse the HTML content of an email. For example, finding an element via a CSS selector, you can use the JSDOM library.
npm i -D jsdom
# or
yarn add -D jsdom
const { JSDOM } = require('jsdom')

// ...

const dom = new JSDOM(message.html.body);

const el = dom.window.document.querySelector('.verification-code');
const verificationCode = el.textContent; // "542163"
Read more
Working with hyperlinks
When an email is sent with an HTML body, Mailosaur automatically extracts any hyperlinks found within anchor (&lt;a&gt;) and area (&lt;area&gt;) elements and makes these available via the html.links array.
Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL:
// How many links?
console.log(message.html.links.length) // 2

const firstLink = message.html.links[0]
console.log(firstLink.text) // "Google Search"
console.log(firstLink.href) // "https://www.google.com/"
Important: To ensure you always have valid emails. Mailosaur only extracts links that have been correctly marked up with &lt;a&gt; or &lt;area&gt; tags.
Links in plain text (including SMS messages)
Mailosaur auto-detects links in plain text content too, which is especially useful for SMS testing:
// How many links?
console.log(message.text.links.length) // 2

const firstLink = message.text.links[0]
console.log(firstLink.href) // "https://www.google.com/"
Working with attachments
If your email includes attachments, you can access these via the attachments property:
// How many attachments?
console.log(message.attachments.length) // 2
Each attachment contains metadata on the file name and content type:
const firstAttachment = message.attachments[0]
console.log(firstAttachment.fileName) // "contract.pdf"
console.log(firstAttachment.contentType) // "application/pdf"
The length property returns the size of the attached file (in bytes):
const firstAttachment = message.attachments[0]
console.log(firstAttachment.length) // 4028
Writing an attachment to disk
const fs = require('fs')

// ...

const firstAttachment = message.attachments[1]

const fileBytes = await mailosaur.files.getAttachment(firstAttachment.id)
fs.writeFileSync(firstAttachment.fileName, fileBytes)
Working with images and web beacons
The html.images property of a message contains an array of images found within the HTML content of an email. The length of this array corresponds to the number of images found within an email:
// How many images in the email?
console.log(message.html.images.length) // 1
Remotely-hosted images
Emails will often contain many images that are hosted elsewhere, such as on your website or product. It is recommended to check that these images are accessible by your recipients.
All images should have an alternative text description, which can be checked using the alt attribute.
const image = message.html.images[0]
console.log(image.alt) // "Hot air balloon"
Triggering web beacons
A web beacon is a small image that can be used to track whether an email has been opened by a recipient.
Because a web beacon is simply another form of remotely-hosted image, you can use the src attribute to navigate to that address:
const image = message.html.images[0]
console.log(image.src) // "https://example.com/s.png?abc123"

// Make an HTTP call to trigger the web beacon
await t.page(image.src)
Spam checking
You can perform a SpamAssassin check against an email. The structure returned matches the spam test object:
const result = await mailosaur.analysis.spam(message.id)

console.log(result.score) // 0.5

result.spamFilterResults.spamAssassin.forEach(r =&gt; {
  console.log(r.rule)
  console.log(r.description)
  console.log(r.score)
})
Library reference
Check out all of the methods available to the Mailosaur Node.js library.

Learn how to test email and SMS messages in WebdriverIO, using Mailosaur.

How to test email and SMS with WebdriverIO

Explore frameworks and tools for seamless email and SMS testing automation with Mailosaur. Dive into guides and API documentation to learn testing with Cypress, Ghost Inspector, Insomnia, Playwright, Postman, PowerShell, Robot Framework, Selenium, TestCafe, and WebdriverIO.

Frameworks and tools

Retrieve a messageDelete a messageList all messagesDelete all messagesSearch for messagesForward a messageReply to a messageSend an email

Explore the Messages API to list, search, view, modify, and create email and SMS messages in your Mailosaur account effortlessly.

Messages

Explore the Files API from Mailosaur, empowering you to effortlessly download files, including message attachments. Dive into examples and practical guidance.

Files

The Analysis API allows you to analyse messages in more detail. For example, running a SpamAssassin report.

Analysis

Retrieve one-time passwordList all devicesCreate a deviceRetrieve OTP for an existing deviceDelete a device

The Devices API allows you to generate one-time passwords (OTPs) and virtual security devices, for the purpose of testing authentication systems.

Devices

List all serversCreate a serverRetrieve a serverRetrieve server passwordUpdate a serverDelete a server

The Servers API allows you to list, view, create, and modify the servers that store your email and SMS messages.

Servers

Retrieve account limitsList usage transactions

The Usage API allows you to view your account limits, as well as list usage history to better understand how your Mailosaur account is utilized.

Usage

Overview
The Mailosaur API lets you test email using a simple REST API. You can make the API calls yourself, however because email and SMS messages can take time to arrive, we highly recommend using one of our official clients.Popular setups## Authentication
The Mailosaur API uses API keys to authenticate requests.
Authentication to the API is performed via HTTP Basic Auth. Your API key must be provided as the basic auth username value. You do not need to provide a password.
Your API keys carry many privileges, so always keep them secret and secure! Never share your API key in publicly-accessible areas such GitHub, client-side code, etc.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.### Managing API keys
You can manage all your API keys in the Mailosaur Dashboard.
Errors
HTTP Status Codes
Mailosaur uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Mailosaur’s servers (give us a shout in the unlikely event that you see one of those).



CODE
DESCRIPTION



200 OK
Request was successful.


204 No Content
Request was successful, no response content.


400 Bad Request
The request could not be handled, often due to missing a required parameter.


401 Unauthorized
No valid API key provided.


404 Not Found
The requested resource doesn’t exist.


5XX Server Errors
Something went wrong at Mailosaur. (Give us a shout).


Error handling
In case of an error the server will return as much information as possible. In the case of a 401 or 404 error the status code gives as much information as you’d need. But for 400 errors Mailosaur will return a JSON object containing the structure below.
Note that our client libraries convert responses to appropriate language-specific objects.



FIELD
DESCRIPTION



type
The type of error returned.


message
A human-readable message providing more details about the error.


parameters
A JSON object containing a key for each property name at fault, with a human-readable message per field.


model
The request model that was sent and failed to be processed.



Mailosaur Email and SMS Testing API for automated tests. Secure authentication with API keys, manage keys in the dashboard, and handle errors with detailed status codes and messages. Integrate effortlessly with popular setups like Nodejs, Cypress, Python, Java, .NET, Go, Ruby, and PHP.

Email and SMS Testing API

Whether you&#39;re using Playwright, Cypress, or any other Node.js setup, you can automate the testing of email, SMS, and multi-factor authentication with just a few lines of code.
Mailosaur has official libraries for most languages, including Node.js, as well as a Cypress plugin. Increasing your end-to-end test coverage couldn&#39;t be simpler.
Email and SMS Testing Guides

Learn how to test SMS or email using Node.js and Mailosaur.

Using Node.js to test email or SMS messages

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. Create a sample project
Install Python
To see if you already have Python installed, open a terminal window and run this command:
python --version
If Python is installed, you’ll see a version number. If you see an error instead, then download Python and install it.
Create a new project
Run each of these commands to create a new folder for your Python project:
mkdir EmailTests
cd EmailTests
Install the Mailosaur Python library
Run this command to install the Mailosaur Python package:
pip install mailosaur
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

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to test with.
Click on the API tab.
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:

Open up an email client and send an email to anything@example.mailosaur.net
Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you sent an email to.
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. Find an email for automated testing
Now that you have a sample project, your server’s credentials, and an email to test, then you’re ready to continue.
Create a file named hello.py and type or paste in this code sample, replacing the template code with the values from step 3 above:
from mailosaur import MailosaurClient
from mailosaur.models import SearchCriteria

# Available in the API tab of a server
api_key = "YOUR_API_KEY"
server_id = "SERVER_ID"
server_domain = "SERVER_DOMAIN"

mailosaur = MailosaurClient(api_key)

criteria = SearchCriteria()
criteria.sent_to = "anything@" + server_domain

email = mailosaur.messages.get(server_id, criteria)

print("Subject: " + email.subject)
This code connects to Mailosaur and looks for any email that has been sent to the address provided in the search criteria.
Save your changes and run the code:
python hello.py
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 received_after option (see library reference below).

5. 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:
test_start = datetime.today() - timedelta(minutes=1)

# Perform the steps that send a message here

criteria = SearchCriteria()
criteria.sent_to = "..."

message = mailosaur.messages.get("SERVER_ID", criteria, received_after=test_start)
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:



PARAMETER
DESCRIPTION



sent_from
The full email address from which the target message was sent.


sent_to
The full email address to which the target message was sent.


subject
Find emails where the subject line contains this text.


body
Finds messages where the message body contains this text.


6. 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 Python 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.
criteria = SearchCriteria()
criteria.sent_to = "someone@SERVER_ID.mailosaur.net"

message = mailosaur.messages.get("SERVER_ID", criteria)
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
Criteria



PARAMETER
DESCRIPTION



sent_from
The full email address from which the target message was sent.


sent_to
The full email address to which the target message was sent.


subject
The subject line of the target email.


body
Search for part of the message body.


match
If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.


Options



PARAMETER
DESCRIPTION



timeout
Specify how long to wait for a matching result (in milliseconds, default value is 10 seconds).


received_after
Limits results to only messages received after this date/time (default 1 hour ago).


from datetime import datetime, timedelta

# ...

criteria = SearchCriteria()
criteria.sent_to = "someone@SERVER_ID.mailosaur.net"
ten_minutes_ago = datetime.today() - timedelta(minutes=10)

# Search all messages received in the last 10 minutes
mailosaur.messages.get("SERVER_ID", criteria, received_after=ten_minutes_ago)
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call get_by_id. Alternatively, we recommend using the get method, which is a far more efficient approach.```python
List the most recent messages
result = mailosaur.messages.list(&#39;SERVER_ID&#39;)
Get the most recent message (the first one in the list)
message = result.items[0]
print(&#39;Subject: &#39; + message.subject)

##### Options
- **received_after** Allows you to customise how far back to look for messages.
- **page** Used alongside ```items_per_page``` to paginate through results. This is zero-based, meaning ```0``` is the first page of results.
- **items_per_page** A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50.

```python
from datetime import datetime, timedelta

# ...

ten_minutes_ago = datetime.today() - timedelta(minutes=10)

# List all results received in the last 10 minutes
result = mailosaur.messages.list(&#39;SERVER_ID&#39;, page=0, items_per_page=10, received_after=ten_minutes_ago)
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call get_by_id. Alternatively, we recommend using the get method, which is a far more efficient approach.```python
from mailosaur.models import SearchCriteria
...
criteria = SearchCriteria()
criteria.sent_to = &quot;someone@SERVER_ID.mailosaur.net&quot;
result = mailosaur.messages.search(&#39;SERVER_ID&#39;, criteria)
Get the most recent match
message = result.items[0]
print(&#39;Subject: &#39; + message.subject)

##### Criteria
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **sent_from** | The full email address from which the target message was sent. |
| **sent_to** | The full email address to which the target message was sent. |
| **subject** | The subject line of the target email. |
| **body** | Search for part of the message body. |
| **match** | If set to ```ALL``` (default), then only results that match all specified criteria will be returned. If set to ```ANY```, results that match any of the specified criteria will be returned. |

##### Options
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **timeout** | If provided, determines how long to wait for a matching result (provided in milliseconds). |
| **error_on_timeout** | When set to ```False```, an error will not be throw if timeout is reached (default: ```True```). |
| **received_after** | Allows you to customise how far back to look for messages. |
| **page** | Used alongside ```items_per_page``` to paginate through results. This is zero-based, meaning ```0``` is the first page of results. |
| **items_per_page** | A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50. |

```python
from mailosaur.models import SearchCriteria

# ...

criteria = SearchCriteria()
criteria.sent_to = &quot;someone@SERVER_ID.mailosaur.net&quot;

# Search for all messages sent to someone@SERVER_ID.mailosaur.net,
# received in the last 2 hours. Limit results to the first 10 matches only.
two_hours_ago=datetime.today() - timedelta(hours=2)
result = mailosaur.messages.search(&#39;SERVER_ID&#39;, criteria, page=0, items_per_page=10, received_after=two_hours_ago)
messages.get_by_id(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.
result = mailosaur.messages.list("SERVER_ID")
message_id = result.items[0].id

message = mailosaur.messages.get_by_id(message_id)

print('Subject: ' + message.subject)
messages.delete(id)
Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
mailosaur.messages.delete(message_id)
messages.delete_all(server)
Permanently deletes all messages held by the specified server. Also deletes any attachments related to each message. This operation cannot be undone.
mailosaur.messages.delete_all("SERVER_ID")
messages.create(server, options)
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.
from mailosaur.models import MessageCreateOptions

# ...

options = MessageCreateOptions()
options.to = "verified-address@example.com"
options.send = True
options.subject = "Request"
options.text = "Please can you give us a call back?"

mailosaur.messages.create("SERVER_ID", options)
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, options)
Forwards the specified email to a verified email address.
from mailosaur.models import MessageForwardOptions

# ...

options = MessageForwardOptions()
options.to = "verified-address@example.com"
options.text = "FYI"

mailosaur.messages.forward("MESSAGE_ID", options)
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, options)
Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails.
from mailosaur.models import MessageReplyOptions

# ...

options = MessageReplyOptions()
options.text = "FYI"

mailosaur.messages.reply("MESSAGE_ID", options)
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.
result = mailosaur.servers.list()

print('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.
from mailosaur.models import ServerCreateOptions

# ...

options = ServerCreateOptions("My email tests")
mailosaur.servers.create(options)
servers.get(id)
Retrieves the detail for a single server. Simply supply the unique identifier for the required server.
server = mailosaur.servers.get("SERVER_ID")
servers.get_password(id)
Retrieves the password, for use with SMTP and POP3, for a single server. Simply supply the unique identifier for the required server.
password = mailosaur.servers.get_password("SERVER_ID")
servers.update(id, server)
Updates a single server.
retrieved_server = mailosaur.servers.get("SERVER_ID")
retrieved_server.name = "Updated server name"

mailosaur.servers.update(retrieved_server.id, retrieved_server)
servers.delete(id)
Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.
mailosaur.servers.delete("SERVER_ID")
servers.generate_email_address(id)
Utility method to help you generate a random email address for a given server.
email_address = mailosaur.servers.generate_email_address("SERVER_ID")

print(email_address) # "bgwqj@SERVER_ID.mailosaur.net"
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
Files
files.get_email(message_id)
Downloads an EML file representing the specified email. Simply supply the unique identifier for the required email.
files.get_attachment(attachment_id)
Downloads a single attachment. Simply supply the unique identifier for the required attachment.
Analysis
analysis.spam(message_id)
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.

Automate test email and SMS in Python with Mailosaur code examples. Learn to send, retrieve, and search emails and SMS. Build comprehensive tests for content, attachments, and more.

How to test email and SMS in Python

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. Create a sample project
This guide makes use of JUnit, therefore create an empty Java &amp; JUnit project to begin.
Install the Mailosaur Java library
Gradle users can add this dependency to their project’s build file:
// MAILOSAUR_JAVA_VERSION available at:
// https://github.com/mailosaur/mailosaur-java/releases/latest)
implementation "com.mailosaur:mailosaur-java:MAILOSAUR_JAVA_VERSION"
Maven users should add this dependency to your project’s POM:
&lt;dependency&gt;
  &lt;groupId&gt;com.mailosaur&lt;/groupId&gt;
  &lt;artifactId&gt;mailosaur-java&lt;/artifactId&gt;
  &lt;version&gt;MAILOSAUR_JAVA_VERSION&lt;/version&gt;
&lt;/dependency&gt;
If you don’t use Gradle or Maven, refer to the README within the GitHub repository.
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

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to test with.
Click on the API tab.
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:

Open up an email client and send an email to anything@example.mailosaur.net
Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you sent an email to.
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. Find an email for automated testing
Now that you have a sample project, your server’s credentials, and an email to test, then you’re ready to continue.
Open the file containing tests in your new, sample project (e.g. AppTest.java) and type or paste in this code sample, replacing the template code with the values from step 3 above:
package demo;

import org.junit.Test;
import static org.junit.Assert.*;
import com.mailosaur.MailosaurClient;
import com.mailosaur.MailosaurException;
import com.mailosaur.models.*;
import java.io.IOException;

public class AppTest {
  @Test public void testExample() throws IOException, MailosaurException {
    // Available in the API tab of a server
    String apiKey = "YOUR_API_KEY";
    String serverId = "SERVER_ID";
    String serverDomain = "SERVER_DOMAIN";

    MailosaurClient mailosaur = new MailosaurClient(apiKey);

    MessageSearchParams params = new MessageSearchParams();
    params.withServer(serverId);

    SearchCriteria criteria = new SearchCriteria();
    criteria.withSentTo("asdas@" + serverDomain);

    Message message = mailosaur.messages().get(params, criteria);

    assertNotNull(message);
    assertEquals("My email 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.
Save your changes and run your tests.
If everything is set up correctly, you should see tests run and the subject line of the last email you sent will be checked.
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).

5. 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:
Date testStart = new Date();

// Perform the steps that send a message here

MessageSearchParams params = new MessageSearchParams();
params.withServer(serverId)
  .withReceivedAfter(testStart);

SearchCriteria criteria = new SearchCriteria();
criteria.withSentTo("...");

Message message = mailosaur.messages().get(params, criteria);
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:



PARAMETER
DESCRIPTION



withSentFrom
The full email address from which the target message was sent.


withSentTo
The full email address to which the target message was sent.


withSubject
Find emails where the subject line contains this text.


withBody
Finds messages where the message body contains this text.


6. 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 Java 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.
MessageSearchParams params = new MessageSearchParams();
params.withServer("SERVER_ID");

SearchCriteria criteria = new SearchCriteria();
criteria.withSentTo("someone@SERVER_ID.mailosaur.net");

Message message = mailosaur.messages().get(params, criteria);
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
Criteria



PARAMETER
DESCRIPTION



sentFrom
The full email address from which the target message was sent.


sentTo
The full email address to which the target message was sent.


subject
The subject line of the target email.


body
Search for part of the message body.


match
If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.


Options



PARAMETER
DESCRIPTION



timeout
Specify how long to wait for a matching result (in milliseconds, default value is 10 seconds).


receivedAfter
Limits results to only messages received after this date/time (default 1 hour ago).


MessageSearchParams params = new MessageSearchParams();
params.withServer("SERVER_ID")
  withReceivedAfter(new Date(2020, 1, 5));

SearchCriteria criteria = new SearchCriteria();
criteria.withSentTo("someone@SERVER_ID.mailosaur.net");

// Search all messages received after midnight on a specific date
Message message = mailosaur.messages().get(params, criteria);
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call getById. Alternatively, we recommend using the get method, which is a far more efficient approach.```java
// List the most recent messages
MessageListParams params = new MessageListParams();
params.withServer(&quot;SERVER_ID&quot;);
MessageListResult result = mailosaur.messages().list(params);
// Get the most recent message (the first one in the list)
MessageSummary message = result.items().get(0);
System.out.println(&quot;Subject: &quot; + 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```.

```java
// List all results received after midnight on a specific date
MessageListParams params = new MessageListParams();
params.withServer(&quot;SERVER_ID&quot;).withReceivedAfter(new Date(2020, 1, 3));
MessageListResult result = mailosaur.messages().list(params);
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call getById. Alternatively, we recommend using the get method, which is a far more efficient approach.```java
MessageSearchParams params = new MessageSearchParams();
params.withServer(&quot;SERVER_ID&quot;);
SearchCriteria criteria = new SearchCriteria();
criteria.withSentTo(&quot;someone@SERVER_ID.mailosaur.net&quot;);
MessageListResult result = mailosaur.messages().search(params, criteria);
// Get the most recent match
MessageSummary message = result.items().get(0);
System.out.println(&quot;Subject: &quot; + message.subject());

##### Criteria
- **sentFrom** The full email address from which the target message was sent.
- **sentTo** The full email address to which the target message was sent.
- **subject** The subject line of the target email.
- **body** Search for part of the message body.
- **match** If set to ```ALL``` (default), then only results that match all specified criteria will be returned. If set to ```ANY```, results that match any of the specified criteria will be returned.

##### Options
- **timeout** If provided, determines how long to wait for a matching result (provided in milliseconds).
- **errorOnTimeout** When set to ```false```, an error will not be throw if timeout is reached (default: ```true```).
- **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```.

```java
// Search for all messages sent to someone@SERVER_ID.mailosaur.net.
// Limit results to the first 10 matches only.
MessageSearchParams params = new MessageSearchParams();
params.withServer(&quot;SERVER_ID&quot;)
  .withPage(0)
  .withItemsPerPage(10);

MessageListResult result = mailosaur.messages().search(params, criteria);
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.
MessageListParams params = new MessageListParams();
params.withServer("SERVER_ID");
MessageListResult result = mailosaur.messages().list(params);
String messageId = result.items().get(0).id();

Message message = mailosaur.messages().getById(messageId);

System.out.println("Subject: " + message.subject());
messages.delete(id)
Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
mailosaur.messages().delete(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.
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.
MessageCreateOptions options = new MessageCreateOptions();
options.withTo("verified-address@example.com")
  .withSend(true)
  .withSubject("Request")
  .withText("Please can you give us a call back?");

mailosaur.messages().create("SERVER_ID", options);
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.
MessageForwardOptions options = new MessageForwardOptions();
options.withTo("verified-address@example.com")
  .withText("FYI");

mailosaur.messages().forward("MESSAGE_ID", options);
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.
MessageReplyOptions options = new MessageReplyOptions();
options.withText("FYI");

mailosaur.messages().reply("MESSAGE_ID", options);
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.
ServerListResult result = mailosaur.servers().list();

System.out.println("You have a server called: " + result.items().get(0).name());
servers.create(server)
Creates a new virtual server. Only the name property is required to create a new server via the API.
ServerCreateOptions options = new ServerCreateOptions().withName("My email tests");
mailosaur.servers().create(options);
servers.get(id)
Retrieves the detail for a single server. Simply supply the unique identifier for the required server.
Server server = 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.
String password = mailosaur.servers().getPassword("SERVER_ID");
servers.update(id, server)
Updates a single server.
Server retrievedServer = mailosaur.servers().get("SERVER_ID");
retrievedServer.withName("Updated server name");

mailosaur.servers().update(retrievedServer.id(), retrievedServer);
servers.del(id)
Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.
mailosaur.servers().delete("SERVER_ID");
servers.generateEmailAddress(id)
Utility method to help you generate a random email address for a given server.
String emailAddress = mailosaur.servers().generateEmailAddress("SERVER_ID");

System.out.println(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.

Learn how to automate email and SMS testing in Java with Mailosaur. Follow our step-by-step guide, create a sample project, and start writing tests.

How to test email and SMS in Java

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

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to test with.
Click on the API tab.
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:

Open up an email client and send an email to anything@example.mailosaur.net
Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you sent an email to.
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() =&gt; {
  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:



PARAMETER
DESCRIPTION



sentFrom
The full email address from which the target message was sent.


sentTo
The full email address to which the target message was sent.


subject
Find emails where the subject line contains this text.


body
Finds messages where the message body contains this text.


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



PARAMETER
DESCRIPTION



sentFrom
The full email address from which the target message was sent.


sentTo
The full email address to which the target message was sent.


subject
The subject line of the target email.


body
Search for part of the message body.


match
If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.


Options



PARAMETER
DESCRIPTION



timeout
Specify how long to wait for a matching result (in milliseconds, default value is 10 seconds).


receivedAfter
Limits results to only messages received after this date/time (default 1 hour ago).


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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call getById. Alternatively, we recommend using the get method, which is a far more efficient approach.```js
// List the most recent messages
const result = await mailosaur.messages.list(&#39;SERVER_ID&#39;);
// Get the most recent message (the first one in the list)
const message = result.items[0];
console.log(&#39;Subject:&#39;, 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```.

```js
// List all results received after midnight on 3rd Feb 2020
const result = await mailosaur.messages.list(&#39;SERVER_ID&#39;, {
  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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call getById. Alternatively, we recommend using the get method, which is a far more efficient approach.```js
const result = await mailosaur.messages.search(&#39;SERVER_ID&#39;, {
  sentTo: &#39;someone@SERVER_ID.mailosaur.net&#39;
});
// Get the most recent match
const message = result.items[0];
console.log(&#39;Subject:&#39;, message.subject);

##### Criteria
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **sentFrom** | The full email address from which the target message was sent. |
| **sentTo** | The full email address to which the target message was sent. |
| **subject** | The subject line of the target email. |
| **body** | Search for part of the message body. |
| **match** | If set to ```ALL``` (default), then only results that match all specified criteria will be returned. If set to ```ANY```, results that match any of the specified criteria will be returned. |

##### Options
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **timeout** | If provided, determines how long to wait for a matching result (provided in milliseconds). |
| **errorOnTimeout** | When set to ```false```, an error will not be throw if timeout is reached (default: ```true```). |
| **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```. |

```js
// 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(&#39;SERVER_ID&#39;, {
  sentTo: &#39;someone@SERVER_ID.mailosaur.net&#39;
}, {
  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.

Automate the testing of email and SMS messages within your web browser, using Mailosaur.

How to test email and SMS with JavaScript

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. Create a sample project
Install .NET
To see if you already have .NET installed, open a terminal window and run this command:
dotnet --version
If .NET is installed, you’ll see a version number. If you see an error instead, then download .NET from Microsoft and install it.
Create a new project
Run each of these commands to create a new .NET project:
mkdir EmailTests
cd EmailTests
dotnet new console
Install the Mailosaur .NET library
Run this command to install the Mailosaur NuGet package:
dotnet add package mailosaur
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

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to test with.
Click on the API tab.
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:

Open up an email client and send an email to anything@example.mailosaur.net
Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you sent an email to.
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. Find an email for automated testing
Now that you have a sample project, your server’s credentials, and an email to test, then you’re ready to continue.
Open the file in your new project called Program.cs and type or paste in this code sample, replacing the template code with the values from step 3 above:
using System;
using Mailosaur;
using Mailosaur.Models;

namespace EmailTests
{
  class Program
  {
    static void Main(string[] args)
    {
      // Available in the API tab of a server
      var apiKey = "YOUR_API_KEY";
      var serverId = "SERVER_ID";
      var serverDomain = "SERVER_DOMAIN";

      var mailosaur = new MailosaurClient(apiKey);

      // Wait for an email to arrive, matching this search criteria
      var criteria = new SearchCriteria() {
          SentTo = "anything@" + serverDomain
      };
      var email = mailosaur.Messages.Get(serverId, criteria);

      // If we have an email, print the subject
      Console.WriteLine("Subject: " + email.Subject);
    }
  }
}
This code connects to Mailosaur and looks for any email that has been sent to the address provided in the search criteria.
Save your changes and run the code:
dotnet run
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).

5. 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:
var testStart = new Date();

// Perform the steps that send a message here

var criteria = new SearchCriteria() {
  SentTo = "..."
};

var message = mailosaur.Messages.Get(
  "SERVER_ID",
  criteria,
  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:



PARAMETER
DESCRIPTION



SentFrom
The full email address from which the target message was sent.


SentTo
The full email address to which the target message was sent.


Subject
Find emails where the subject line contains this text.


Body
Finds messages where the message body contains this text.


6. 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 .NET 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.
This is the most efficient method of looking up a message, therefore we recommend using it whenever possible.
var message = mailosaur.Messages.Get("SERVER_ID", new SearchCriteria() {
  SentTo = "someone@SERVER_ID.mailosaur.net"
});
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
Criteria



PARAMETER
DESCRIPTION



SentFrom
The full email address from which the target message was sent.


SentTo
The full email address to which the target message was sent.


Subject
The subject line of the target email.


Body
Search for part of the message body.


Match
If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.


Options



PARAMETER
DESCRIPTION



timeout
Specify how long to wait for a matching result (in milliseconds, default value is 10 seconds).


receivedAfter
Limits results to only messages received after this date/time (default 1 hour ago).


// Search all messages received after midnight on a specific
var message = mailosaur.Messages.Get("SERVER_ID", new SearchCriteria() {
  SentTo = "someone@SERVER_ID.mailosaur.net"
}, receivedAfter: new DateTime(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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call GetById. Alternatively, we recommend using the Get method, which is a far more efficient approach.```csharp
// List the most recent messages
var result = mailosaur.Messages.List(&quot;SERVER_ID&quot;);
// Get the most recent message (the first one in the list)
var message = result.Items[0];
Console.WriteLine(&quot;Subject: &quot; + 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```.

```csharp
// List all results received after midnight on a specific date
// Limit results to the first 10 matches only.
var result = mailosaur.Messages.List(&quot;SERVER_ID&quot;, 0, 10, new DateTime(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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call GetById. Alternatively, we recommend using the Get method, which is a far more efficient approach.```csharp
var result = mailosaur.Messages.Search(&quot;SERVER_ID&quot;, new SearchCriteria() {
  SentTo = &quot;someone@SERVER_ID.mailosaur.net&quot;
});
// Get the most recent match
var message = result.Items[0];
Console.WriteLine(&quot;Subject: &quot; + message.Subject);

##### Criteria
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **sentFrom** | The full email address from which the target message was sent. |
| **sentTo** | The full email address to which the target message was sent. |
| **subject** | The subject line of the target email. |
| **body** | Search for part of the message body. |
| **match** | If set to ```ALL``` (default), then only results that match all specified criteria will be returned. If set to ```ANY```, results that match any of the specified criteria will be returned. |

##### Options
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **timeout** | If provided, determines how long to wait for a matching result (provided in milliseconds). |
| **errorOnTimeout** | When set to ```false```, an error will not be throw if timeout is reached (default: ```true```). |
| **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```. |

```csharp
// Search for all messages sent to someone@SERVER_ID.mailosaur.net,
// received after midnight on a specific date. Limit results to
// the first 10 matches only.
var result = mailosaur.Messages.Search(&quot;SERVER_ID&quot;, new SearchCriteria() {
  SentTo = &quot;someone@SERVER_ID.mailosaur.net&quot;
}, page: 0, itemsPerPage: 10, receivedAfter: new DateTime(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.
var result = mailosaur.Messages.List("SERVER_ID");
var messageId = result.Items[0].Id;

var message = mailosaur.Messages.GetById(messageId);

Console.WriteLine("Subject: " + message.Subject);
Messages.Delete(id)
Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
mailosaur.Messages.Delete(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.
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.
mailosaur.Messages.Create("SERVER_ID", new MessageCreateOptions() {
  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.
mailosaur.Messages.Forward("MESSAGE_ID", new MessageForwardOptions() {
  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.
mailosaur.Messages.Reply("MESSAGE_ID", new MessageReplyOptions() {
  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.
ServerListResult result = mailosaur.Servers.List();

Console.WriteLine("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.
var options = new ServerCreateOptions("My email tests");
mailosaur.Servers.Create(options);
Servers.Get(id)
Retrieves the detail for a single server. Simply supply the unique identifier for the required server.
var server = 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.
var password = mailosaur.Servers.GetPassword("SERVER_ID");
Servers.Update(id, server)
Updates a single server.
var retrievedServer = mailosaur.Servers.Get("SERVER_ID");
retrievedServer.Name = "Updated server name";

mailosaur.Servers.Update(retrievedServer.Id, retrievedServer);
Servers.Delete(id)
Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.
mailosaur.Servers.Delete("SERVER_ID");
Servers.GenerateEmailAddress(id)
Utility method to help you generate a random email address for a given server.
var emailAddress = mailosaur.Servers.GenerateEmailAddress("SERVER_ID");

Console.WriteLine(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.

Automated testing for email and SMS in .NET with Mailosaur. Step-by-step guidance, sample projects, troubleshooting, and advanced search techniques

How to test email and SMS in .NET

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. Create a sample project
Install Ruby
To see if you already have Ruby installed, open a terminal window and run this command:
ruby --version
If Ruby is installed, you’ll see a version number. If you see an error instead, then download Ruby and install it.
Create a new project
Run each of these commands to create a new folder for your Ruby project:
mkdir EmailTests
cd EmailTests
Install the Mailosaur Ruby library
Run this command to install the Mailosaur Ruby package:
gem install mailosaur
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

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to test with.
Click on the API tab.
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:

Open up an email client and send an email to anything@example.mailosaur.net
Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you sent an email to.
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. Find an email for automated testing
Now that you have a sample project, your server’s credentials, and an email to test, then you’re ready to continue.
Create a file named hello.rb and type or paste in this code sample, replacing the template code with the values from step 3 above:
require 'mailosaur'

# Available in the API tab of a server
api_key = "YOUR_API_KEY"
server_id = "SERVER_ID"
server_domain = "SERVER_DOMAIN"

mailosaur = Mailosaur::MailosaurClient.new(api_key)

criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = "anything@" + server_domain

email = mailosaur.messages.get(server_id, criteria)

print("Subject: " + email.subject)
This code connects to Mailosaur and looks for any email that has been sent to the address provided in the search criteria.
Save your changes and run the code:
ruby hello.rb
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 received_after option (see library reference below).

5. 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 received_after option.
This example shows you how to only include emails received after your test started:
test_start = DateTime.now

# Perform the steps that send a message here

criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = '...'

message = mailosaur.messages.get('SERVER_ID', criteria, received_after: test_start)
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:



PARAMETER
DESCRIPTION



sent_from
The full email address from which the target message was sent.


sent_to
The full email address to which the target message was sent.


subject
Find emails where the subject line contains this text.


body
Finds messages where the message body contains this text.


6. 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 Ruby 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 whenever possible.
criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = "someone@SERVER_ID.mailosaur.net"

message = mailosaur.messages.get("SERVER_ID", criteria)
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
Criteria



PARAMETER
DESCRIPTION



sent_from
The full email address from which the target message was sent.


sent_to
The full email address to which the target message was sent.


subject
The subject line of the target email.


body
Search for part of the message body.


match
If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.


Options



PARAMETER
DESCRIPTION



timeout
Specify how long to wait for a matching result (in milliseconds, default value is 10 seconds).


received_after
Limits results to only messages received after this date/time (default 1 hour ago).


criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = "someone@SERVER_ID.mailosaur.net"
ten_minutes_ago = DateTime.now - (10 / 1440.0)

# Search all messages received in the last 10 minutes
message = mailosaur.messages.get("SERVER_ID", criteria, received_after: ten_minutes_ago)
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call get_by_id. Alternatively, we recommend using the get method, which is a far more efficient approach.```ruby
List the most recent messages
result = mailosaur.messages.list(&quot;SERVER_ID&quot;)
Get the most recent message (the first one in the list)
message = result.items[0]
print(&#39;Subject: &#39; + message.subject)

##### Options
- **received_after** 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.
- **items_per_page** A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50.

```ruby
ten_minutes_ago = DateTime.now - (10 / 1440.0)

# List all results received in the last 10 minutes.
# Limit results to the first 10 matches only.
result = mailosaur.messages.list(&quot;SERVER_ID&quot;, page: 0, items_per_page: 10, received_after: ten_minutes_ago)
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call get_by_id. Alternatively, we recommend using the get method, which is a far more efficient approach.```ruby
criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = &quot;someone@SERVER_ID.mailosaur.net&quot;
result = mailosaur.messages.search(&quot;SERVER_ID&quot;, criteria)
Get the most recent match
message = result.items[0]
print(&#39;Subject: &#39; + message.subject)

##### Criteria
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **sent_from** | The full email address from which the target message was sent. |
| **sent_to** | The full email address to which the target message was sent. |
| **subject** | The subject line of the target email. |
| **body** | Search for part of the message body. |
| **match** | If set to ```ALL``` (default), then only results that match all specified criteria will be returned. If set to ```ANY```, results that match any of the specified criteria will be returned. |

##### Options
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **timeout** | If provided, determines how long to wait for a matching result (provided in milliseconds). |
| **error_on_timeout** | When set to ```false```, an error will not be throw if timeout is reached (default: ```true```). |
| **received_after** | 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. |
| **items_per_page** | A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50. |

```ruby
criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = &quot;someone@SERVER_ID.mailosaur.net&quot;

# Search for all messages sent to someone@SERVER_ID.mailosaur.net,
# received in the last 2 hours. Limit results to the first 10 matches only.
two_hours_ago = DateTime.now - (2 / 24.0)
result = mailosaur.messages.search(&quot;SERVER_ID&quot;, criteria, page: 0, items_per_page: 10, received_after: two_hours_ago)
messages.get_by_id(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.
result = mailosaur.messages.list("SERVER_ID")
message_id = result.items[0].id

message = mailosaur.messages.get_by_id(message_id)

print('Subject: ' + message.subject)
messages.delete(id)
Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
mailosaur.messages.delete(message_id)
messages.delete_all(server)
Permanently deletes all messages held by the specified server. Also deletes any attachments related to each message. This operation cannot be undone.
mailosaur.messages.delete_all("SERVER_ID")
messages.create(server, options)
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.
options = Mailosaur::Models::MessageCreateOptions.new()
options.to = 'verified-address@example.com'
options.send = true
options.subject = 'Request'
options.text = 'Please can you give us a call back?'

mailosaur.messages.create('SERVER_ID', options)
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, options)
Forwards the specified email to a verified email address.
options = Mailosaur::Models::MessageForwardOptions.new()
options.to = 'verified-address@example.com'
options.text = 'FYI'

mailosaur.messages.forward('MESSAGE_ID', options)
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, options)
Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails.
options = Mailosaur::Models::MessageReplyOptions.new()
options.text = 'FYI'

mailosaur.messages.reply('MESSAGE_ID', options)
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.
result = mailosaur.servers.list()

print('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.
create_options = Mailosaur::Models::ServerCreateOptions.new()
create_options.name = "My email tests"

mailosaur.servers.create(create_options)
servers.get(id)
Retrieves the detail for a single server. Simply supply the unique identifier for the required server.
server = mailosaur.servers.get("SERVER_ID")
servers.get_password(id)
Retrieves the password, for use with SMTP and POP3, for a single server. Simply supply the unique identifier for the required server.
password = mailosaur.servers.get_password("SERVER_ID")
servers.update(id, server)
Updates a single server.
retrieved_server = mailosaur.servers.get("SERVER_ID")
retrieved_server.name = "Updated server name"

mailosaur.servers.update(retrieved_server.id, retrieved_server)
servers.delete(id)
Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.
mailosaur.servers.delete("SERVER_ID")
servers.generate_email_address(id)
Utility method to help you generate a random email address for a given server.
email_address = mailosaur.servers.generate_email_address("SERVER_ID")

print(email_address) # "bgwqj@SERVER_ID.mailosaur.net"
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
Files
files.get_email(message_id)
Downloads an EML file representing the specified email. Simply supply the unique identifier for the required email.
files.get_attachment(attachment_id)
Downloads a single attachment. Simply supply the unique identifier for the required attachment.
Analysis
analysis.spam(message_id)
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.

Learn how to automate test email and SMS messages in Ruby, using Mailosaur.

How to test email and SMS in Ruby

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. Create a sample project
Install PHP
To see if you already have PHP installed, open a terminal window and run this command:
php --version
If PHP is installed, you’ll see a version number. If you see an error instead, then download PHP and install it.
Create a new project
Run each of these commands to create a new folder for your PHP project:
mkdir EmailTests
cd EmailTests
Install the Mailosaur PHP library
Run this command to install the Mailosaur PHP package:
composer require mailosaur/mailosaur
If you don’t have composer installed, download and install it here.
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

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to test with.
Click on the API tab.
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:

Open up an email client and send an email to anything@example.mailosaur.net
Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you sent an email to.
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. Find an email for automated testing
Now that you have a sample project, your server’s credentials, and an email to test, then you’re ready to continue.
Create a file named hello.php and type or paste in this code sample, replacing the template code with the values from step 3 above:
&lt;?php

require_once('vendor/autoload.php');

use Mailosaur\MailosaurClient;
use Mailosaur\Models\SearchCriteria;

// Available in the API tab of a server
$apiKey = 'YOUR_API_KEY';
$serverId = 'SERVER_ID';
$serverDomain = 'SERVER_DOMAIN';

$mailosaur = new MailosaurClient($apiKey);

$criteria = new SearchCriteria();
$criteria-&gt;sentTo = 'anything@' . $serverDomain;

$email = $mailosaur-&gt;messages-&gt;get($serverId, $criteria);

print('Subject: ' . $email-&gt;subject);

?&gt;
This code connects to Mailosaur and looks for any email that has been sent to the address provided in the search criteria.
Save your changes and run the code:
php hello.php
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 received_after option (see library reference below).

5. Narrowing your search results
Only find messages received after a certain time
By default, searches include messages received in the last hour, but you can customise the search window with the received_after option.
This example shows you how to only include emails received after your test started:
$testStart = new \DateTime();

// Perform the steps that send a message here

$criteria = new SearchCriteria();
$criteria-&gt;sentTo = '...';

$message = $mailosaur-&gt;messages-&gt;get(
  '...',
  $criteria,
  10000, // Wait for up to 10 seconds
  $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:



PARAMETER
DESCRIPTION



sentFrom
The full email address from which the target message was sent.


sentTo
The full email address to which the target message was sent.


subject
Find emails where the subject line contains this text.


body
Finds messages where the message body contains this text.


6. 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 PHP 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-&gt;get(server, criteria, timeout, receivedAfter)
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.
$criteria = new SearchCriteria();
$criteria-&gt;sentTo = 'someone@SERVER_ID.mailosaur.net';

$message = $mailosaur-&gt;messages-&gt;get('SERVER_ID', $criteria);
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
Criteria



PARAMETER
DESCRIPTION



sentFrom
The full email address from which the target message was sent.


sentTo
The full email address to which the target message was sent.


subject
The subject line of the target email.


body
Search for part of the message body.


match
If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.


Options



PARAMETER
DESCRIPTION



timeout
Specify how long to wait for a matching result (in milliseconds, default value is 10 seconds).


receivedAfter
Limits results to only messages received after this date/time (default 1 hour ago).


$criteria = new SearchCriteria();
$criteria-&gt;sentTo = 'someone@SERVER_ID.mailosaur.net';

$tenMinutesAgo = new \DateTime();
$tenMinutesAgo-&gt;sub(new \DateInterval('PT10M'));

# Search all messages received in the last 10 minutes (with 10s timeout)
$message = $mailosaur-&gt;messages-&gt;get('SERVER_ID', $criteria, 10000, $tenMinutesAgo);
messages-&gt;all(server, page, itemsPerPage, receivedAfter)
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call getById. Alternatively, we recommend using the get method, which is a far more efficient approach.```php
List the most recent messages
$result = $mailosaur-&gt;messages-&gt;all(&#39;SERVER_ID&#39;);
Get the most recent message (the first one in the list)
$message = $result-&gt;items[0];
print(&#39;Subject: &#39; . $message-&gt;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```.

```php
$tenMinutesAgo = new \DateTime();
$tenMinutesAgo-&gt;sub(new \DateInterval(&#39;PT10M&#39;));

# List all results received in the last 10 minutes.
# Limit results to the first 10 matches only.
$result = $mailosaur-&gt;messages-&gt;all(&#39;SERVER_ID&#39;, 0, 10, $tenMinutesAgo);
messages-&gt;search(server, criteria, page, itemsPerPage, timeout, receivedAfter)
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call getById. Alternatively, we recommend using the get method, which is a far more efficient approach.```php
$criteria = new SearchCriteria();
$criteria-&gt;sentTo = &#39;someone@SERVER_ID.mailosaur.net&#39;;
$result = $mailosaur-&gt;messages-&gt;search(&#39;SERVER_ID&#39;, $criteria);
Get the most recent match
$message = $result-&gt;items[0];
print(&#39;Subject: &#39; . $message-&gt;subject);

##### Criteria
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **sentFrom** | The full email address from which the target message was sent. |
| **sentTo** | The full email address to which the target message was sent. |
| **subject** | The subject line of the target email. |
| **body** | Search for part of the message body. |
| **match** | If set to ```ALL``` (default), then only results that match all specified criteria will be returned. If set to ```ANY```, results that match any of the specified criteria will be returned. |

##### Options
| PARAMETER | DESCRIPTION |
| ------------ | ------------ |
| **timeout** | If provided, determines how long to wait for a matching result (provided in milliseconds). |
| **errorOnTimeout** | When set to ```false```, an error will not be throw if timeout is reached (default: ```true```). |
| **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```. |

```php
$criteria = new SearchCriteria();
$criteria-&gt;sentTo = &#39;someone@SERVER_ID.mailosaur.net&#39;;

# Search for all messages sent to someone@SERVER_ID.mailosaur.net,
# received in the last 2 hours. Limit results to the first 10 matches only.
$twoHoursAgo = new \DateTime();
$twoHoursAgo-&gt;sub(new \DateInterval(&#39;PT2H&#39;));

$result = $mailosaur-&gt;messages-&gt;search(&#39;SERVER_ID&#39;, $criteria, 0, 10, null, $twoHoursAgo);
messages-&gt;getById(id)
Retrieves the detail for a single email message. Must be used in conjunction with either all or search in order to get the unique identifier for the required message. We always recommend using the get method instead.
$result = $mailosaur-&gt;messages-&gt;all('SERVER_ID');
$messageId = $result-&gt;items[0]-&gt;id;

$message = $mailosaur-&gt;messages-&gt;getById($messageId);

print('Subject: ' . $message-&gt;subject);
messages-&gt;delete(id)
Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
$mailosaur-&gt;messages-&gt;delete($messageId);
messages-&gt;deleteAll(server)
Permanently deletes all messages held by the specified server. Also deletes any attachments related to each message. This operation cannot be undone.
$mailosaur-&gt;messages-&gt;deleteAll('SERVER_ID');
messages-&gt;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.
$options = new MessageCreateOptions();
$options-&gt;to = 'verified-address@example.com';
$options-&gt;send = TRUE;
$options-&gt;subject = 'Request';
$options-&gt;text = 'Please can you give us a call back?';

$mailosaur-&gt;messages-&gt;create('SERVER_ID', $options);
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-&gt;forward(messageId, messageForwardOptions)
Forwards the specified email to a verified email address.
$options = new MessageForwardOptions();
$options-&gt;to = 'verified-address@example.com';
$options-&gt;text = 'FYI';

$mailosaur-&gt;messages-&gt;forward('MESSAGE_ID', $options);
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-&gt;reply(messageId, messageReplyOptions)
Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails.
$options = new MessageReplyOptions();
$options-&gt;text = 'FYI';

$mailosaur-&gt;messages-&gt;reply('MESSAGE_ID', $options);
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-&gt;all()
Returns a list of your virtual servers. Servers are returned sorted in alphabetical order.
$result = $mailosaur-&gt;servers-&gt;all();

print('You have a server called: ' . $result-&gt;items[0]-&gt;name);
servers-&gt;create(server)
Creates a new virtual server. Only the name property is required to create a new server via the API.
$createOptions = new ServerCreateOptions('My email tests');
$mailosaur-&gt;servers-&gt;create($createOptions);
servers-&gt;get(id)
Retrieves the detail for a single server. Simply supply the unique identifier for the required server.
$server = $mailosaur-&gt;servers-&gt;get('SERVER_ID');
servers-&gt;getPassword(id)
Retrieves the password, for use with SMTP and POP3, for a single server. Simply supply the unique identifier for the required server.
$password = $mailosaur-&gt;servers-&gt;getPassword('SERVER_ID');
servers-&gt;update(id, server)
Updates a single server.
$retrievedServer = $mailosaur-&gt;servers-&gt;get('SERVER_ID');
$retrievedServer-&gt;name = 'Updated server name';

$mailosaur-&gt;servers-&gt;update($retrievedServer-&gt;id, $retrievedServer);
servers-&gt;delete(id)
Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.
$mailosaur-&gt;servers-&gt;delete('SERVER_ID');
servers.generate_email_address(id)
Utility method to help you generate a random email address for a given server.
$emailAddress = $mailosaur-&gt;servers-&gt;generateEmailAddress('SERVER_ID');

print($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-&gt;getEmail(messageId)
Downloads an EML file representing the specified email. Simply supply the unique identifier for the required email.
files-&gt;getAttachment(attachmentId)
Downloads a single attachment. Simply supply the unique identifier for the required attachment.
Analysis
analysis-&gt;spam(messageId)
Perform spam testing on the specified email.
Usage
usage-&gt;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-&gt;transactions()
Retrieves the last 31 days of transactional usage. This endpoint requires authentication with an account-level API key.

Learn how to automate test email and SMS messages in PHP, using Mailosaur.

How to test email and SMS in PHP

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. Create a sample project
Install Go
To see if you already have Go installed, open a terminal window and run this command:
go version
If Go is installed, you’ll see a version number. If you see an error instead, then download Go from its official site and install it.
Create a new project
Run each of these commands to create a new project:
mkdir EmailTests
cd EmailTests
go mod init example.com/emailtests
Install the Mailosaur Go library
Run this command to install the Mailosaur Go package:
go get -u github.com/mailosaur/mailosaur-go
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

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to test with.
Click on the API tab.
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:

Open up an email client and send an email to anything@example.mailosaur.net
Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you sent an email to.
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. Find an email for automated testing
Now that you have a sample project, your server’s credentials, and an email to test, then you’re ready to continue.
Create a file named hello_test.go and type or paste in this code sample, replacing the template code with the values from step 3 above:
package emailtests

import (
  "fmt"
  "testing"
  "github.com/mailosaur/mailosaur-go"
)

func TestExample(t *testing.T) {
  // Available in the API tab of a server
  apiKey := "YOUR_API_KEY";
  serverId := "SERVER_ID";
  serverDomain := "SERVER_DOMAIN";

  m := mailosaur.New(apiKey);

  params := &amp;mailosaur.MessageSearchParams {
    Server: serverId,
  }

  criteria := &amp;mailosaur.SearchCriteria {
    SentTo: "anything@" + serverDomain,
  }

  email, err := m.Messages.Get(params, criteria)

  if (err != nil) {
    t.Error(err)
  }

  // If we have an email, print the subject
  fmt.Println("Subject: " + email.Subject)
}
This code connects to Mailosaur and looks for any email that has been sent to the address provided in the search criteria.
Save your changes and run the code:
go test
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).

5. Narrowing your search results
Only find messages received after a certain time
By default, searches 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:
testStart := time.Now()

// Perform the steps that send a message here

message, _ := client.Messages.Get(&amp;MessageSearchParams{
        Server: "SERVER_ID",
    ReceivedAfter: testStart,
}, &amp;SearchCriteria{
        SentTo: "...",
})
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:



PARAMETER
DESCRIPTION



SentFrom
The full email address from which the target message was sent.


SentTo
The full email address to which the target message was sent.


Subject
Find emails where the subject line contains this text.


Body
Finds messages where the message body contains this text.


6. 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 Go 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(params, 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.
params := &amp;mailosaur.MessageSearchParams {
  Server: "SERVER_ID",
}

criteria := &amp;mailosaur.SearchCriteria {
  SentTo: "something@{SERVER_ID}.mailosaur.net",
}

message, err := m.Messages.Get(params, criteria)
To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.
Parameters
In addition to the server, you can also set the following…



PARAMETER
DESCRIPTION



Server
The unique identifier for your Mailosaur Server.


Timeout
Specify how long to wait for a matching result (in seconds, default value is 10 seconds).


ReceivedAfter
Limits results to only messages received after this date/time (default 1 hour ago).


Criteria



PARAMETER
DESCRIPTION



SentFrom
The full email address from which the target message was sent.


SentTo
The full email address to which the target message was sent.


Subject
The subject line of the target email.


Body
Search for part of the message body.


Match
If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.


// Search all messages received after midnight on a specific date
params := &amp;mailosaur.MessageSearchParams {
  Server: "SERVER_ID",
  ReceivedAfter: time.Date(2020, 1, 5, 0, 0, 0, 0, time.UTC),
}

criteria := &amp;mailosaur.SearchCriteria {
  SentTo: "something@{SERVER_ID}.mailosaur.net",
}

message, err := m.Messages.Get(params, criteria)
Messages.List(params)
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call GetById. Alternatively, we recommend using the Get method, which is a far more efficient approach.```go
// List the most recent messages
params := &amp;mailosaur.MessageListParams {
  Server: server
}
result, err := m.Messages.List(params)
if (err != nil) {
  // Handle err
}
// Get the most recent message (the first one in the list)
message = result.Items[0]
fmt.Println(&quot;Subject: &quot; + message.Subject)

##### Parameters
- **Server** The unique identifier for your Mailosaur Server.
- **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```.

```go
// List all results received after midnight on a specific date 
// Limit results to the first 10 matches only.
params := &amp;mailosaur.MessageListParams {
  Server: server,
  ReceivedAfter: time.Date(2020, 1, 3, 0, 0, 0, 0, time.UTC),
  Page: 0,
  ItemsPerPage: 50,
}

result, err = m.Messages.List(params)
Messages.Search(params, criteria)
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.Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call GetById. Alternatively, we recommend using the Get method, which is a far more efficient approach.```go
params := &amp;mailosaur.MessageListParams {
  Server: server,
}
criteria := &amp;mailosaur.SearchCriteria {
  SentTo: &quot;someone@SERVER_ID.mailosaur.net&quot;,
}
result, err := m.Messages.Search(params, criteria)
if (err != nil) {
  // Handle err
}
// Get the most recent match
message := result.Items[0]
fmt.Println(&quot;Subject: &quot; + message.Subject)

##### Parameters
- **Server** The unique identifier for your Mailosaur Server.
- **Timeout** If provided, determines how long to wait for a matching result (provided in milliseconds).
- **ErrorOnTimeout** When set to ```false```, an error will not be throw if timeout is reached (default: ```true```). Note the data type is ```*bool```, therefore you must set this using a variable (e.g. ```f := false``` followed by ```params.ErrorOnTimeout = &amp;f```)
- **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```.

##### Criteria
- **SentFrom** The full email address from which the target message was sent.
- **SentTo** The full email address to which the target message was sent.
- **Subject** The subject line of the target email.
- **Body** Search for part of the message body.
- **Match** If set to ```ALL``` (default), then only results that match all specified criteria will be returned. If set to ```ANY```, results that match any of the specified criteria will be returned.

```go
// Search for all messages sent to someone@SERVER_ID.mailosaur.net,
// received after midnight on a specific date. Limit results to
// the first 10 matches only.
params := &amp;mailosaur.MessageListParams {
  Server: server,
  Page: 0,
  ItemsPerPage: 10,
  ReceivedAfter: time.Date(2020, 1, 3, 0, 0, 0, 0, time.UTC),
}

criteria := &amp;mailosaur.SearchCriteria {
  SentTo: &quot;someone@SERVER_ID.mailosaur.net&quot;,
}

result, err := m.Messages.Search(params, criteria)
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.
result, err = m.Messages.List(&amp;mailosaur.MessageListParams {
  Server: server,
})

if (err != nil) {
  // Handle err
}

messageId := result.Items[0].Id

message := m.Messages.GetById(messageId)

fmt.Println("Subject: " + message.Subject)
Messages.Delete(id)
Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
m.Messages.Delete(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.
m.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.
options := &amp;mailosaur.MessageCreateOptions {
  To: "verified-address@example.com",
  Send: true,
  Subject: "Request",
  Text: "Please can you give us a call back?",
}

m.Messages.Create("SERVER_ID", options)
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.
options := &amp;mailosaur.MessageForwardOptions {
  To: "verified-address@example.com",
  Text: "FYI",
}

m.Messages.Forward("MESSAGE_ID", options)
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.
options := &amp;mailosaur.MessageReplyOptions {
  Text: "FYI",
}

m.Messages.Reply("MESSAGE_ID", options)
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.
result, err := m.Servers.List()

if (err != nil) {
  // Handle err
}

fmt.Println("You have a server called: " + result.Items[0].Name)
Servers.Create(options)
Creates a new virtual server. Only the name property is required to create a new server via the API.
options := &amp;mailosaur.ServerCreateOptions {
  Name: "My email tests",
}

m.Servers.Create(options) 
Servers.Get(id)
Retrieves the detail for a single server. Simply supply the unique identifier for the required server.
server, err := m.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.
password, err := m.Servers.GetPassword("SERVER_ID")
Servers.Update(id, server)
Updates a single server.
retrievedServer, err := m.Servers.Get("SERVER_ID")

if (err != nil) {
  // Handle err
}

retrievedServer.Name = "Updated server name"

m.Servers.Update(retrievedServer.Id, retrievedServer);
Servers.Delete(id)
Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.
m.Servers.Delete("SERVER_ID")
Servers.GenerateEmailAddress(id)
Utility method to help you generate a random email address for a given server.
emailAddress := m.Servers.GenerateEmailAddress("SERVER_ID")

fmt.Println(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.

Learn how to automate testing of email and SMS messages in Golang using Mailosaur. Follow steps to create a sample project, send emails, and write effective tests.

How to test email and SMS in Go

Explore comprehensive guides on testing email and SMS messages in various programming languages. Learn automation techniques in Node.js, Python, Java, JavaScript, .NET, Ruby, PHP, and Go with Mailosaur.

Languages

HTML and text content within an email Most email sent today is HTML-based, however an email will often contain a plain text alternative for older mail clients, which is what this page relates to. Learn how to work with the HTML content of an email.## Before you begin
The examples shown below are based on two key assumptions:

That you have already create a basic automated test using our getting started guides.
You have a chosen assertion library that you will use to test the values shown below.

Accessing the text
The text content of email or SMS message can be accessed via the text.body property of a message.## Working with the content
This section describes some of the most common use cases related to the content of an email or SMS message. You should also refer to the guides on working with automatically-extracted content such as links and images.
Checking if message contains a string### Finding a 6-digit code
Note: We recommend using Mailosaur’s built-in verification code detection. However, you can also write your own regular expressions to extract values from within your content.
The example below shows how to extract a 6-digit numeric code from a message.### Finding an 8-digit alphanumeric code
In this example, an 8-digit code, consisting of 2 letters, followed by 6 numbers is extracted.

Discover the secrets of testing text content in email or SMS with Mailosaur. Latest techniques for effective and reliable testing.

How to test the text content of email or SMS

HTML and text content within an email Most email sent today is HTML-based, however an email may also contain a plain text alternative for older mail clients. Learn how to work with text content of an email.## Before you begin
The examples shown below are based on two key assumptions:

That you have already create a basic automated test using our getting started guides.
You have a chosen assertion library that you will use to test the values shown below.

Accessing the HTML content
An email’s HTML body can be accessed via the html.body property of a message.Mailosaur also automatically extracts certain content for you, such as links and images.
Extracting from the HTML
You may wish to work with individual elements within your email’s HTML content. This is useful for extracting key pieces of data, such as account verification codes.
Install an HTML library
To extract content from the body of an email, you will need to use an HTML library in your tests. Each language has alternative libraries to those shown here, but this should get you started.
First, install a library for the language you are working with:### Import the library in your code
Next, reference the library in your code:### Find the target element
In this example, we want to extract the verification code from the HTML below:
&lt;div&gt;
  &lt;h1&gt;To activate your account, enter this code:&lt;/h1&gt;
  &lt;p class="verify-code"&gt;542163&lt;/p&gt;
&lt;/div&gt;
To do this, we pass the email’s HTML body into our library, then find the element we need and access the 6-digit access code within:

Explore the intricacies of HTML and text content within emails. Delve into the importance of HTML-based emails and discover how to manage plain text alternatives for compatibility with older mail clients

HTML content of an email

Before you begin
The examples shown below are based on two key assumptions:

That you have already create a basic automated test using our getting started guides.
You have a chosen assertion library that you will use to test the values shown below.

Links within email and SMS text content
When an email or SMS message is sent with plain text content, Mailosaur automatically extracts anything that look like a verification code and makes these available via the text.codes array. Each code has a value property, representing the code itself.## Links within email HTML content
As with links found within the text content of a message, Mailosaur also detects and extracts codes found within the HTML of any email.
These are made available viable via the html.codes array.## What if my code is not detected?
Mailosaur automatically detects most common verification code patterns, however you can still write your own regular expressions to meet more specific requirements.

Unlock the secrets of code extraction from email and SMS messages with Mailosaur. Dive into examples in multiple programming languages, exploring plain text, HTML content, and custom regular expressions. Enhance your automated tests for verification codes.

Extracting codes from email and SMS

Before you begin
The examples shown below are based on two key assumptions:

That you have already create a basic automated test using our getting started guides.
You have a chosen assertion library that you will use to test the values shown below.

Links within email HTML content
When an email is sent with an HTML body, Mailosaur automatically extracts any hyperlinks found within anchor (&lt;a&gt;) and area (&lt;area&gt;) elements and makes these available via the html.links array.
Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL.
Note that only links that have been correctly marked up in HTML will be detected.## Links within email and SMS text content
As with links found within the HTML content of an email, Mailosaur also detects and extracts links found within the plain text of a message (both email and SMS).
These are made available viable via the text.links array.
Each link has an href property containing the target URL. Whilst each link also has a text property, this will always have the same value as href.

Master the art of link extraction from email and SMS messages with Mailosaur. Explore examples in various programming languages, covering HTML content and plain text. Enhance your automated tests for hyperlinks.

Extracting links from email and SMS

Before you begin
The examples shown below are based on two key assumptions:

That you have already create a basic automated test using our getting started guides.
You have a chosen assertion library that you will use to test the values shown below.

How many attachments
The attachments property of a message contains an array of attachments. The length of this array corresponds to the number of files attached to the email.## Testing the file name and content type
Each attachment contains metadata on the file name and content type.## Testing attachment file size
The length property returns the size of the attached file (in bytes).## Embedded Images
If an email contains embedded images then the contentId attribute will be populated and will have a corresponding entry in the images array.## Fetching an attachment as base64
You can fetch the content of an attachment, encoded as base64, using the “get attachment” method:## Saving an attachment to disk
You can also write an attached file to disk:

Master email attachment testing with Mailosaur. Explore file count, name, content type, size, embedded images, and fetching attachments in various programming languages. Follow step-by-step examples to enhance your automated tests and ensure efficient email attachment handling.

Email attachments

Before you begin
The examples shown below are based on two key assumptions:

That you have already create a basic automated test using our getting started guides.
You have a chosen assertion library that you will use to test the values shown below.

How many images
The html.images property of a message contains an array of images. The length of this array corresponds to the number of images found within an email.Each attachment contains both a src attribute, which contains the location of the image, as well as an alt attribute holding the alternative, text description of the image.
Remotely-hosted images
Emails will often contain many images that are hosted elsewhere, such as on your website or product. It is recommended to check that these images are accessible by your recipients.
All images should have an alternative text description, which can be checked using the alt attribute.In addition, to check that the image itself is accessible, you can use the src attribute to perform an HTTP request to that address.
Web beacons
A web beacon is a small image that can be used to track whether an email has been opened by a recipient.
Because a web beacon is simply another form of remotely-hosted image, you can use the same code shown above to trigger an open email event.
Embedded images
When an image is embedded within the content of an email, its src attribute will contain a “content ID” (e.g. cid:ii_1435fadb31d523f6).
Where a content ID is present, the image itself will be attached to the email, and so can be access in the same way as any other attachment. Note that the contentId attribute of the attachment will match the value found in the src attribute, excluding the cid: prefix.

Learn to handle images and web beacons in HTML emails with Mailosaur. Optimize your automated testing for email and SMS content.

Images and web beacons

Before you begin
The examples shown below are based on two key assumptions:

That you have already create a basic automated test using our getting started guides.
You have a chosen assertion library that you will use to test the values shown below.

Email subject
Allows you to check that the correct subject will be displayed in a recipient’s mail client.## Recipients
The to property of a message contains an array of all recipients of a message (excluding those that have been carbon-copied on an email).### Carbon copy (CC) recipients### Blind carbon-copy (BCC) recipients## Sender
The from property of a message contains an array of senders. In almost all cases there will only be 1, however the email specification technically allows for multiple senders to exist.## Email Headers
Emails contain a set of headers that are used to transmit metadata which is typically not visible to the recipient.
All email headers are available via the metadata.headers property of a message. Each header has both a field and value property.

Learn how to test the common properties of an email or SMS messages with Mailosaur.

Message properties

Before you begin
The examples shown below are based on two key assumptions:

That you have already create a basic automated test using our getting started guides.
You have a chosen assertion library that you will use to test the values shown below.

Accessing SpamAssassin results
Allows you to perform a SpamAssassin check against an email. The structure returned matches the spam test object:

Master the art of testing email spam score with Mailosaur. Latest insights and guidance for efficient SpamAssassin checks.

How to test email spam score

Learn common email and SMS tests with Mailosaur. Explore text and HTML content, extract codes and links, test attachments, images, web beacons, message properties, and spam scores.

Common test cases

What is Multifactor Authentication?
Products and websites often use something called “Two-Step Verification” or “Multifactor Authentication” (MFA), whereby a user is required to provide multiple ‘factors’ to prove they are who they claim to be. Three common kinds of factor are:

Something you know: Your password, or a memorable date.
Something you have: Your smartphone, or a secure USB key.
Something you are: Facial recognition, your fingerprint, etc.

Using the Mailosaur API you can test MFA functionality, either by using Mailosaur’s SMS Testing functionality, or by creating virtual security devices.
Using Virtual Security Devices
One of the most common ways to implement multifactor authentication is via an authenticator app, like Google Authenticator. Creating a Virtual Security Device allows you to mimic this functionality, by generating the same one-time passwords (OTP) that an authenticator app would. This makes it easy to create end-to-end tests that give you full coverage of the most sensitive areas of your product or service.
Automating OTP tests with virtual devices
For most end-to-end tests, you’ll simply need a way of getting the current one-time password (OTP) for a given shared secret (i.e. the value you would ask your user to setup Google Authenticator with).
You can do this with a couple of lines of code, using the otp method to get the current one-time password for a secret:### Creating a device for longer-term testing
If you need a device for a longer-period of time, you can simply create one within the Mailosaur Dashboard, or via the API:### Retrieving the current one-time password
You can get the current code for a saved security device within the Mailosaur Dashboard, or via the API:### Deleting a device
You can delete a virtual security device within the Mailosaur Dashboard, or via the API using the device’s unique identifier:## Using SMS
You can also use Mailosaur to test multifactor authentication processes that make use of SMS. For more information on this, check out our sms testing guide.

Learn how to effectively test Multifactor Authentication (MFA/2FA) with Mailosaur. Explore virtual security devices, automated OTP tests, creating devices for long-term testing, and utilizing SMS testing for comprehensive coverage.

How to test Multifactor Authentication - MFA, 2FA, OTP

What is a server?
Servers allow you to group tests, permissions, and other settings together. You could use a server for a particular project, product, environment, or another purpose.
How do I create a new server?
To create a server, you must be an Administrator or Account Owner on the account in question. This access can be granted by another Administrator on your account if you do not already have this.
You can create a new server using the Mailosaur Dashboard, or the API.## Server limits
You can only create as many servers as your plan supports.
For information on how many servers you account supports you can refer to the Usage page in the Mailosaur Dashboard, or visit our pricing page.
How do I delete a server?
You can delete servers using the Mailosaur Dashboard or the API.
A deleted server is a permanently lost, and immediately unavailable for use. Be sure that the server is not used anywhere in your team before performing this operation.

Our servers act like projects, which group your tests together. This page explains how to create and manage servers using the Mailosaur Dashboard and the API.

Creating and deleting servers

Manage virtual SMTP/SMS servers with Mailosaur. Explore guides and API documentation for creating and deleting servers, grouping tests effectively.

Managing servers

What are API keys for?
If you want to automate email and SMS testing with Mailosaur, you need to make calls to the Mailosaur API. API keys are used to authenticate requests to this API.
Authentication to the API is performed via HTTP Basic Auth, with your API key provided as the basic auth username value. You do not need to provide a password.
What are account-level API keys?
Account-level API keys have access to all functions described in the API reference, and have access to all the servers in your account.
Creating an account-level API key
To create an account-level API key, you must be an Administrator or Account Owner on the account in question. This access can be granted by another Administrator on your account if you do not already have this.

Go to the Settings page in the Mailosaur Dashboard.
Go to the API Keys page.
Click the Create a Key button.
In the dialog that appears, enter a name for your key.
When you are finished, click Create.

Revealing an account-level API key
For your security, API keys are not automatically displayed on-screen. To reveal an account-level API key:

Go to the Settings page in the Mailosaur Dashboard.
Go to the API Keys page.
Click the Reveal Key button for the API key you want.
Click the revealed value to copy it to your clipboard the dialog that appears, enter a name for your key.
When you are finished, click Create.

What are server API keys?
You may want to restrict how much data an API key can access. This is where server-level API keys come in. This type of API key can only access the data of a single server, and have no ability to list or manage servers on your account.
If you need more access, take a look at account-level API keys above.
Creating a server-level API key
To create an server-level API key, you must have access to the server in question. This access can be granted by an Administrator on your account if you do not already have this.

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to create an API key for.
Click on the API tab.
Click Create a Key.
In the dialog that appears, enter a name for your key.
When you are finished, click Create.

Revealing a server-level API key
For your security, API keys are not automatically displayed on-screen. To reveal a server-level API key:

Go to the Servers page in the Mailosaur Dashboard.
Click on the name of the server you want to create an API key for.
Click on the API tab.
Click the Reveal Key button for the API key you want.
Click the revealed value to copy it to your clipboard.


API keys and their role in automating email and SMS testing with Mailosaur. Learn about account-level and server-level API keys, how to create them, and ensure secure access to functions and data.

API Keys

Deleting a trial account
To delete an account, you must be an Account Administrator. If you are, you can delete your account using the Mailosaur Dashboard.

Go to the Account Settings area in the Mailosaur Dashboard.
Click Invoicing &amp; billing.
Click the Edit button at the top of the Current plan panel. If you do not see this button, you’ll need to contact the support team.
In the menu that appears, click Delete account and follow the on-screen instructions.

Cancelling your subscription
If you want to pause or cancel your subscription on your account, you can do so using the Mailosaur Dashboard. You must be a Billing Administrator for this to work.

Go to the Account Settings area in the Mailosaur Dashboard.
Click Invoicing &amp; billing.
Click the Edit button at the top of the Current plan panel. If you do not see this button, you’ll need to contact the support team.
Click Cancel subscription and follow the on-screen instructions.

Once cancelled, you will still be able to use your account until your next renewal date.

Maybe you have a duplicate account or perhaps you want to leave Mailosaur. Either way, here is how to delete an account.

Deleting your account

Why verify a domain?
There are 3 main reasons for verifying ownership of a domain:

To use a custom inbound domain for emails sent into Mailosaur (Professional and Enterprise plans only).
To use the mailosaur.js library (e.g. with Ghost Inspector).
To send, reply and forward email to external email addresses on that domain.

Verifying ownership of a domain

Log into the Mailosaur Dashboard.
Navigate to the Account Settings area.
Select Domains.
Click the Add Domain button and enter the domain name you want to verify (e.g. example.com)
If you also want to be able to receive inbound email on this domain, select Allow email to be sent to this domain and answer any additional questions (only available to Professional and Enterpise plan customers).
Once you’re ready, submit the form.
You will be presented with on-screen instructions on how to verifying ownership of the domain. This will require technical knowledge. Share this information with an IT team member if this is not your thing.
Once you have followed the on-screen instructions, it may take up to 30 minutes for the domain to be verified.
Once a domain is verified, you’ll see a green checkmark next to it, meaning it is ready to use.

Allow email to be sent into Mailosaur via this domain
Note: Only available to Professional and Enterpise plan customers.
By default, Mailosaur gives you access to email addresses ending @{server_id}.mailosaur.net. You can, however, use your own domain instead (e.g. @yourdomain.com)
To do this, follow the instructions above and select Allow email to be sent to this domain when setting up or configuring a domain. You can link your domain to a single Mailosaur server, or use a wildcard pattern (replacing @{server_id}.mailosaur.net with @{server_id}.yourdomain.com).
You’ll be presented with instructions on how you need to confirm the DNS records of your domain. This will require technical knowledge. Share this information with an IT team member if this is not your thing.
It can take up to 24 hours for new DNS records to propagate, but once set up, any email sent to email addresses using that domain will appear in your Mailosaur inbox.

Learn how to verify a domain you own, so that you can use it with your Mailosaur account for email and SMS testing.

Verifying Domain Ownership

You can send, reply and forward emails with Mailosaur, for the purpose of testing functionality in your product or website. However, as Mailosaur is not an email service provider (ESP), you must first verify that you have the consent of the email address owner.
To begin the process of verifying ownership of an external email address, you must be an Administrator on the account. This access can be granted by another Administrator on your account if you do not already have this.
Verifying ownership of an external email address

Log into the Mailosaur Dashboard.
Navigate to the Account Settings area.
Select Email Addresses.
Click the Add Email Address button.
Enter the email address that you want to verify, and submit the form.
An email will then be sent to this address, with instructions on how to complete the process.

Once an email address has been verified, you’ll see a green checkmark next to it, meaning it is ready for use.
Verifying an entire domain
If you need to send to a wide range of emails on a domain you own (for example, if you’re testing a helpdesk/ticketing product), then you can also verify an entire domain.
For more infromation, see verifying domain ownership.

Learn how to manage external email addresses with Mailosaur. Verify ownership for sending, replying, and forwarding emails.

Managing External Email Addresses

Overview
Some organisations operate security policies that deny outbound traffic by default. If your organisation does this, you’ll need to add Mailosaur’s services to your allowlist.
We may change to our IP addresses from time to time, and so we recommend allowing by domain name rather than IP address whereever possible.
Domains and IP addresses
Mailosaur is accessible via three primary IP addresses: 34.149.187.159, 35.187.177.145 and 35.233.95.121:



SERVICE
DOMAIN NAME
IP ADDRESS



Website
mailosaur.com
34.149.187.159


Dashboard
mailosaur.com
34.149.187.159


API
mailosaur.com
34.149.187.159


SMTP
mailosaur.net
35.187.177.145


POP3
mailosaur.net
35.187.177.145


SMTP (Legacy)
mailosaur.io
35.233.95.121


POP3 (Legacy)
mailosaur.io
35.233.95.121


Note that the Legacy SMTP &amp; POP3 services only apply to customers connecting to mailosaur.io in their test code.
Port numbers
For services to function, you must allow the following TCP ports:



SERVICE
PORT NUMBER(S)



Website, Dashboard, API
443


SMTP
25, 2525, 465 and 587


POP3
110 and 995



Learn how to configure Mailosaur for corporate networks blocking unknown IP addresses or port numbers. Optimize email and SMS testing for your network.

IP addresses and ports

You can invite your colleagues to access your Mailosaur account so that you can collaborate together. Each user can have have different permission levels.
You can also create Teams, which allow you to easily configure the permissions for groups of users.
Inviting, editing and removing users
You must be an Account Administrator in order to manage users.
If you know a person&#39;s email address, you can invite them to your account by clicking Invite User on the Users screen within admin settings.
You can edit a users&#39; details by clicking on their name in the list of users. To delete a user, just click the trash can icon on that same row.
Managing teams
If you want to apply the same permissions and access to a group of users, you can do so by creating teams.
You can create teams in the Teams area within admin settings, by clicking the Create Team button.
Once a team is created, you can add or remove users as members of that team.
Administrator permissions
When configuring users or teams on your account, you can optionally assign one or both of the following administration privileges:

Account Administrator: This role is for people who need access to manage account-wide API keys, settings, etc. This role can see and manage almost everything on the account.
Billing Administrator: This role is for people who need to manage your account subscription, plan level and billing settings.


Learn how to manage user permissions in Mailosaur. Control team access and actions, configure user permissions.

Managing Users and Teams

What is SSO?
Single sign-on (SSO) is an authentication scheme that allows customers to mandate sign-in requirements and team member access to systems like the Mailosaur Dashboard.
Mailosaur allows users to log in via Google, GitHub and Microsoft authentication, but also supports Enterprise SSO providers via Security Assertion Markup Language (SAML) and OpenID Connect (OIDC), allowing authentication and team member account creation to be deferred to an Identity Provider (IdP) like Okta, AzureAD, Ping Identity and more.
Benefits of SSO
Using SSO to authenticate to the Mailosaur Dashboard has two main benefits:

Security improvements
Allow team members to access the Dashboard without needing to create a password.
Leverage authentication decisions defined through an IdP, such as password policies and mandating two-factor authentication.
Configure your account to mandate SSO for all team members.


Easily manage access
Allow new team members to instantly sign in to the Dashboard using Just-in-Time account provisioning.
Revoke Dashboard access as needed, such as when a user leaves your organisation.
Manage users, teams and team membership with SCIM.



Setting up Enterprise SSO (SAML or OpenID Connect)
What we need from you
If you’re using a SAML-based provider, then all our team need is the metadata URL for your identity provider (e.g. https://example.com/metadata/idp.xml). However, if you can’t find this, simply send us the entity ID, SSO/redirect URL and certificate.
If you’re using an OpenID Connect-based provider, we just need the client ID and issuer URL.
What you need from us
If you’re using SAML, you’ll need to set a ‘Single sign on URL’ (or recipient/destination URL), which is https://mailosaur.com/__/auth/handler. You will also need to set the ‘Audience URI’ (or entity ID) for the Mailosaur service, which is https://id.mailosaur.com/saml.
For OpenID Connect, you’ll need the ‘Authorization Callback URL (ACS)’ for Mailosaur, which is https://mailosaur.com/__/auth/handler.
Enforcing single sign-on
When we first set up Enterprise SSO for you, it will be configured as optional, which means your users can still log in via another mechansim (e.g. their own username/password). Once you are happy with the SSO configuration, just let our team know and we’ll make SSO mandatory for your account.
Just-in-time (JIT) provisioning
Mailosaur supports just-in-time (JIT) provisioning of users. When enabled, whenever a user visits Mailosaur for the first time, we’ll add them to your account, as long as they are authorised by your identity provider. This saves times when adding new users; as you just need to grant them access to Mailosaur within your organisation’s IT systems.
When someone no longer requires Mailosaur access, blocking them via your SSO provider will immediate prevent them from logging in, but you’ll also want to log into Mailosaur and delete their user record, to free up a seat on your account. You do not need to do this manual step if you have SCIM enabled.
SCIM
SCIM (System for Cross-domain Identity Management) allows for the advanced management of users and teams. It can be used instead of JIT to provision new users, but moreover can also create teams, assign users to teams, and delete users when they leave your organisation.
SCIM is available to Enterprise plan customers, just speak to the team to learn more.

Enhance your Mailosaur Dashboard security with Single Sign-On (SSO). Implement SAML or OpenID Connect for seamless authentication and access control.

Single sign-on

SCIM Provisioning
The SCIM API is used by SCIM-enabled Identity Providers (IdPs) to automate provisioning and manage access for user accounts and teams (groups). The Mailosaur API is based on version 2.0 of the SCIM standard. The SCIM endpoint that an IdP should use is: https://mailosaur.com/api/scim/.
The SCIM API is only available to customers with an Enterprise plan, with Enterprise SSO enabled.
Authentication
To authenticate with the Mailosaur SCIM API, you must first create an account-level API key. As with all other authenticated calls to the Mailosaur API, this key must be passed using HTTP Basic Auth. Learn more about API authentication in our API reference.
SCIM user attributes
The following table maps SCIM attributes to the relevant fields that Mailosaur uses. Most of these profile fields are exposed directly in a person’s profile in the Mailosaur Dashboard:



NAME
TYPE
DESCRIPTION



displayName
string
The full name of the user. When provisioning a user, the name attributes are preferred to displayName.


name.givenName
string
The first name of the user.


name.familyName
string
The last name of the user.


emails
array
Whilst this is a list of user emails, Mailosaur only uses one, which will be associated with their Mailosaur account. If Mailosaur finds an email marked as primary (or one that is marked as the user’s “work” email address) then this will be used. Otherwise, the first email in the list will be selected.


userName
string
The email address associated with the Mailosaur user. May be used to set the email address for a user, if not set via the emails array.


id
string
Identifier generated by the Mailosaur SCIM endpoint.


externalId
string
This identifier is generated by the SAML provider, and is used as a unique ID by the SAML provider to match against a Mailosaur user. You can find the externalID for a user either at the SAML provider, or using the List SCIM provisioned identities endpoint and filtering on other known attributes, such as a user’s GitHub username or email address.


active
boolean
Indicates whether the identity is active (true) or should be deprovisioned (false).


NOTE: Endpoint URLs for the SCIM API are case sensitive. For example, the first letter in the Users endpoint must be capitalized.List usersProvision a userRetrieve a userUpdate a userDelete a user## Groups (Teams)
SCIM groups are mapped to Mailosaur “Teams”, which can be used for organizing users in logical divisions across a workspace, such as by team or affinity.



NAME
TYPE
DESCRIPTION



displayName
string
The team (group) name.


members
array
Users that are assigned to this team (group).



Efficiently manage user access with Mailosaur&#39;s SCIM API. Automate provisioning, access, and team organization with SCIM-enabled Identity Providers.

SCIM

Prerequisites
Mailosaur&#39;s Okta integration supports authentication via SAML, OpenID Connect (OIDC) and SCIM provisioning (depending on plan level).
Before beginning, ensure that you have:

A Mailosaur account with SSO enabled. SSO is available on the Enterprise plan, and as an optional bolt-on to the Professional plan.
Access with the role of Account Administrator.

Supported Features

SP-initiated SSO
JIT (Just-In-Time) provisioning
SCIM provisioning (Enterprise plan only)

SAML
Configuration Steps
Follow these steps if you wish to integrate Okta and Mailosaur using SAML. Alternatively, you can configure using OpenID Connect (OIDC).
1. Configuration within Okta

Log into your Okta administrative portal.
Click Applications in the left-hand sidebar, and then Browse App Catalog near the top of the resulting page.
Search for &quot;mailosaur&quot; in the search bar, and then click the Mailosaur integration from the results.
Click the Add Integration button to add the Mailosaur integration to your Okta instance.
When the app integration is added to your Okta instance, you will be redirected to the applications assignments page. Click on the Sign On tab then copy the Metadata URL value, you will need this later.

2. Verify your company domain in Mailosaur
So that your users can be automatically redirected to Okta if they try to log in via the Mailosaur login page, you need to verify that you own the domain in their email address (for example, if your users used some.person@example.com, you would verify ownership of example.com). To do this:

Log into the Mailosaur Dashboard.
Click Admin (cog icon) in the top-right of the screen, then select Domains.
Click Add Domain and type in the domain that you wish to verify (e.g. example.com)
Leave all other options unchanged, and click Add Domain.
Follow the on-screen instructions to verify that you own this domain (contact our support team if you&#39;re unsure how to do this).

3. Setup SSO within Mailosaur

If you are not already logged in, then log into the Mailosaur Dashboard.
Click Admin (cog icon) in the top-right of the screen, then select Single Sign-On.
Select your verified domain from the list of domains (see step above if you haven&#39;t verified a domain yet).
From the list of Identity providers, choose Okta.
Now fill in the Identity provider (IdP) metadata URL field. The value for this is what you copied above and can be found on the Sign On tab within the Okta administrative portal.
Paste in this value and click Save.

SSO is now configured on your account. You can optionally choose to enable JIT (Just-In-Time) Provisioning, which will automatically add any new users onto your account when they first log into Mailosaur.
You can also make SSO mandatory (however, you must first log in with Okta before you can do this).
Users can now log in via the URL shown on-screen e.g. https://mailosaur.com/sso/{company}
OpenID Connect (OIDC)
Configuration Steps
Follow these steps if you wish to integrate Okta and Mailosaur using OpenID Connect (OIDC). Alternatively, you can configure using SAML.

Log into your Okta administrative portal.
Click Applications in the left-hand sidebar, and then Browse App Catalog near the top of the resulting page.
Search for &quot;mailosaur&quot; in the search bar, and then click the Mailosaur integration from the results.
Click the Add Integration button to add the Mailosaur integration to your Okta instance.
When the app integration is added to your Okta instance, you will be redirected to the applications assignments page.
On the General tab, make a note of the Client ID that is shown.
Click on the Sign On tab then make a note of the Issuer URL.
Contact support with the Client ID and Issuer URL noted above, so that our team can complete OIDC configuration on our side.
Our team will provide you information on how your users can login.

SCIM
Supported Features

Create users
Update user attributes
Deactivate users
Push groups

For more information on the features listed below, we recommend visiting this glossary from Okta.
Configuration Steps
Generate a token for use with SCIM

Log into the Mailosaur Dashboard.
Click Admin (cog icon) in the top-right of the screen, then select API keys.
Click Create Key, name the new key SCIM and click Create Key again.
Find the newly-created key and click Reveal Key, copy the revealed value for use later (below).

Configuring provisioning in Okta

Log into your Okta administrative portal.
Click Applications in the left-hand sidebar, and navigate into the Mailosaur application that you already have configured (see configuration steps for SAML or OIDC above).
Select the Provisioning tab and check the Configure API Integration box.
Check the Enable API integration checkbox
Paste in the API key that you created in the steps above.
Click Test API Credentials - a success message should appear.
Click Save.
Select To App in the left panel then click Edit.
Enable Create users, Update User Attributes and Deactivate Users, then click Save.

Select users to be provisionned

The Assignments tab will let you provision your Okta users to Mailosaur.

Sync groups
On the Push Groups tab:

Select Push Groups, then Find groups by name.
Enter the name of your group.
Click Save &amp; Add Another.

Known Issues / Troubleshooting
Please reach our team at support@mailosaur.com if you encounter any issue.

Learn how to secure Mailosaur using SSO with Okta

Configure Single Sign On (SSO) with Mailosaur and Okta

Prerequisites
Mailosaur&#39;s Entra ID integration supports authentication via SAML and SCIM provisioning (depending on plan level).
Before beginning, ensure that you have:

A Mailosaur account with SSO enabled. SSO is available on the Enterprise plan, and as an optional bolt-on to the Professional plan.
Access with the role of Account Administrator.
A Microsoft Entra subscription.

Supported Features

SP-initiated SSO
JIT (Just-In-Time) provisioning
SCIM provisioning (Enterprise plan only)

Configuration Steps
Follow these steps if you wish to integrate Microsoft Entra and Mailosaur using SAML.
1. Configuration within Microsoft Entra
To configure the integration of Mailosaur into Microsoft Entra ID, you need to add Mailosaur from the gallery to your list of managed SaaS apps.

Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
Browse to Identity &gt; Applications &gt; Enterprise applications &gt; New application.
In the Add from the gallery section, type &quot;Mailosaur&quot; into the search box.
Select Mailosaur from results panel and then add the app. Wait a few seconds while the app is added to your tenant.
When the app is added to your tenant, select Single sign-on from the navigation sidebar.
On the Select a single sign-on method page, select SAML.
In the Basic SAML Configuration section, click Edit to edit the configuration.
In the Identifier (Entity ID) text box, type the URL: https://id.mailosaur.com/saml
In the Reply URL text box, type the URL: https://mailosaur.com/__/auth/handler
In the Sign on URL text box, type a URL using the following pattern: https://mailosaur.com/sso/{company}, where {company} is replaced with a short name for your organisation (e.g. acmecorp). Remember this Sign on URL as you will need it below.
Save your changes to Basic SAML Configuration.


In the SAML Certificates section, locate App Federation Metadata Url and copy the value, you will need this later.

2. Verify your company domain in Mailosaur
So that your users can be automatically redirected to Microsoft Entra if they try to log in via the Mailosaur login page, you need to verify that you own the domain in their email address (for example, if your users used some.person@example.com, you would verify ownership of example.com). To do this:

Log into the Mailosaur Dashboard.
Click Admin (cog icon) in the top-right of the screen, then select Domains.
Click Add Domain and type in the domain that you wish to verify (e.g. example.com)
Leave all other options unchanged, and click Add Domain.
Follow the on-screen instructions to verify that you own this domain (contact our support team if you&#39;re unsure how to do this).

3. Setup SSO within Mailosaur

If you are not already logged in, then log into the Mailosaur Dashboard.
Click Admin (cog icon) in the top-right of the screen, then select Single Sign-On.
Select your verified domain from the list of domains (see step above if you haven&#39;t verified a domain yet).
From the list of Identity providers, choose Microsoft Azure AD / Entra.
Now fill in the Identity provider (IdP) metadata URL field. The value for this is the App Federation Metadata Url that you copied above and can be found on the Single sign-on tab within the Microsoft Entra admin center.
Paste in this value and click Save.

SSO is now configured on your account. You can optionally choose to enable JIT (Just-In-Time) Provisioning, which will automatically add any new users onto your account when they first log into Mailosaur.
You can also make SSO mandatory (however, you must first log in with Okta before you can do this).
Users can now log in via the URL shown on-screen e.g. https://mailosaur.com/sso/{company}
SCIM
Supported Features

Create users
Update user attributes
Deactivate users
Push groups

Configuration Steps
Generate a token for use with SCIM

Log into the Mailosaur Dashboard.
Click Admin (cog icon) in the top-right of the screen, then select API keys.
Click Create Key, name the new key SCIM and click Create Key again.
Find the newly-created key and click Reveal Key, copy the revealed value for use later (below).

Configuring provisioning in Microsoft Entra

Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
Browse to Identity &gt; Applications &gt; Enterprise applications and locate/click on Mailosaur.
Navigate to Provisioning.
Click Get Started, then select provisioning mode Automatic.
Input the following Admin Credentials:
In the Tenant URL field enter https://mailosaur.com/api/scim/
In the Secret Token field enter the key generated above (see Generate a token for use with SCIM).
Click Test Connection
Once the connection is successfully tested, click Save



Known Issues / Troubleshooting
Please reach our team at support@mailosaur.com if you encounter any issue.

Learn how to secure Mailosaur using SSO with Microsoft Entra (Azure)

Configure SSO with Mailosaur and Microsoft Entra

The Mailosaur Dashboard is the user interface that allows you to operate and configure your Mailosaur account. You can use it to manage your servers, emails and SMS messages, manage users and permissions and more.
Browser compatibility
The Dashboard officially supports the following web browsers and mobile environments:

The last two versions of Chrome, Firefox, Safari, and Edge
The last two versions of mobile Safari on iOS


Manage your Mailosaur account with our intuitive Dashboard. Explore guides on email and SMS testing, API keys, domain ownership, user management, and more.