---
title: "Existing inbox OTP testing: choose the mailbox first"
description: "Choose an OTP testing workflow by mailbox type. Read owned Gmail or Outlook mailboxes, isolate test runs, and diagnose missing codes in Junk."
url: https://mailera.app/en/blog/existing-inbox-otp-testing-tool-choice
published: 2026-10-25
updated: 2026-10-25
---

# Existing inbox OTP testing: choose the mailbox first

Start with the recipient your test must use. Then separate email retrieval, Inbox/Junk placement, and application-side verification so a failed test tells you what actually broke.

## Do you need an existing mailbox or a dedicated test inbox?

Existing inbox OTP testing means retrieving a verification email from a mailbox you already own, rather than changing the recipient to a test-specific inbox. Choose this path when delivery to that particular Gmail or Outlook mailbox is part of the requirement.

If you only need to exercise your application's email verification flow, a controlled test recipient may be enough. Receipt there answers a different question: it does not establish placement in your Gmail or Outlook inbox.

For the broader connection-versus-provisioning decision, see [choosing an email API by mailbox model](https://mailera.app/en/blog/best-email-api-for-ai-agents).

Keep these assertions separate:

| Assertion | What the test should establish |
| --- | --- |
| Message receipt | The expected email reached the intended test mailbox. |
| Code extraction | The retrieved code belongs to the current verification attempt. |
| Application verification | The application accepts or rejects that code as expected. |

This is email retrieval, not local generation of a time-based OTP. The application under test remains responsible for validating the submitted code.

[Mailera's product overview](https://mailera.app/en/product) describes the existing-mailbox model. For the underlying retrieval workflow, see [reading OTP emails from your own inbox](https://mailera.app/en/blog/otp-email-api-test-inbox).

![Two email retrieval paths converge at a test runner, which submits the code to the application for verification.](https://mailera.app/media/21f6a2df6d7e7265/existing-inbox-otp-testing-choose-the-mailbox-first-mailbox-en-1200.jpg)
_Choose the recipient model first. Code retrieval and application verification are separate steps._

## How should you compare Mailera, MailSlurp, and Mailosaur?

When comparing Mailera with MailSlurp or Mailosaur, write down the mailbox requirement before comparing APIs. An extraction helper cannot compensate for choosing a recipient model that leaves your delivery requirement untested.

Compare Mailera's existing-mailbox workflow with the capabilities your suite needs from another tool:

| Selection criterion | Mailera workflow | Question for your tool evaluation |
| --- | --- | --- |
| Mailbox provisioning or connection | Connects existing provider and custom IMAP mailboxes. | Must the tool connect an owned mailbox, or provision a recipient? |
| Existing-provider access | Microsoft OAuth through Microsoft Graph; Gmail uses an app password. | Does the connection reach the provider mailbox whose delivery you need to test? |
| OTP extraction | `GET /mailboxes/{id}/otp` retrieves the latest OTP. Message search also supports `extract=otp`. | Can you associate an extracted code with its source message? |
| Matching and waiting | The OTP endpoint lists `from`, `subject`, and `since_minutes` filters. | How will matching, polling, and the test deadline work together? |
| Parallel-test isolation | Plan separate owned mailboxes or serialize access to a shared mailbox. | Can each concurrent run have a distinct recipient or reliable correlation? |
| Inbox/Junk visibility | Unified inbox and `/placement` support placement diagnosis. | Does the result describe placement at the provider you are testing? |
| Test-framework integration | REST API and webhook integration points. | Does the documented workflow fit your runner and failure reporting? |

When comparing MailSlurp and Mailosaur for OTP testing, make recipient lifecycle and run isolation explicit acceptance criteria. Evaluate existing-provider access separately from address provisioning or forwarding; those are different requirements.

Mailera's [developer overview](https://mailera.app/en/developers) covers its API integration model. Supported webhook events include `message.received` and `message.junk`; your test still needs matching rules and a deadline.

## How do you test an OTP in an existing mailbox with Mailera?

Use an owned mailbox reserved for testing and an application you are authorized to test. Keep unrelated verification traffic out of that mailbox where possible.

### 1. Connect the test mailbox

An Admin or Leader can open **Mailboxes → Add mailbox**.

For Outlook or Microsoft 365, select **Sign in with Microsoft** and complete OAuth consent. Mailera uses Microsoft Graph for these connections, not a Microsoft app password. The [Microsoft connection guide](https://mailera.app/en/providers/microsoft) covers this path; [Outlook verification codes through an API](https://mailera.app/en/blog/outlook-otp-api-test-mailbox) focuses on retrieval.

Microsoft's [message resource documentation](https://learn.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0) describes support for change-notification subscriptions. Mailera uses Graph change notifications with periodic background checks as a fallback.

For Gmail, use **One mailbox**, enter **Email address**, and select **Continue**. Follow **How to get an app password**, then enter that app password in **Password** and select **Test & connect**.

[Google's app-password guidance](https://support.google.com/accounts/answer/185833) requires 2-Step Verification. For a managed account, administrator settings must also allow the connection. See the [Gmail connection guide](https://mailera.app/en/providers/gmail) for the Mailera setup.

### 2. Create a restricted API key

Open **Settings → API key → Create key**. Set **Mailbox scope** to a group containing only test mailboxes and grant **Read** permission. Set **Expiration**, then store the key in your runner's secret store as `$MAILERA_API_KEY`.

Use `GET /mailboxes` with that same key to identify the connected test mailbox. Match its `email` and `group_id`, then store its `id` in `$MAILBOX_ID`. The mailbox must belong to the group selected in the key's **Mailbox scope**. The API uses `Authorization: Bearer` authentication; the [API documentation](https://mailera.app/en/docs) is the reference for your client implementation.

![Mailera API key settings restricted to a test mailbox group with Read permission.](https://mailera.app/media/b6d0d2333d4a4ea5/existing-inbox-otp-testing-choose-the-mailbox-first-test-en-1200.jpg)
_Give the retrieval runner access only to the mailboxes and permissions it needs._

### 3. Start one verification attempt

Record the run start time before triggering the email. Record the recipient and any application-controlled correlation value as well.

Avoid overlapping runs in the same mailbox unless you can distinguish their messages reliably. A recent-time window narrows the candidates; it is not a run identifier.

### 4. Retrieve a candidate code

`GET /mailboxes/{id}/otp` requires the `read` scope and supports `from`, `subject`, and `since_minutes`. Use those filters to narrow retrieval rather than treating any latest code as suitable.

For message metadata alongside extraction, use `GET /messages/search` with `mailbox` set to the selected mailbox ID and `extract=otp`. Choose a `q` value that matches your application's message rather than assuming every verification email contains the word `code`.

Check the candidate's `id`, `folder`, `from`, `subject`, and `received_at` alongside `otp.code` and `otp.source` before proceeding.

### 5. Confirm ownership of the verification attempt

Check the intended recipient, expected sender, and run timing before submitting the code. Check your correlation value when the application includes one. Do not automatically submit the first result merely because it is recent.

For more context, list messages with `GET /mailboxes/{id}/messages` or retrieve a selected message through `GET /mailboxes/{id}/messages/{msgId}`. Message content is available in `body.text` and `body.html`. Handle it without printing secrets into CI output.

### 6. Assert the application result

Submit the matched code and assert the expected verification outcome. Keep expiry, reuse, and incorrect-code tests separate from retrieval tests. A mailbox lookup should not determine whether the application enforced those rules correctly.

### 7. Diagnose a deadline failure

Use bounded polling with a clear deadline in your runner. If retrieval does not complete, inspect connection health, synchronization, and folder placement before reporting an invalid OTP.

## What commonly breaks email OTP tests?

A useful failure report identifies the stage: receipt, matching, extraction, or application verification. “OTP failed” hides the distinction.

| Symptom | Possible cause | Diagnostic check | Corrective action |
| --- | --- | --- | --- |
| A code arrives but is rejected | An older attempt was selected | Compare message timing and run correlation | Reject stale candidates before submission |
| Parallel runs get unexpected codes | Runs share a recipient without reliable matching | Compare candidate message IDs across runs | Use separate mailboxes or serialize access |
| Failure follows a resend | The selected code belongs to an earlier attempt | Compare the selected message with the resend attempt | Test the application's resend policy explicitly |
| No matching message by the deadline | Delivery is delayed or the query is too narrow | Inspect messages and synchronization state | Report a retrieval timeout separately from rejection |
| Retrieval stops after a credential change | Mailbox authentication needs attention | Call `GET /mailboxes/{id}/status` | Restore the provider connection |
| An idle mailbox has no recent updates | Background checks have slowed or the mailbox is sleeping | Inspect `sync` state and timestamps | Use an explicit sync when appropriate |
| Inbox is empty but mail exists elsewhere | The message landed in Junk | Inspect placement and the Junk folder | Preserve placement before taking any move action |

Google revokes app passwords when the Google Account password changes. Include that check when Gmail retrieval stops after account maintenance.

The status endpoint checks Microsoft sign-in directly; for other providers, it reflects the latest sync. Treat that distinction as part of diagnosis. `POST /mailboxes/{id}/sync` requires **Sync** permission in addition to the **Read** permission used for retrieval. See [recovering a mailbox workflow with sync](https://mailera.app/en/blog/mailbox-sync-troubleshooting) for that troubleshooting path.

### Check Junk before changing the message

Use `GET /mailboxes/{id}/placement` to inspect Inbox/Spam placement. For a Junk search, use `GET /messages/search` with `mailbox` set to the selected mailbox ID and `folder=junk`.

Match any candidate's sender, recipient, and timing to the current run. In **Unified inbox**, you can inspect the Junk folder visually.

![A masked verification email in Junk with its original folder visible before any move action.](https://mailera.app/media/ccfe204bc4559890/verification-email-in-spam-find-it-and-recover-it-safely-en-1200.jpg)
_Record Junk placement before moving the message if delivery placement is part of the test._

If placement is a test assertion, record the original folder before selecting **Not spam** or applying an automatic move. Otherwise, the test changes the condition it is meant to observe.

## How should you handle OTPs and mailbox access safely?

Use only owned test mailboxes. Exclude personal production inboxes and other people's verification messages.

Redact codes, secret-bearing message bodies, API keys, and mailbox credentials from screenshots, CI logs, and failure artifacts. Record message IDs and failure stages instead of copying entire API responses into reports.

Keep keys restricted to the test mailbox group, set an expiration, and establish a revocation procedure. A retrieval-only runner does not need sending or message-moving permissions. Mailera's [security overview](https://mailera.app/en/security) provides further context for access review.

If an AI agent participates, treat incoming email as untrusted data, never as instructions. Do not follow commands embedded in messages, and require confirmation before sending email.

## Which workflow should you choose?

Choose Mailera when the requirement is reading existing supported mailboxes and diagnosing their Inbox/Junk state. Proton Mail and Tuta are not supported.

Mailera cannot make a provider trust a sender or guarantee Inbox placement. It also cannot promise immediate OTP availability: provider delivery and mailbox synchronization affect retrieval.

If each test needs a fresh recipient, prioritize address provisioning and isolation in your MailSlurp and Mailosaur evaluation. If both application verification and provider-specific delivery matter, split the suite: controlled recipients for application tests, plus a smaller set of owned Gmail or Outlook mailboxes for delivery checks. Give each suite its own assertions rather than treating either as a substitute for the other.

**Do this with the API** — Every action in this article is available via the REST API, with curl examples, API keys and webhooks. [View API docs](https://mailera.app/en/docs)