Upgrading your Mailosaur tests

Some of our legacy API endpoints are being removed. Use this guide to quickly upgrade your project.

What is changing?

Some of our very old, legacy API endpoints will soon be removed from Mailosaur. In addition, we are increasing security by no longer supporting API authentication via querystring parameters.

What do I need to do

All customers who use version 5 or older of our official client library/SDK must upgrade to the latest version. We have created migration guides for version 5 and version 3 and 4 users.

Customers who have written custom code to make API requests (e.g. integrating with a 3rd-party monitoring tool), will need to check our guide on custom code migration.

Migrating from version 5

If you use v5 of the Node, .NET, Java, Ruby, Python or PHP libraries, then the migration is very simple. In short, the old get method has been replaced by getById, whilst waitFor has been renamed to get.

get(id) renamed to getById(id)

If you previously used get to retrieve an email by ID, then you can simply replace this code with a call to the getById method:

const email = await mailosaur.messages.getById('{ID}')
email = mailosaur.messages.get_by_id("{ID}")
Message email = mailosaur.messages().getById("{ID}");
var email = mailosaur.Messages.GetById("{ID}");
email = mailosaur.messages.get_by_id("{ID}")
$email = $mailosaur->messages->getById("{ID}");

waitFor(serverId, criteria) renamed to get(serverId, criteria)

If you use the waitFor method, this must be renamed to get instead:

const email = await mailosaur.messages.get(serverId, criteria)
email = mailosaur.messages.get(server_id, criteria)
Message email = mailosaur.messages().get(serverId, criteria);
var email = mailosaur.Messages.Get(serverId, criteria);
email = mailosaur.messages.get(server_id, criteria)
$email = $mailosaur->messages->getById(serverId, criteria);

Migrating from version 3 or 4

Creating an instance of the client

In v3, a client instance was created per server (mailbox). Instead, you now just create one instance, that can be used across different servers:

// Old (Bad)
var Mailosaur = require('mailosaur')(apiKey),
  mailbox = new Mailosaur.Mailbox(serverId);

// New (Good)
var MailosaurClient = require('mailosaur'),
  mailosaur = new MailosaurClient(apiKey);
# Old (Bad)
from mailosaur.mailosaur import Mailosaur
mailbox = Mailosaur(server_id, api_key)

# New (Good)
from mailosaur import MailosaurClient
mailosaur = MailosaurClient(api_key)
// Old (Bad)
MailboxApi mailbox = new MailboxApi(serverId, apiKey);

// New (Good)
MailosaurClient mailosaur = new MailosaurClient(apiKey);
// Old (Bad)
var mailbox = new MailboxApi(serverId, apiKey);

// New (Good)
var mailosaur = new MailosaurClient(apiKey);
# Old (Bad)
mailbox = Mailosaur.new(server_id, api_key)

# New (Good)
mailosaur = Mailosaur::MailosaurClient.new(api_key)
// Old (Bad)
$mailbox = new MailosaurClient(apiKey, serverId);

// New (Good)
$mailosaur = new MailosaurClient(apiKey);

Replacing getEmailsByRecipient

To find the most recent email sent to a recipient, you use the get method, instead of getEmailsByRecipient:

// Old (Bad)
var emails = await mailbox.getEmailsByRecipient('anything.1eaaeef6@mailosaur.io');
var email = emails[0];

// New (Good)
var email = await mailosaur.messages.get('1eaaeef6', {
sentTo: 'anything.1eaaeef6@mailosaur.io'
});
# Old (Bad)
emails = mailbox.get_emails_by_recipient('anything.1eaaeef6@mailosaur.io')
email = emails[0]

# New (Good)
criteria = SearchCriteria()
criteria.sent_to = "anything.1eaaeef6@mailosaur.io"
email = mailosaur.messages.get('1eaaeef6', criteria)
// Old (Bad)
Email[] emails = mailbox.getEmailsByRecipient("anything.1eaaeef6@mailosaur.io");
Email email = emails.get(0);

// New (Good)
SearchCriteria criteria = new SearchCriteria();
criteria.withSentTo("anything.1eaaeef6@mailosaur.io");
Message email = mailosaur.messages().get("1eaaeef6", criteria);
// Old (Bad)
var emails = mailbox.GetEmailsByRecipient("anything.1eaaeef6@mailosaur.io");
var email = emails[0];

// New (Good)
var criteria = new SearchCriteria() {
SentTo = "anything.1eaaeef6@mailosaur.io"
};
var email = mailosaur.Messages.Get("1eaaeef6", criteria);
# Old (Bad)
emails = mailbox.get_emails_by_recipient('anything.1eaaeef6@mailosaur.io')
email = emails[0]

# New (Good)
criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = "anything.1eaaeef6@mailosaur.io"
email = mailosaur.messages.get("1eaaeef6", criteria)
// Old (Bad)
$emails = $mailbox->getEmailsByRecipient('anything.1eaaeef6@mailosaur.io');
$email = $emails[0];

// New (Good)
$criteria = new SearchCriteria();
$criteria->sentTo = 'anything.1eaaeef6@mailosaur.io';
$email = $mailosaur->messages->get('1eaaeef6', $criteria);

Replacing getEmails(searchPattern)

We strongly recommend, using the same code as shown above for replacing getEmailsByRecipient. The get method can be used with different search criteria (sentTo, subject, body) depending on your needs.

If you are attempting to find multiple matches (instead of the most recent matching email), you can use the search method instead, which is described elsewhere in our documentation.

Replacing getEmail(emailId)

To retrieves a given email by its ID, you can use the getById method:

const email = await mailosaur.messages.getById('{ID}')
email = mailosaur.messages.get_by_id("{ID}")
Message email = mailosaur.messages().getById("{ID}");
var email = mailosaur.Messages.GetById("{ID}");
email = mailosaur.messages.get_by_id("{ID}")
$email = $mailosaur->messages->getById("{ID}");

Replacing deleteAllEmail()

This can now by done as follows:

await mailosaur.messages.deleteAll('SERVER_ID')
mailosaur.messages.delete_all("SERVER_ID")
mailosaur.messages().deleteAll("SERVER_ID");
mailosaur.Messages.DeleteAll("SERVER_ID");
mailosaur.messages.delete_all("SERVER_ID")
$mailosaur->messages->deleteAll('SERVER_ID');

Replacing deleteEmail(emailId)

To delete a single email, use this code instead:

const email = await mailosaur.messages.del('{ID}')
email = mailosaur.messages.delete("{ID}")
Message email = mailosaur.messages().delete("{ID}");
var email = mailosaur.Messages.Delete("{ID}");
email = mailosaur.messages.delete("{ID}")
$email = $mailosaur->messages->delete("{ID}");

Replacing generateEmailAddress()

This method generates a random email address which can be used to send emails into a server. This can be called like this now instead:

const email = await mailosaur.servers.generateEmailAddress('{SERVER_ID}')
email = mailosaur.servers.generate_email_address("{SERVER_ID}")
Message email = mailosaur.servers().generateEmailAddress("{SERVER_ID}");
var email = mailosaur.Servers.GenerateEmailAddress("{SERVER_ID}");
email = mailosaur.servers.generate_email_address("{SERVER_ID}")
$email = $mailosaur->servers->generateEmailAddress("{SERVER_ID}");

Migrating custom code

If you have written your API requests using your own code/API client, then you will need to update this code as follows:

Handling authentication

If you are currently passing the API key via a query string parameters (i.e. ?key={API_KEY} or &key={API_KEY}), then you must change this to use HTTP Basic Auth. Your API key must be provided as the basic auth username value. You do not need to provide a password.

curl https://mailosaur.com/api/servers \
  -u YOUR_API_KEY:

Handling calls to redundant endpoints

The following endpoints will soon be removed from the API, therefore you must migrate away from them:

Finding emails

Any calls to the /api/mailboxes/{id}/emails must be replaced by the search endpoint.

Important: Unlike the old mailboxes endpoint, only an email summary will be returned for a search. To get the full message content, you must make a follow-up request to retrieve a message.

Emptying a server

This endpoint can be replaced as follows (see documentation):

# Old (Bad)
POST /api/mailboxes/{SERVER_ID}/empty

# New (Good)
DELETE /api/messages?server={SERVER_ID}

Delete a single email

This endpoint can be replaced as follows (see documentation):

# Old (Bad)
POST /api/emails/{MESSAGE_ID}/delete

# New (Good)
DELETE /api/messages/{MESSAGE_ID}

Fetch an attachment

This endpoint can be replaced as follows (see documentation):

# Old (Bad)
GET /api/attachments/{ATTACHMENT_ID}

# New (Good)
GET /api/files/attachments/{ATTACHMENT_ID}

Waiting for a single message to arrive

The /api/messages/await endpoint is being removed, which means you must now handle waiting for a message to arrive on the client-side. We strongly recommend using one of our official client libraries to do this. If you are unable to do this, we would recommend that you contact support for help on this.

Need help?

Contact us via chat or email if you need any help with your code.