Fundamental Concepts

How it works

To get started with Mailstack, you first need to create an account. The easiest way to do this is by registering using social authentication through Google, LinkedIn, or GitHub. Alternatively, you can use the standard registration form.

Once your account is successfully created, we will prepare a default mailbox and an API key for you. This default API key will be authorized to access the default mailbox.

From the console, you can create an unlimited number of new mailboxes and API keys. For each API key, you should specify the mailboxes that can be accessed with that key.

Additionally, you will be able to create virtual MFA (Multi-Factor Authentication) devices that function like Google Authenticator or similar apps. You can enter a QR code, and our API will generate and provide the OTP code, allowing you to automate your tests or RPA processes.

Sending Test Emails

You can send your test emails to:

{tag}.{mailboxid}@mailstack.expandtesting.com

tag: This can be anything, like a username or a team name, allowing you to create unlimited email addresses on the fly.
mailboxid: This is the unique reference for your mailbox.

Example

If the mailbox ID is b301a2, the following email addresses are valid:

anything.b301a2@mailstack.expandtesting.com
john.doe.b301a2@mailstack.expandtesting.com
jane.doe.support.b301a2@mailstack.expandtesting.com
support.b301a2@mailstack.expandtesting.com

Using the API

You can now use our free REST API to retrieve received emails. You can also use the realtime query parameter to wait for new incoming emails for a specified mailbox.

The API endpoint format is:

https://mailstack.expandtesting.com/api/query?apikey={apikey}&mailbox={mailbox}

You can get the values of apikey and mailbox from the console.

You can also search for a specific tag filter by adding the tag as a query parameter.

Let me give you an example:

Given this email address: contact.b301a2@mailstack.expandtesting.com

If you want to retrieve emails sent to the 'contact' tag and the b301a2 mailbox, you can use this request:

 https://mailstack.expandtesting.com/api/query?apikey=96e33757f23a91&mailbox=b301a2&tag=contact

In addition to the previous filter, you can also apply a date filter (unix timestamp) by using from_timestamp and to_timestamp in your query. Look at this example:

https://mailstack.expandtesting.com/api/query?apikey=96e33757f23a91&mailbox=b301a2&from_timestamp=1697836800000&to_timestamp=1697923200000

You can use the from_timestamp and to_timestamp filters together or only one of them

Example Endpoint

https://mailstack.expandtesting.com/api/query?apikey=96e33757f23a91&mailbox=b301a2

This works with any HTTP client, even your browser! If you’re uncomfortable using the API key as a query parameter, you can also include it in your request headers.

API Response

The API will return the result as a JSON object. Here are some key concepts:

Without the realtime query parameter, the API will respond immediately and will not wait for new incoming emails.
With the realtime query parameter, the API will wait for new incoming mail if no results match the specified search criteria.
In realtime mode, you don’t need to recall the API or make polling requests. After 1 minute of waiting, the API will return a 307 HTTP redirect to itself, so your client will automatically resend the same request.
Your script should handle timeouts when using realtime.

Deleting Emails via the API

In the MailStack API, you can delete emails associated with a mailbox or delete a specific email by its ID. This section outlines how to perform these deletion operations and the expected responses.

Deleting Emails Associated with a Mailbox

To delete all emails associated with a specific mailbox, send a DELETE request to the following endpoint:

DELETE https://mailstack.expandtesting.com/api/mailboxes/{mailbox}/emails?apikey={apikey}

Parameters:

apikey: Your API access key. You can include it as a query parameter or in the request headers. For example, in headers:

headers: { "apikey": "your_api_key" }

mailbox: The ID of the mailbox from which you want to delete all associated emails.

Example Request:

DELETE https://mailstack.expandtesting.com/api/mailboxes/b301a2/emails?apikey=your_api_key

Alternative Request with Header:

DELETE https://mailstack.expandtesting.com/api/mailboxes/b301a2/emails
{
    "headers": { "apikey": "your_api_key" }
}

Response:

{
    "result": "success",
    "message": "All emails associated with the mailbox [b301a2] have been deleted."
}

If there’s an error, you may receive:

{
    "result": "fail",
    "message": "An error occurred while deleting emails."
}

Deleting a Specific Email by ID

To delete a specific email by its ID, use the following endpoint:

DELETE https://mailstack.expandtesting.com/api/mailboxes/{mailbox}/emails/{emailid}?apikey={apikey}

Parameters:

apikey: Your API access key. You can include it as a query parameter or in the request headers.
emailid: The ID of the email you wish to delete.
mailbox: The ID of the mailbox from which you want to delete the specific Email.

Example Request:

DELETE https://mailstack.expandtesting.com/api/mailboxes/b301a2/emails/abc123?apikey=your_api_key

Alternative Request with Header:

DELETE https://mailstack.expandtesting.com/api/mailboxes/b301a2/emails/abc123
{
    "headers": { "apikey": "your_api_key" }
}

Response:

{
    "result": "success",
    "message": "Email deleted successfully."
}

If the email ID is not found, you may receive:

{
    "result": "fail",
    "message": "Email not found."
}

In case of an error:

{
    "result": "fail",
    "message": "An error occurred while deleting emails."
}

Important Notes

Deletion actions are irreversible. Once an email or all emails associated with a mailbox are deleted, they cannot be restored.
Ensure that you have appropriate permissions and that you are aware of the impact of deleting emails in your account.

Multi-Factor Authentication (MFA, 2FA)

Our API offers the possibility to create virtual MFA devices that act like Google Authenticator, Microsoft Authenticator, and compatible tools, exposing the OTP code over a secure API. You can create a virtual device by scanning a QR code or entering the secret manually. After creating and associating an API key, you will be able to use our free API to generate the OTP.

This can be really helpful for automated end-to-end testing of our RPA processes, ensuring that your tests will not be broken due to multi-factor authentication.

Using the API

Once the virtual device is created, you can use our API by calling this endpoint:

https://mailstack.expandtesting.com/api/mfa/otp?apikey={apikey}&deviceid={deviceid}

Here, apikey is the API access key that can be created from the console, and deviceid is the ID for your virtual device, which can also be created there.

Example Endpoint

Here’s an example of the endpoint:

https://mailstack.expandtesting.com/api/mfa/otp?apikey=3d1ff0e394089b76bb887&deviceid=8446c7

You can use this API with any HTTP client or automated testing tools like Cypress, Playwright, and similar tools.

Feedback

This is the alpha version, and new capabilities will come in future releases. Some features may not work as expected, so don’t hesitate to share your feedback by email or via LinkedIn.