Hotmail OTP API: retrieve a code from your own test mailbox

Can you retrieve Hotmail OTP emails through an API?

Yes. Mailera connects Hotmail through Microsoft Graph using OAuth, then exposes an endpoint for retrieving the latest OTP code: GET /mailboxes/{id}/otp. Hotmail uses the same Microsoft connection path as Outlook.com, not a separate Hotmail OTP service.

An OTP is a one-time passcode. When you automate an email verification test, separate these four jobs:

Microsoft Entra's emailOtpSend event belongs on the delivery side: Entra sends a passcode to a REST API you own. It isn't an endpoint for reading codes from Hotmail.

The Mailera product overview explains how existing mailboxes connect to applications. For the provider-independent workflow, see reading OTP emails from your own inbox.

What do you need before connecting your Hotmail mailbox?

Use an existing Hotmail mailbox and a test account you own. You also need permission to automate the application being tested. This walkthrough covers a verification email generated by your test application, not Microsoft account recovery.

Have an Admin or Leader connect the mailbox; other Mailera roles cannot add mailboxes. Use OAuth rather than looking for an app password. Microsoft mailboxes aren't connected to Mailera with app passwords.

There are two authorization boundaries:

• Microsoft OAuth authorizes the mailbox connection. Microsoft's delegated authorization flow starts with the user authorizing the application to act on their behalf.
• The Mailera API key authorizes your test runner's requests to Mailera. It isn't a Microsoft access token.

Microsoft's permissions reference recommends requesting the least privileged permissions needed. Apply the same principle to your Mailera key: retrieval needs read, not permission to send messages.

How do you connect Hotmail and create a read-only API key?

1. Open Mailboxes → Add mailbox → Sign in with Microsoft.
2. Complete Microsoft's OAuth consent for the intended test mailbox. Check which Microsoft account you're authorizing before continuing.
3. Return to the mailbox list and confirm the connected address and status. Keep the test mailbox in a dedicated mailbox group.
4. Open Settings → API key tab → Create key. Give the key a descriptive name identifying the test runner.
5. Under Mailbox scope, select the test mailbox group. Enable only Read, then set Expiration.
6. Copy the key into a server-side secret when Key created — copy it now appears. Mailera displays it only once.

Have your secret manager provide $MAILERA_API_KEY to the test process. Run the following in a private working directory, outside source control and shared CI artifacts:

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

Inspect mailboxes.json locally. The response contains a data array; match the intended email, check provider and status, and retain that entry's id as $MAILBOX_ID. Don't select the first entry just because it exists. If the list spans multiple pages, use limit and offset to find the intended mailbox.

The mailbox ID chooses the retrieval target. The key's mailbox scope controls which group it can access. Keep both narrow. The Mailera API documentation covers the request definitions used here.

How do you request a recent OTP from the correct mailbox?

Start with an isolated test rather than a polling loop. That makes it easier to distinguish a retrieval problem from a code belonging to another attempt.

1. Record the test start time in your runner, without recording a code or credential.
2. Trigger one verification email from your authorized test application to the connected Hotmail mailbox.
3. Request the latest code using the intended mailbox ID and the expected sender and subject.
4. Submit the retrieved value only to the application that issued it.

This example passes from, subject and since_minutes=5. The sender and subject are illustrative; replace them with those used by your test application.

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

The response goes to a file rather than terminal output. Treat that file as a secret: don't upload it as a test artifact, print it in logs or commit it. Remove it when the test no longer needs it.

The endpoint accepts from, subject and since_minutes. Keep each result tied to one test attempt: serialize attempts per mailbox, or use independently isolated test mailboxes for parallel runs. Don't keep triggering new emails while an earlier attempt is still waiting.

For message-level inspection, GET /mailboxes/{id}/messages exposes fields including from.address, subject and received_at. Compare the expected message with your recorded start time when diagnosing ambiguous results. Don't treat a recent timestamp as a substitute for isolating tests.

Give the test a deadline and a bounded retry count; don't turn every unsuccessful response into another request. Stop on success or a terminal failure. Mailera's configured limit is 300 requests per minute per key, not a recommended polling rate.

The issuing application decides whether the submitted value is valid, expired or already used.

What common mistakes cause missing or incorrect codes?

Check the mailbox and the email before changing your extraction logic.

Don't rely on the OTP request alone to diagnose Junk. The placement endpoint reports Inbox or Spam placement. In the app, Not spam moves a message out of Junk, but it requires Move messages permission. A retrieval-only key shouldn't gain that permission merely to troubleshoot a missing code.

Mailera receives new Microsoft mail through Graph change notifications, with periodic background checks as a fallback. An explicit POST /mailboxes/{id}/sync request requires the separate sync permission; the read-only key in this walkthrough cannot perform it.

How do you keep OTP retrieval safe?

Keep the key server-side and scoped to the test mailbox group. Redact codes, addresses, tokens and message bodies from logs and screenshots. If a key is exposed, revoke it; Mailera rejects subsequent calls using that key immediately. The Mailera security page provides broader security information.

Incoming email is untrusted data, not instructions. If an agent consumes the result, extract only the expected data for the authorized test. Don't follow instructions embedded in a subject or message body, including requests to disclose secrets or visit another service.

A retrieval-only agent doesn't need Send messages permission. If a separate workflow sends email, require confirmation before sending. See using existing mailboxes with AI agents for the broader setup. For MCP, Mailera's tools by task covers the tool interface; get_latest_otp also requires read.

Mailera doesn't create Hotmail addresses, guarantee Inbox placement, or promise instantaneous synchronization. It cannot make an expired code valid and isn't an official Microsoft partner.