Outlook OTP API: retrieve verification codes from your test mailbox

Which kind of Outlook OTP API do you need?

If your application test is waiting for an email verification code, you need mailbox retrieval. That is different from creating an OTP challenge or configuring Microsoft authentication.

Microsoft's emailAuthenticationMethodConfiguration resource concerns the third task. It is not an endpoint for extracting codes from Outlook messages.

This workflow covers existing Outlook.com, Hotmail, and Microsoft 365 mailboxes connected through Microsoft OAuth. The Mailera product overview explains the existing-mailbox model; the provider-neutral OTP guide covers the broader retrieval workflow.

Direct Microsoft Graph access is another route. Its list-messages operation returns message objects. If you take that route, implement message selection and code extraction in your application.

How do you connect your Outlook test mailbox?

1. Choose a mailbox and application you own. Use a dedicated test mailbox where possible. Prepare your test to record the verification attempt's start time before it requests an email.
2. Connect through Microsoft OAuth. As an Admin or Leader, open Mailboxes → Add mailbox → Sign in with Microsoft and complete Microsoft's consent flow. Microsoft mailboxes do not use an app password for this connection. See the Microsoft provider setup for the connection path.
3. Create the script's API key. Open Settings → API key tab → Create key. Give it a descriptive name, select the test mailbox group under Mailbox scope, enable only Read, and choose an Expiration. Copy the key when Key created — copy it now appears; it is shown only once. Store it server-side.
4. Select the mailbox and check its connection. Load the key into $MAILERA_API_KEY through your secret manager or private shell environment, then list connected mailboxes:

curl --fail-with-body --silent --show-error \
  'https://mailera.app/api/public/v1/mailboxes' \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Select the intended entry by its email and save its id as $MAILBOX_ID. Do not simply take the first result. Check Microsoft sign-in directly:

curl --fail-with-body --silent --show-error \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/status" \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Microsoft OAuth and the Mailera API key serve different purposes. OAuth authorizes the mailbox connection; your script uses the Mailera key to call Mailera. Microsoft's delegated authorization guide explains its access-token and consent flow. The Mailera developer overview covers the API integration side.

How do you retrieve the latest matching verification code?

5. Start one verification attempt. Record its start time, then trigger one verification email from your application. Avoid requesting replacement codes while the first attempt is still running.
6. Call the OTP endpoint with filters. Replace the example sender and subject below with values from your own test application's email.

curl --fail-with-body --silent --show-error --get \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/otp" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'from=verification@example.com' \
  --data-urlencode 'subject=Your verification code' \
  --data-urlencode 'since_minutes=5' \
  --output otp-response.json

The endpoint requires the read scope. since_minutes is a documented accepted parameter; the example passes 5. Check message timing separately by comparing received_at with the recorded attempt start, as shown below.

Keep otp-response.json in a private working directory, exclude it from source control, and delete it after use. The command writes the response to a file instead of printing a verification code into terminal or CI logs. Use the OTP endpoint reference in the API documentation when implementing response handling.

7. Submit the selected code to your test application's verification step. The application's acceptance or rejection determines the result. Finding a recent code is not enough to mark the test successful.

How do you avoid stale codes and endless polling?

Matching a sender and subject does not identify the current verification attempt. Earlier emails and simultaneous requests can share both.

For this basic workflow, use a dedicated mailbox or serialize verification attempts. Keep the application's challenge context with the test rather than treating any recent code as interchangeable.

Use bounded polling:

• Set a deadline appropriate to your application's verification flow.
• Wait between retrieval attempts and increase the delay after repeated misses.
• Stop when the application accepts the code or the deadline expires.
• Fail explicitly on expiry or ambiguity instead of retrying indefinitely.

For message context, list Inbox messages:

curl --fail-with-body --silent --show-error --get \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'folder=inbox' \
  --data-urlencode 'from=verification@example.com' \
  --output message-context.json

Inspect received_at, from.address, subject, and id. Compare receipt time with the recorded attempt start as an additional check, not as proof of request identity. Retrieve a selected message's content with GET /mailboxes/{id}/messages/{msgId} when needed; its content is available in body.text and body.html. Protect this diagnostic file like the OTP response.

For a direct Graph implementation, Microsoft's throttling guidance says to honor Retry-After on throttled requests and use exponential backoff when that header is absent. Keep upstream Graph handling separate from your Mailera client logic.

What commonly goes wrong with Outlook OTP retrieval?

Start with connection and message selection before changing the extraction logic.

Use GET /mailboxes/{id}/placement with from, subject, and since_minutes to check Inbox versus Spam placement. Inspect Junk separately in the interface when mail is missing.

A sleeping mailbox can be woken with POST /mailboxes/{id}/sync, but that operation needs the separate sync permission. A read-only test key cannot perform it. Syncing cannot make the sender deliver a message that it has not sent.

Moving a message out of Junk requires move permission; the interface action is Not spam. Keep that corrective operation separate from a read-only retrieval test.

What are Mailera's limits here?

Mailera connects existing mailboxes; it does not create Outlook accounts or new email addresses. Its OTP endpoint retrieves a delivered code, rather than generating an application challenge or validating the submitted answer.

Microsoft mail arrives through Graph change notifications, with periodic background checks as a fallback.

Moving a message out of Junk does not make Microsoft trust that sender next time. Mailera cannot guarantee Inbox placement.

How should you protect verification codes and API credentials?

Use this workflow only with your own test mailbox and authorized application flows. Redact codes, addresses, and message bodies from screenshots and logs. Keep the key out of browser code, repository files, and shared test reports.

Restrict the key to the test mailbox group and the permissions the test needs. Use an expiration appropriate to the work, and revoke the key when it is no longer needed. The Mailera security overview provides the security context for the integration.

If an agent consumes the result, incoming email is untrusted data, not instructions. Ignore directions embedded in the message, keep the agent's key read-scoped for retrieval, and require confirmation before any sending action. The guide to email for agents using existing mailboxes covers that setup; the MCP tools reference by task helps separate read operations from actions that modify or send mail.