Fundamental Concepts

How it works

To get started with Mailstack, you first need to create an account. The easiest way is to register with social auth using Google, LinkedIn, or GitHub, but you can also use the registration form.

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

From the console, you can also create unlimited new mailboxes and API keys. For each API key, you should specify the mailboxes that can be accessed by that key.

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

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.

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.