> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/editing-tests/testing-inbox.md).

# Testing Inbox

BugBug Testing Inbox for testing sign-up, email verification, password reset and one-time codes: unique addresses with {{testRunId}}, recording, the Open inbox step, reading links and codes, clearing

The [BugBug Testing Inbox](https://bugbug-inbox.com/) receives emails sent by your app during a test, so the test can open them and click the verification link or read a code. You don't need your own mail server or a real mailbox.

{% hint style="info" %}
**In short**

* Every address `<name>@bugbug-inbox.com` works without setup. Its inbox is at `https://bugbug-inbox.com/<name>`.
* Use `{{testRunId}}@bugbug-inbox.com` to get a new, unique address in every test run.
* The **Open inbox** step opens the inbox in a new tab. Its value is only the mailbox name, the part before `@bugbug-inbox.com`.
* Emails are rendered in the inbox page itself, so you click links and save codes with normal steps.
* Inboxes are public: anyone who knows the name can read them. Use unique names and test data only.
* Emails are removed after 10 minutes.
* **Open inbox** steps are available on all paid plans. See [pricing](https://bugbug.io/pricing/).
  {% endhint %}

## How the inbox works

* **Any name works.** You don't create a mailbox. An email sent to `anything@bugbug-inbox.com` appears in the inbox `anything`. Names aren't case-sensitive.
* **Allowed characters.** A name can have letters, digits, `.`, `_`, `+` and `-`, up to 64 characters. `{{testRunId}}` has 36 characters, so you can add a short prefix.
* **Two domains.** `usebugbug.com` is an alternative domain. `anything@usebugbug.com` and `anything@bugbug-inbox.com` go to the same inbox `anything`. Use it when your app doesn't accept `bugbug-inbox.com` addresses. The recorder and the API give addresses with `bugbug-inbox.com`.
* **The name is the whole part before `@`.** `bugbugautomation+{{testRunId}}` and `{{testRunId}}` are two different inboxes.
* **To, Cc and Bcc.** An email appears in the inbox of every BugBug address it was sent to.
* **Newest first.** The inbox lists emails from the newest. New emails appear automatically, without reloading the page.
* **Search.** The search field filters emails by subject and content.
* **Retention.** Emails are removed after 10 minutes.

{% hint style="warning" %}
**Inboxes are public.** There's no login: anyone who knows or guesses the name can read the emails and clear the inbox. Use names that are hard to guess, such as `{{testRunId}}`, and don't send real personal data to the Testing Inbox.
{% endhint %}

## Get a unique address for each run

Use the [built-in variable](https://docs.bugbug.io/editing-tests/variables.md#use-built-in-variables-for-dynamic-or-random-values) `testRunId` in the address:

```
{{testRunId}}@bugbug-inbox.com
```

`testRunId` is the same in all steps of one test run and changes in the next run. Each run registers a new user, and each run reads only its own emails. Tests that run in parallel or in a suite don't get each other's emails.

You can add a prefix or other variables, for example `signup-{{testRunId}}@bugbug-inbox.com`. Then use the same name, `signup-{{testRunId}}`, in the **Open inbox** step.

{% hint style="info" %}
To read emails through the [API or MCP](#read-emails-through-the-api-or-mcp), use the name `{{testRunId}}` without a prefix, with either domain.
{% endhint %}

## Record a sign-up test with email verification

> **Test case:** I go to the sign-up page, enter a new email and a password, and submit the form. I receive a verification email and click the link. I log in with the same email and password.

1. Start recording on the page with the sign-up form and record the steps up to the email field.
2. In the recording overlay, click **Inbox**. Don't stop the recording.

   <figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FnEiwj28K9BCm1lA0N9iQ%2Finbox%20menu.png?alt=media&amp;token=45c7dfb3-2570-4146-8452-12a0f696621d" alt="Inbox option in the recording overlay"><figcaption></figcaption></figure>
3. Choose **Auto-generated random email unique for this test**. It creates the address `{{testRunId}}@bugbug-inbox.com`.

   <figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FI0zjD3V8Yj4X0QHii60T%2Finbox%20open.png?alt=media&amp;token=eefe3fef-6cf6-4960-8f1b-e57fb5a5c425" alt="Inbox options: auto-generated email and specific test email"><figcaption></figcaption></figure>
4. Copy the address with the copy icon and paste it into the email field. The recorded step uses the variable, not the address from this recording, so the next run registers a new user.

   <figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2Fcx2X7nyCfMU3jLuK5QKR%2FCopy%20icon.png?alt=media&amp;token=5eb1bc55-f756-46d2-932e-f9b7ae3c7818" alt="Copy icon next to the generated email address"><figcaption></figcaption></figure>

   <figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FfNaWVjORrYyt6uLgUjrY%2Fsteps.png?alt=media&amp;token=a0a008c8-dcbc-4780-9185-d41ac516ebfe" alt="Type text step with the testRunId email"><figcaption></figcaption></figure>
5. Fill in the rest of the form and submit it.
6. In the Inbox menu, click **Open inbox**. The inbox opens in a new tab, and BugBug records an **Open inbox** step.

   <figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FmkOstuMtUjKkvYZWbaLW%2Fopen%20inbox.png?alt=media&amp;token=0f8afda4-f776-4d9a-8e3d-31fafd404ea4" alt="Open inbox button in the overlay"><figcaption></figcaption></figure>
7. Wait for the email and click its subject.

   <figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FNW7uSzFQy4nI1Q18395B%2Fsubject.png?alt=media&amp;token=41252ac9-5902-4f80-a3e1-116c351d9b67" alt="Email list in the BugBug inbox"><figcaption><p>The BugBug confirmation email is used only as an example.</p></figcaption></figure>
8. Click the verification link or button in the email.

   <figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2F9NP3qGDS80IJvNbEWPmi%2Fconfirm%20button.png?alt=media&amp;token=38dbfa9b-e71c-496c-9542-84c92385a62c" alt="Confirmation button in the email"><figcaption><p>The BugBug confirmation email is used only as an example.</p></figcaption></figure>
9. Continue recording: log in with the same `{{testRunId}}@bugbug-inbox.com` address and password.

Links in the email open in the same tab as the inbox. To continue in the tab of your app, add a [Switch context](https://docs.bugbug.io/editing-tests/actions.md#switch-context) step to the tab of your app, or close the inbox tab with **Close tab**. See [Tabs & iframes](https://docs.bugbug.io/editing-tests/tabs-and-iframes.md).

### Use a specific address

To use a name of your choice, choose **Specific test email** in the Inbox menu and type the name. You type only the part before `@bugbug-inbox.com`. This option also opens the inbox for that name.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2F8aiEJBCp2TDmG9uGpoGk%2FmyEmail.png?alt=media&amp;token=b90ea3be-24fc-4d79-b1ce-ec7b1f7a7dd2" alt="Specific test email option"><figcaption></figcaption></figure>

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FtzYOJ7Ny15JkGUDwKSOC%2Falias.png?alt=media&amp;token=d6e11de1-47a9-4278-a1be-a3471fe3924c" alt="Alias input for a specific test email"><figcaption></figcaption></figure>

A fixed name is the same in every run, so old emails from earlier runs can still be in the inbox, and other people using the same name can see your emails. Add a variable to the name, for example `{{testRunId}}` or `{{timestamp}}`, or [clear the inbox](#clear-the-inbox-before-the-test) first.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FYm07pvUf03GdeOJ6uj5i%2FtypeTextId.png?alt=media&amp;token=92881833-04fb-420f-a5e3-dd63d2ba6efd" alt="Email alias built from variables"><figcaption></figcaption></figure>

## The Open inbox step

The [Open inbox](https://docs.bugbug.io/editing-tests/actions.md#open-inbox) step opens `https://bugbug-inbox.com/<name>` in a new tab, and the next steps run in that tab.

* **Value.** Only the mailbox name, for example `{{testRunId}}` or `signup-{{testRunId}}`. Don't enter the full address with `@bugbug-inbox.com`. If you have the full address in a variable, cut out the name with a Set variable step, see [this example](https://docs.bugbug.io/editing-tests/custom-javascript-actions.md#example-a-bugbug-inbox-mailbox-from-a-login-email).
* **Variables** work in the value.
* **Plans.** Open inbox steps are available on all paid plans.
* **Waiting for the email.** Open inbox doesn't wait for emails. The next step, for example a click on the email's subject, waits for the email to appear, up to the step's [timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md). If your app sends emails slowly, increase the timeout of that step.

You can also open an inbox with a **Go to URL** or **New tab** step and the URL `https://bugbug-inbox.com/{{testRunId}}`.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FQLD6M7ixalr454fyE10I%2Ftab.png?alt=media&amp;token=a430c859-947d-4a2b-a3a9-19b1d8841508" alt="Inbox URL combined with a variable"><figcaption></figcaption></figure>

## Work with the email

The email is shown in the inbox page itself, not in an iframe, so you use the same steps as on any page.

### Open the right email

Click the email by its subject, with a [selector](https://docs.bugbug.io/preventing-failed-tests/selectors.md) that matches the subject text, for example:

```
//SPAN[normalize-space(text())="Confirm your e-mail address"]
```

The newest email is at the top. If the selector matches several emails, BugBug clicks the first one, which is the newest.

### Click a verification link

If the email has a button, click it like any button.

If the link is shown as text, its address changes in every email. The recorder saves a selector with the full address, for example:

```
//A[normalize-space(text())="https://acmecorp.com/#/activate?key=60f0ae29-542a-4418-8529-41a01bf22fcc"]
```

Change the selector so that it matches only the beginning of the link:

```
//A[contains(text(), "https://acmecorp.com/#/activate")]
```

### Use a one-time code

To type a code from the email into your app:

1. Open the email.
2. Add a [Set variable](https://docs.bugbug.io/editing-tests/actions.md#set-variable) step on the element that contains only the code, with **Variable name** `code` and **Value** set to **From element**.
3. Switch back to the tab of your app and type `{{code}}` with a **Type text** step.

If the code is part of a longer text, set **Value** to **Custom JavaScript** instead and read the code in JavaScript, for example a 6-digit code:

```javascript
return document.body.innerText.match(/\b\d{6}\b/)[0];
```

### Save a link for later

To open a link from the email in your app's tab instead of the inbox tab, save its address and go there:

1. Add a Set variable step with **Variable name** `activationUrl`, **Value** set to **Custom JavaScript**, and the code:

   ```javascript
   return document.querySelector('a[href*="/activate"]').getAttribute('href');
   ```
2. Switch to the tab of your app and add a **Go to URL** step with `{{activationUrl}}`.

### Check the content of the email

Use [assertions](https://docs.bugbug.io/editing-tests/assertions.md) in the inbox tab, for example **Text** on the subject or on a paragraph of the email.

## Clear the inbox before the test

With a fixed name, emails from earlier runs can stay in the inbox for up to 10 minutes. To start with an empty inbox, open it once with `?clear=true` at the end of the URL:

```
https://bugbug-inbox.com/my-test-inbox?clear=true
```

The inbox deletes all its emails and then shows new ones. Use a **Go to URL** or **New tab** step for this URL. With `{{testRunId}}` in the name you don't need this, because every run has a new, empty inbox.

## Read emails through the API or MCP

The inbox of a test run, `{{testRunId}}@bugbug-inbox.com`, is also available outside the browser. Use it to check emails after a run, or let an AI agent read the verification link.

| Task                         | [Public API](https://docs.bugbug.io/integrations/public-api.md) | [BugBug MCP](https://docs.bugbug.io/ai-testing/mcp.md)                                                          |
| ---------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| List emails                  | `GET /v2/testruns/{id}/inbox/`                                  | `bugbug_get_test_run_inbox` with `runId`                                                                        |
| Read one email with its HTML | `GET /v2/testruns/{id}/inbox/messages/{messageId}/`             | `bugbug_get_test_run_inbox` with `runId` and `messageId`. `fields: ["links"]` returns the links from the email. |
| Clear the inbox              | `DELETE /v2/testruns/{id}/inbox/`                               | `bugbug_delete_test_run_inbox_messages` with `runId`                                                            |
| Delete one email             | `DELETE /v2/testruns/{id}/inbox/messages/{messageId}/`          | `bugbug_delete_test_run_inbox_messages` with `runId` and `messageId`                                            |

The list can be filtered with `search`, `from`, `to`, `subject`, `body`, `unseen`, `hasAttachments`, `receivedAfter`, `receivedBefore`, `ordering` and `limit` (up to 500). The response has the inbox `address`, its `url` and the `messages`. A single message has a text preview of the first 200 characters and the full `html`.

* Only the `{{testRunId}}` inbox of the run is available. Inboxes with other names, for example `signup-{{testRunId}}`, can be read only in the browser.
* The Public API is available on the Business plan. The inbox endpoints have a lower rate limit than the rest of the API.
* If the inbox service is unavailable, they return `503`. Try again later.
* Emails are removed after 10 minutes, so read them soon after the run.

## FAQ

<details>

<summary>Can I use my own email domain or my own mailbox?</summary>

The Testing Inbox works only with `@bugbug-inbox.com` and `@usebugbug.com` addresses. To read emails from your own mailbox, call your mail provider's API in a [Set variable](https://docs.bugbug.io/editing-tests/actions.md#set-variable) step with **Value** set to **Custom JavaScript**, see [Custom JavaScript actions](https://docs.bugbug.io/editing-tests/custom-javascript-actions.md).

</details>

<details>

<summary>Why doesn't the email arrive?</summary>

* Check that the Open inbox value is the same name as in the email address you typed, without `@bugbug-inbox.com`. `signup-{{testRunId}}` and `{{testRunId}}` are different inboxes.
* Your app may reject or not send to the `bugbug-inbox.com` domain, for example because of a list of blocked email domains. Try the alternative domain: `{{testRunId}}@usebugbug.com` goes to the same inbox.
* Your app may send the email later than the step's timeout. Increase the timeout of the step that clicks the email.
* Emails older than 10 minutes are removed.

</details>

<details>

<summary>The test clicks an old email from an earlier run. What do I do?</summary>

Use `{{testRunId}}` in the address, so every run has a new inbox. With a fixed name, [clear the inbox](#clear-the-inbox-before-the-test) at the start of the test.

</details>

<details>

<summary>Is the Testing Inbox private?</summary>

No. Anyone who knows the name can open the inbox. Use names that are hard to guess, such as `{{testRunId}}`, and only test data.

</details>

<details>

<summary>How long are emails kept?</summary>

10 minutes. After that they're removed.

</details>

<details>

<summary>Can I test a one-time code or a magic link?</summary>

Yes. Save the code or the link with a Set variable step and use it in your app's tab. See [Use a one-time code](#use-a-one-time-code) and [Save a link for later](#save-a-link-for-later).

</details>

<details>

<summary>Can I test SMS codes?</summary>

No, the Testing Inbox receives only emails. To get an SMS code, call your SMS provider's API in a Set variable step with **Value** set to **Custom JavaScript**.

</details>

<details>

<summary>Can an AI agent read the verification email?</summary>

Yes, through [BugBug MCP](https://docs.bugbug.io/ai-testing/mcp.md): `bugbug_get_test_run_inbox` lists the emails of a test run, and with `messageId` and `fields: ["links"]` returns the links from the email. It works for the `{{testRunId}}` inbox.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/editing-tests/testing-inbox.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
