Getting Started with Java

Learn how to automate email testing in Java

Before you start

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

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

Installing Mailosaur

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

Maven users



You’ll need to manually install the following JARs:

Authenticating with Mailosaur

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

Retrieving an email

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

// 1. Create an instance of the MailosaurClient, using your API key
MailosaurClient client = new MailosaurClient("{API_KEY}");

// 2. Build search criteria to find the email you have sent
SearchCriteria criteria = new SearchCriteria();

// 3. Wait for the message (by default only looks for the most recent message received in the last hour)
Message message = client.messages().get("{SERVER_ID}", criteria);

// 4. Assert that the email subject is what we expect
assertEquals("Reset your password", message.subject());

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

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

// Wait for message
Message message = client.messages().get("{SERVER_ID}", criteria);

// Check that we have the password reset email
assertEquals("Reset your password",;

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

Extracting content from email HTML

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

Let’s imagine that message.html().body() contains:

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

To work with the email’s HTML, install jsoup. For example, with Maven:


Import dependencies at the top of your test file:

import org.jsoup.Jsoup;
import org.jsoup.nodes.Document;

Now, you can extract the verification code as follows:

// Wait for the message
Message message = client.messages().get("{SERVER_ID}", criteria);

// Extract the verification code from HTML
Document doc = Jsoup.parse(message.html().body());
Elements elements = doc.getElementsByTag(".verify-code");
String verificationCode = elements.get(0).text();