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

<h2 id="0-retrieve-account-limits"><a class="flex items-center group text-black hover:text-black" href="#0-retrieve-account-limits">Retrieve account limits<div class="inline-block ml-2 align-middle w-3.5 h-3.5 opacity-0 transition-opacity group-hover:opacity-100"><img src="/images/icons/hashtag-regular.svg" height="18" width="18" alt="A hashtag icon"></div></a></h2>

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

<h2 id="1-list-usage-transactions"><a class="flex items-center group text-black hover:text-black" href="#1-list-usage-transactions">List usage transactions<div class="inline-block ml-2 align-middle w-3.5 h-3.5 opacity-0 transition-opacity group-hover:opacity-100"><img src="/images/icons/hashtag-regular.svg" height="18" width="18" alt="A hashtag icon"></div></a></h2>

Mailosaur

Twitter

GitHub

YouTube

Instagram

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

<p>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.</p>

<h1>Usage</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.

Learn how to send emails to Mailosaur for testing and demonstration purposes.

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 messages 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:

Use the reply function to simulate a user replying to one of your emails.

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:

Use the sending function in Mailosaur to simulate someone sending an email to your product.

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.

Connect to your Mailosaur email testing server with POP3, so that you can pull emails down into other email clients and services.

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:

Use Mailosaur as a dummy SMTP server to catch every email your product sends.

Testing with SMTP

Learn how to use our virtual SMTP servers to test 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 how to allocate and use phone numbers to test SMS functionality with Mailosaur.

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:

Use the reply function to simulate a user replying to one of your SMS messages.

Replying to SMS messages

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 phone numbers to create end-to-end tests that cover identity verification, alerting, promotional messages and more.

How to test SMS messages with Mailosaur

Before you begin
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!
Install the Mailosaur plugin
Mailosaur provides an official set of custom commands, that allow you to test email and SMS seamlessly in Cypress.
Extend Cypress, by installing Mailosaur’s custom commands package cypress-mailosaur.
Install via npm or yarn
cd your/project/path
npm i -D cypress-mailosaur
# or
yarn add -D cypress-mailosaur
Once installed, register the commands by appending an import statement to the cypress/support/e2e.js file (or cypress/support/index.js in older versions of Cypress), within your project folder:
echo "import 'cypress-mailosaur'" &gt;&gt; cypress/support/e2e.js
Authenticating with Mailosaur
In order to connect to Mailosaur, you need to add your API key to your tests. You access your API key via the account settings screen.
Add API key to cypress.config.js
module.exports = defineConfig({
  env: {
    MAILOSAUR_API_KEY: "your-key-here",
  },

  // ...
});
Alternatively, set API key via a system environment variable
To set the environment variable on your machine, it needs to be prefixed with either CYPRESS_ or cypress_.
export CYPRESS_MAILOSAUR_API_KEY=your-key-here
Writing your first test
In this example, we’ll navigate to a password reset page, request a new password link (sent via email) and get that email.
touch cypress/e2e/password-reset.cy.js
Now edit the file to something like this:
describe('Password reset', () =&gt; {
  const serverId = 'SERVER_ID'; // Replace SERVER_ID with an actual Mailosaur Server ID
  const testEmail = `something@${serverId}.mailosaur.net`

  it('Makes a Password Reset request', () =&gt; {
    cy.visit('https://github.com/password_reset')
    cy.title().should('equal', 'Forgot your password?')
    cy.get('#email_field').type(testEmail)
  })

  it('Gets a Password Reset email', () =&gt; {
    cy.mailosaurGetMessage(serverId, {
      sentTo: testEmail
    }).then(email =&gt; {
      expect(email.subject).to.equal('Reset your password');
      passwordResetLink = email.text.links[0].href;
    })
  })

  it('Follows the link from the email', () =&gt; {
    const validPassword = 'delighted cheese jolly cloud'

    cy.visit(passwordResetLink)
    cy.title().should('contain', 'Change your password')
    cy.get('#password').type(validPassword)
    cy.get('#password_confirmation').type(validPassword)
    cy.get('form').submit()
  })
})
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

cy.mailosaurGetMessage('SERVER_ID', {
  sentTo: '...'
}, {
  receivedAfter: testStart
}).then(message =&gt; {
  cy.log(message.subject)
})
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.


Email not found in time?
By default, the mailosaurGetMessage command only looks for emails that were received by Mailosaur within the last hour.
You can override this by setting receivedAfter, like so:
cy.mailosaurGetMessage(serverId, {
  sentTo: testEmail
}, {
  // Find messages received since Jan 1st 2020. This will be slow!
  receivedAfter: new Date('2020-01-01T00:00:00Z')
})
Common test cases
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
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.
cy.mailosaurGetMessage(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.
cy.mailosaurGetMessage('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}).then((message) =&gt; {
  cy.log('Message subject:', message.subject);
});
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).


cy.mailosaurGetMessage('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}, {
  // Search all messages received after midnight 5th Feb 2020
  receivedAfter: new Date(2020, 1, 5)
});
cy.mailosaurListMessages(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 mailosaurGetMessageById. Alternatively, we recommend using the mailosaurGetMessage method, which is a far more efficient approach.```js
// List the most recent messages
cy.mailosaurListMessages(&#39;SERVER_ID&#39;).then((result) =&gt; {
  // Get the most recent message (the first one in the list)
  const message = result.items[0];
  cy.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
cy.mailosaurListMessages(&#39;SERVER_ID&#39;, {
  page: 0,
  itemsPerPage: 10,
  receivedAfter: new Date(2020, 1, 3)
});
cy.mailosaurSearchMessages(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 mailosaurGetMessageById. Alternatively, we recommend using the mailosaurGetMessage method, which is a far more efficient approach.```js
cy.mailosaurSearchMessages(&#39;SERVER_ID&#39;, {
  sentTo: &#39;someone@SERVER_ID.mailosaur.net&#39;
}).then((result) =&gt; {
  // Get the most recent match
  const message = result.items[0];
  cy.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.
cy.mailosaurSearchMessages(&#39;SERVER_ID&#39;, {
  sentTo: &#39;someone@SERVER_ID.mailosaur.net&#39;
}, {
  page: 0,
  itemsPerPage: 10,
  receivedAfter: new Date(2020, 1, 3)
});
cy.mailosaurGetMessagesBySubject(server, subject)
Shorthand for a mailosaurSearchMessages query on message subject. 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.
cy.mailosaurGetMessagesBySubject('SERVER_ID', 'Password reset');
cy.mailosaurGetMessagesBySentFrom(server, emailAddress)
Shorthand for a mailosaurSearchMessages query on message sender. 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.
cy.mailosaurGetMessagesBySentFrom('SERVER_ID', 'someone@SERVER_ID.mailosaur.net');
cy.mailosaurGetMessagesBySentTo(server, emailAddress)
Shorthand for a mailosaurSearchMessages query on message recipient. 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.
cy.mailosaurGetMessagesBySentTo('SERVER_ID', 'someone@SERVER_ID.mailosaur.net');
cy.mailosaurGetMessagesByBody(server, text)
Shorthand for a mailosaurSearchMessages query on message body. 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.
cy.mailosaurGetMessagesBySubject('SERVER_ID', 'Hey there');
cy.mailosaurGetMessageById(id)
Retrieves the detail for a single email message. Must be used in conjunction with either mailosaurListMessages or mailosaurSearchMessages in order to get the unique identifier for the required message. We always recommend using the mailosaurGetMessage method instead.
cy.mailosaurListMessages('SERVER_ID').then((result) =&gt; {
  const messageId = result.items[0].id;

  cy.mailosaurGetMessageById(messageId).then((message) =&gt; {
    cy.log('Subject:', message.subject);
  });
});
cy.mailosaurDeleteMessage(id)
Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
cy.mailosaurDeleteMessage(messageId)
cy.mailosaurDeleteAllMessages(server)
Permanently deletes all messages held by the specified server. Also deletes any attachments related to each message. This operation cannot be undone.
cy.mailosaurDeleteAllMessages('SERVER_ID')
cy.mailosaurCreateMessage(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.
cy.mailosaurCreateMessage('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.

cy.mailosaurForwardMessage(messageId, messageForwardOptions)
Forwards the specified email to a verified email address.
cy.mailosaurForwardMessage('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.

cy.mailosaurReplyToMessage(messageId, messageReplyOptions)
Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails.
cy.mailosaurReplyToMessage('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.
cy.mailosaurListServers()
Returns a list of your virtual servers. Servers are returned sorted in alphabetical order.
cy.mailosaurListServers().then((result) =&gt; {
  cy.log('You have a server called:', result.items[0].name);
});
cy.mailosaurCreateServer(server)
Creates a new virtual server. Only the name property is required to create a new server via the API.
cy.mailosaurCreateServer({
  name: 'My email tests'
});
cy.mailosaurGetServer(id)
Retrieves 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);
});
cy.mailosaurGetServerPassword(id)
Retrieves 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);
});
cy.mailosaurUpdateServer(server)
Updates a single server.
retrievedServer.name = 'Updated server name';

cy.mailosaurUpdateServer(retrievedServer);
cy.mailosaurDeleteServer(id)
Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.
cy.mailosaurDeleteServer('SERVER_ID');
cy.mailosaurGenerateEmailAddress(id)
Utility method to help you generate a random email address for a given server.
cy.mailosaurGenerateEmailAddress('SERVER_ID').then((emailAddress) =&gt; {
  cy.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
cy.mailosaurDownloadMessage(messageId)
Downloads an EML file representing the specified email. Simply supply the unique identifier for the required email.
cy.mailosaurDownloadAttachment(attachmentId)
Downloads a single attachment. Simply supply the unique identifier for the required attachment.
Analysis
cy.mailosaurGetSpamAnalysis(messageId)
Perform spam testing on the specified email.

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

How to test email and SMS with Cypress

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!
1. Get what you need from Mailosaur
To write Mailosaur tests, you will need a Server ID, Server Domain, and an API key to test with.
These attributes can all be accessed via the API tab within the Mailosaur Dashboard.
For more information: Learn more about Server IDs &amp; Domains or API Keys.
2. Create a Playwright test that triggers an email
First, you will need a test that causes an email to be sent - for example an account verification or, in this example, a password reset:
const playwright = require('playwright');
const assert = require('chai').assert;

(async () =&gt; {
  const serverId = 'abcd1234';
  const serverDomain = 'abcd1234.mailosaur.net';

  const browser = await playwright.chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();
    
  await page.goto('https://example.mailosaur.com/password-reset');
  await page.screenshot({ path: `password-request.png` });

  // Make up an email address for this test
  const randomString = new Date().getTime();
  const testEmail = `${randomString}@${serverDomain}`;

  // Request a password reset for our test email address
  await page.fill('#email', testEmail);
  await page.click('button[type="submit"]');

  await page.screenshot({ path: `password-request-sent.png` });

  await browser.close();
})();
3. Install the Mailosaur Node.js library
Because Playwright is JavaScript-based, you can easily couple it with the official Mailosaur Node.js library.
npm i -D mailosaur
# or
yarn add -D mailosaur
4. Use Mailosaur with Playwright
const playwright = require('playwright');
const assert = require('chai').assert;
const Mailosaur = require('mailosaur');

(async () =&gt; {
  const apiKey = 'YOUR_API_KEY';
  const mailosaur = new Mailosaur(apiKey);

  const serverId = 'abcd1234';
  const serverDomain = 'abcd1234.mailosaur.net';

  const browser = await playwright.chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();
    
  await page.goto('https://example.mailosaur.com/password-reset');
  await page.screenshot({ path: `password-request.png` });

  // Make up an email address for this test
  const randomString = new Date().getTime();
  const testEmail = `${randomString}@${serverDomain}`;

  // Request a password reset for our test email address
  await page.fill('#email', testEmail);
  await page.click('button[type="submit"]');

  await page.screenshot({ path: `password-request-sent.png` });

  // Search for the email
  const email = await mailosaur.messages.get(serverId, {
    sentTo: testEmail
  });

  assert.equal(email.subject, 'Set your new password for ACME Product');

  await browser.close();
})();
Email not found in time?
By default, the get method only looks for emails that were received by Mailosaur within the last hour.
You can override this by setting receivedAfter, like so:
const email = await mailosaur.messages.get(serverId, {
  sentTo: testEmail
}, {
  // Find messages received since Jan 1st 2020.
  // Note, this will be slower than the default, so we recommend
  // you only use this during initial configuration/setup.
  receivedAfter: new Date('2020-01-01T00:00:00Z')
});
Library reference
Check out all of the methods available to the Mailosaur Node.js library.
Common test cases
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:

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!


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


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

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

Automate email and SMS testing with all the major frameworks and tools including Cypress, Selenium, Webdriver.io and Robot Framework

Frameworks and tools

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

The Messages API allows you to list, search, view, modify and create email and SMS messages within your Mailosaur account.

Messages

The Files API allows you to download files, such as message attachments, from Mailosaur.

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

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.



Using the Mailosaur API, you can write automated tests for the email and SMS messages your product sends.

Email and SMS Testing API

Using Cypress?
If you are using Cypress, check out our Cypress plugin and tutorial here!
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 Node.js
To see if you already have Node.js installed, open a terminal window and run this command:
node --version
If Node.js is installed, you’ll see a version number. If you see an error instead, then download Node.js 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
npm init -y
Install the Mailosaur Node library
Run this command to install the Mailosaur Node package:
npm i -D mailosaur
# or
yarn add -D 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.js and type or paste in this code sample, replacing the template code with the values from step 3 above:
(async () =&gt; {
  const MailosaurClient = require('mailosaur')

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

  const mailosaur = new MailosaurClient(apiKey)

  const criteria = {
    sentTo: 'anything@' + serverDomain
  }

  const email = await mailosaur.messages.get(serverId, criteria)

  console.log(`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:
node hello.js
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:
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.


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 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.

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

How to test email and SMS in Node.js

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.

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

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 5th Jan 2020
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 3rd January 2020
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 test email and SMS messages in Java, using Mailosaur.

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 5th Jan 2020
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 3rd January 2020
// 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 3rd Jan 2020. 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.

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

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 5th Jan 2020
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 3rd January 2020
// 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 3rd Jan 2020. 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 test email and SMS messages in Golang, using Mailosaur.

How to test email and SMS in Go

Automate email and SMS testing with any language or framework using 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.

Learn how to test the text content of email or SMS with Mailosaur.

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:

Learn how to work with the HTML content found within your emails.

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.

Learn how to test verification codes found in email and SMS messages with Mailosaur.

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.

Learn how to test hyperlinks found in email and SMS messages with Mailosaur.

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:

Learn how to test the email attachments with Mailosaur.

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 how to work with images, including web beacons, within a HTML email.

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 message 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:

Learn how to test the SpamAssassin score of an email with Mailosaur.

How to test email spam score

Learn how to perform common email and SMS tests with Mailosaur

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 test multifactor authentication using virtual authentication devices and/or SMS testing with Mailosaur.

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

Learn how to use our virtual SMTP/SMS servers to our guides and API documentation to learn how to test email and SMS with Mailosaur.

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.


Managing your Mailosaur API keys at both an account and server level.

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.

Verify ownership of email addresses outside of Mailosaur. Allowing you to send, reply and forward 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



If your corporate network blocks unknown IP addresses or port numbers, this page explains what you’ll need to configure in order for Mailosaur to work.

IP addresses and ports

You can invite other members of your team to access your Mailosaur account. To limit the actions they can perform, user permissions can be configured as required.
Team members and permissions are managed via the Users screens within the Mailosaur UI. You can invite team members via email.
Managing Permissions
There are two main user roles that you can choose from when adding a team member to your account, each with increasing restrictions on the actions they can take:



USER TYPE
DESCRIPTION



Administrator
The user has the same level of access as the account owner and can create new servers, view API keys, invite new users, etc. Administrators cannot alter billing information or subscription settings, which the the account owner can.


User
This user cannot manage team members, create/edit/delete servers nor manage billing information on your Mailosaur account.


Account Owners
The Account Owner is, by default, the user who originally created the Mailosaur account. They have full access to all features within the Mailosaur UI, and can also manage billing and subscription settings.
If you are the current Account Owner, you can transfer this ownership to someone else simply by navigating to a user, and clicking the Transfer Ownership button.

Control how your team members are able to access your Mailosaur account.

Managing Users and Permissions

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).



Manage the access granted to your users using the SCIM API.

SCIM

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.

Secure the Mailosaur Dashboard using your organisation’s SAML or OpenID Connect Identity Provider.

Single sign-on

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


Learn how to use the Dashboard to operate your Mailosaur account.