# How to test email and SMS in Java Learn how to automate testing of email and SMS messages in Java, using Mailosaur. ## 1. Create a Mailosaur account If you already have an account, skip to step 2. To create a new trial account, [sign up here](/app/signup). ## 2. Create a sample project This guide makes use of JUnit, therefore create an empty Java & JUnit project to begin. ### Install the Mailosaur Java library **Gradle users** can add this dependency to their project’s build file: ```java // 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: ```xml com.mailosaur mailosaur-java MAILOSAUR_JAVA_VERSION ``` If you don’t use Gradle or Maven, refer to the README within the [GitHub repository](https://github.com/mailosaur/mailosaur-java). ## 3. Send email to your Mailosaur inbox Inboxes allow you to group tests, permissions, and other settings together. Each inbox has an **Inbox ID** and 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](/docs/managing-your-account/api-keys) to use. You can learn more about [creating API keys here](/docs/managing-your-account/api-keys). ### Retrieve your inbox’s attributes 1. In the left-hand navigation, locate the **Inboxes** section. 2. Click on the name of the inbox you want to test with. 3. Click the **Settings** tab. 4. Make a note of the **Inbox ID** and **Domain**. 5. Get an API key from the [API Keys](/app/keys) page. ### Send an email to your inbox If the **domain name** of your inbox above was: ```bash example.mailosaur.net ``` Then you can send an email to it with these steps: 1. Open up an email client and send an email to `anything@example.mailosaur.net` 2. In the left-hand navigation, locate the **Inboxes** section. 3. Click on the name of the inbox you sent an email to. 4. Confirm the email is there. Note that some services (like Gmail) may take 10-20 seconds to send a message through. To learn more, read our guide on [sending email to Mailosaur](/docs/email-testing/sending-to-mailosaur). ## 4. Find an email for automated testing Now that you have a sample project, your inbox’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: ```java 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 { // Find these on the API Keys page and your inbox's Settings tab 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, 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: ```java Date testStart = System.currentTimeMillis(); // 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 these criteria: | 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: > [!LINK](/docs/automation/text-content) > ### How to test the text content of email or SMS > Learn how to test the text content of email or SMS with Mailosaur. > [!LINK](/docs/automation/html-content) > ### HTML content of an email > Learn how to work with the HTML content found within your emails. > [!LINK](/docs/automation/codes) > ### Extracting codes from email and SMS > Learn how to test verification codes found in email and SMS messages with Mailosaur. > [!LINK](/docs/automation/links) > ### Extracting links from email and SMS > Learn how to test hyperlinks found in email and SMS messages with Mailosaur. > [!LINK](/docs/automation/attachments) > ### Email attachments > Learn how to test the email attachments with Mailosaur. > [!LINK](/docs/automation/images) > ### Images and web beacons > Learn how to work with images, including web beacons, within an HTML email. > [!LINK](/docs/automation/message-properties) > ### Message properties > Learn how to test the common properties of an email or SMS message with Mailosaur. > [!LINK](/docs/automation/spam) > ### How to test email spam score > Learn how to test the SpamAssassin score of an email with Mailosaur. ## SMS Testing You can test SMS messages in much the same way as email. Take a look at our [guide on testing SMS messages](/docs/sms-testing) 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](/docs/api) contains everything you need to perform in-depth automated testing. #### messages.get(MessageSearchParams, SearchCriteria) 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. ```java 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 inbox IDs, and what to replace `SERVER_ID` with, see [sending email to Mailosaur](/docs/email-testing/sending-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_). | ```java MessageSearchParams params = new MessageSearchParams(); params.withServer("SERVER_ID") .withReceivedAfter(1578182400000L); SearchCriteria criteria = new SearchCriteria(); criteria.withSentTo("someone@SERVER_ID.mailosaur.net"); // Search all messages received after midnight on a specific date Message message = mailosaur.messages().get(params, criteria); ``` #### messages.list(MessageListParams) 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. > [!SUCCESS] > 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`](#messagesgetbyidid). Alternatively, we recommend using the [`get`](#messagesgetserver-criteria-options) method, which is a far more efficient approach. ```java // List the most recent messages MessageListParams params = new MessageListParams(); params.withServer("SERVER_ID"); 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("Subject: " + message.subject()); ``` ##### Options - **receivedAfter** Allows you to customise how far back to look for messages (time in milliseconds). - **page** Used alongside `itemsPerPage` to paginate through results. This is zero-based, meaning `0` is the first page of results. - **itemsPerPage** A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50. - **dir** Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`. ```java // List all results received after midnight on a specific date MessageListParams params = new MessageListParams(); params.withServer("SERVER_ID").withReceivedAfter(1577836800000L); MessageListResult result = mailosaur.messages().list(params); ``` #### messages.search(MessageSearchParams, SearchCriteria) 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. > [!SUCCESS] > 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`](#messagesgetbyidid). Alternatively, we recommend using the [`get`](#messagesgetserver-criteria-options) method, which is a far more efficient approach. ```java MessageSearchParams params = new MessageSearchParams(); params.withServer("SERVER_ID"); SearchCriteria criteria = new SearchCriteria(); criteria.withSentTo("someone@SERVER_ID.mailosaur.net"); MessageListResult result = mailosaur.messages().search(params, criteria); // Get the most recent match MessageSummary message = result.items().get(0); System.out.println("Subject: " + 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 thrown if timeout is reached (default: `true`). - **receivedAfter** Allows you to customise how far back to look for messages (time in milliseconds). - **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("SERVER_ID") .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`](#messageslistserver-options) or [`search`](#messagessearchserver-criteria-options) in order to get the unique identifier for the required message. **We always recommend using the** [`get`](#messagesgetserver-criteria-options) **method instead**. ```java 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. ```java mailosaur.messages().delete(messageId); ``` #### messages.deleteAll(server) Permanently deletes all messages held in the specified inbox. Also deletes any attachments related to each message. This operation cannot be undone. ```java 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. ```java 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. ```java 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 plain text content to forward the email with. - **html** Any additional HTML 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. ```java 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 Inboxes capture emails and SMS messages, group your tests and settings, and manage access for your team. #### servers.list() Returns a list of your inboxes. Inboxes are returned sorted in alphabetical order. ```java ServerListResult result = mailosaur.servers().list(); System.out.println("You have an inbox called: " + result.items().get(0).name()); ``` #### servers.create(server) Creates a new inbox. Only the `name` property is required to create a new inbox via the API. ```java ServerCreateOptions options = new ServerCreateOptions().withName("My email tests"); mailosaur.servers().create(options); ``` #### servers.get(id) Retrieves the detail for a single inbox. Simply supply the unique identifier for the required inbox. ```java Server server = mailosaur.servers().get("SERVER_ID"); ``` #### servers.getPassword(id) Retrieves the password, for use with SMTP and POP3, for a single inbox. Simply supply the unique identifier for the required inbox. ```java String password = mailosaur.servers().getPassword("SERVER_ID"); ``` #### servers.update(id, server) Updates a single inbox. ```java Server retrievedServer = mailosaur.servers().get("SERVER_ID"); retrievedServer.withName("Updated inbox name"); mailosaur.servers().update(retrievedServer.id(), retrievedServer); ``` #### servers.del(id) Permanently deletes an inbox. Also deletes all messages and associated attachments within the inbox. This operation cannot be undone. ```java mailosaur.servers().delete("SERVER_ID"); ``` #### servers.generateEmailAddress(id) Utility method to help you generate a random email address for a given inbox. ```java String emailAddress = mailosaur.servers().generateEmailAddress("SERVER_ID"); System.out.println(emailAddress); // "bgwqj@SERVER_ID.mailosaur.net" ``` To learn about inbox IDs, and what to replace `SERVER_ID` with, see [sending email to Mailosaur](/docs/email-testing/sending-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.