MailSlurp is a Web service that provides dummy email addresses and an API to send and receive them. This is mainly used for testing and development purposes. This is only available in English.
There are free and charged versions, with the free version having the following limitations.
- Email address has an expiration date, and after the expiration date, the email address becomes invalid and the received email disappears.
- Only 50 email addresses can be generated per month.
- Only 100 emails can be sent and received, respectively, each month.
For details, please check the Price chart. If you use the Starter plan, you will likely face few issues in terms of practical application.
Table of contents
1. How to Create Email Tests
1-1. Obtain the API access key
Create an account using the Sign up button on the top-right of the homepage, and after logging in, copy API access key on Dashboard.
1-2. Obtain the Inbox ID
Generate the email address to be used in the test.
As a random value will be generated, copy the Inbox ID of an inbox that does not contain a domain.
1-3. Define variables and set "API access key" and "Inbox ID"
Define MAIL_API_KEY in the MagicPod secret shared variable, and set the copied API access key.
Then, using the command Store fixed value, define Inbox_ID, and set the copied Inbox ID.
1-4. Empty the Inbox by the "Web API call" command
The method described here retrieves the first email in the inbox. Empty the inbox first, as multiple emails in the inbox may result in retrieval of non-target emails. This Web API call should be executed before any email is sent, such as a click on the user registration button.
Next, copy this json type text and paste it into the test case edit screen with ctrl + V (command + V on Mac OS). A Web API call step will then be added to empty the Inbox.
{"command_calls": [{"command": "web_api","val": [{"url": "https://api.mailslurp.com/emails","method": "delete","header": [{"key": "x-api-key","value": "${MAIL_API_KEY}"}],"body": {"format": "raw","form_data": [],"raw": ""},"result": {"params": []}}]}],"project_id": 0,"version": "0"}
Executing this will empty the inbox.
If adding a step by copy and paste fails, add a Web API call step and set the following items:
Method: DELETE
URL: https://api.mailslurp.com/emails
Header: "x-api-key" as key, "${MAIL_API_KEY}" as value
1-5. Obtain "Mail ID" and "Title of the email" by the "Web API call" command
Obtain one Mail ID. The title of the email can also be obtained at the same time. Copy this json type text and paste it into the test case edit screen with ctrl + V (command + V on Mac OS). A Web API call step will then be added to obtain one Mail ID in the Inbox.
{"command_calls": [{"command": "web_api","val": [{"url": "https://api.mailslurp.com/inboxes/${INBOX_ID}/emails?minCount=1","method": "get","header": [{"key": "x-api-key","value": "${MAIL_API_KEY}"}],"result": {"params": [{"key": "MAIL_ID","value": "jsonResponse[0][\"id\"]"},{"key": "タイトル","value": "jsonResponse[0][\"subject\"]"}]}}]}],"project_id": 0,"version": "0"}
Executing this will set the variable MAIL_ID to the mail ID and set the variable Title to the title of the email.
If adding a step by copy and paste fails, add a Web API call step and set the following items:
Method: GET
URL: https://api.mailslurp.com/inboxes/${INBOX_ID}/emails?minCount=1
Header: "x-api-key" as key, "${MAIL_API_KEY}" as value
Results: "MAIL_ID" as Variable, "jsonResponse[0]["id"]" as Javascript
"Title" as Variable, "jsonResponse[0]["subject"]" as Javascript
- minCount=1 in the URL means to wait until the total number of emails in the inbox is greater than or equal to one. This value can be modified.
- [0] in the Results refers to the first email. 1 refers to the second email, 2 refers to the third...and so on. (There is also an option to put the latest one at the front, but this did not work very well. )
1-6. Retrieve the body of the email by the "Web API call" command
Finally, retrieve the body of the email based on the mail ID obtained in step 1-5. Copy this json type text and paste it into the test case edit screen with ctrl + V (command + V on Mac OS). A Web API call step will then be added to retrieve the body of the email based on the Mail ID obtained in steps 1-5.
{"command_calls": [{"command": "web_api","val": [{"url": "https://api.mailslurp.com/emails/${MAIL_ID}/textLines","method": "get","header": [{"key": "x-api-key","value": "${MAIL_API_KEY}"}],"result": {"params": [{"key": "MAIL_CONTENTS","value": "jsonResponse[\"lines\"]"}]}}]}],"project_id": 0,"version": "0"}
Executing this will set the variable MAIL_CONTENTS to the contents of the email.
If adding a step by copy and paste fails, add a Web API call step and set the following items:
Method: GET
URL: https://api.mailslurp.com/emails/${MAIL_ID}/textLines
Header: "x-api-key" as key, "${MAIL_API_KEY}" as value
結果: "MAIL_CONTENTS" as Variable, "jsonResponse["lines"]" as Javascript
- If you want to retrieve the body text in html, specify "https://api.mailslurp.com/emails/${MAIL_ID}/html" in the URL.
1-7. Note
- The content of the sent email can be confirmed on the MailSlurp Dashboard.
- MailSlurp includes various other API, such as those shown below. For details, check the MailSlurp documentation.
- Acquire the part matching the CSS selector from the main text of an HTML email (/emails/${MailID}/htmlQuery)
- Acquire the part matching a regular expression from the main text of an HTML email (/emails/${MailID}/contentMatch)
- Wait until an email matching specified criteria is found in the inbox, and retrieve its contents when found (/waitForMatchingEmails)
- Delete mail address (DELETE method/inboxes/${Inbox_ID})
- Send email (POST method /inboxes/${Inbox_ID})
- Acquire email header information (acquire data with jsonResponse["headers"]["HeaderName"] based on results of /emails/${MailID})
2. Examples of Test Case Steps
2-1. Transition to the URL included in the body of the email
Let's create a test in which the user registers as a new member by navigating to the URL included in the email.
- Click the "Register" button on the application to be tested.
- An email is sent to the newly registered email address.
- Click on the URL in the email to complete the membership registration.
Dear XXX
Thank you for registering.
Please log in using the link below within one hour of receipt.
https://example.com/qwertyuiop123456789
In this case, please add the following test case steps.
In this case, you can store just the URL into the URL variable by specifying the following regular expression in the step13 Store substring matching regular expression command.
https:\/\/example.com\/.+
2-2. Enter the authentication code included in the body of the email in the app
Let's create a test in which new member registration is performed by entering the authentication code contained in the email into the app to be tested.
- Press the "Register" button in the app to be tested.
- An email will be sent to the newly registered email address.
- Enter the authentication code in the email into the app to complete the membership registration.
Dear XXX
Thank you for registering.
Please log in within 1 hour of receipt and enter the authentication code below.
Authentication code: 123456
In this case, please add the following test case steps.
In this case, you can store just the 6-digit number into the auth_code variable by specifying the following regular expression in the step13 Store substring matching regular expression command.
[0-9]{6}
If you want to accurately extract the 6-digit number that follows the "Authentication code: ", you can use the following regular expression.
(?<=Authentication code: )([0-9]{6})
2-3. Test using a random email address
By creating an Inbox with the Web API, you can test using a different email address each time. For detailed Web API specifications, please refer to this page. Please note that the number of Inboxes that can be created each month varies depending on the subscription plan.
3. Troubleshooting
3-1. Failure to obtain the "API access key"
If the API access key is incorrect when making a Web API call, the test will fail with a Client error. Status code 401 Unauthorized error and the API response will be {"message": "User not found for API KEY `${MAIL_API_KEY}`...} is returned.
In this case, the shared variable MAIL_API_KEY is most likely incorrect. Please check the following:
- Shared variable MAIL_API_KEY is defined correctly.
- Whether you are using the test run configuration with the shared variable MAIL_API_KEY defined at the time of test run.
3-2.Failure to obtain the "Mail ID"
If no email matches the search criteria during the execution of the Web API to obtain the Mail ID, the API returns a response of {"message":"Failed to satisfy email query for inbox ID `xxx` for user ID `xxx`. Expected minimum message count of `1`. Found at most `0`...}. In this case, it is most likely that the email has not yet been received by the time the Web API call to obtain the Mail ID is made.
Please insert a Wait for fixed seconds command between the step that triggers the email sending (e.g., "Register") and the Web API call step that obtains the Mail ID, as shown below. Adjust the wait time as necessary.
If the mail still fails after adding the wait command, it may have failed to receive the mail in the first place; log in to MailSlurp and check to see if the mail is received in the target Inbox.