---
title: "Hotmail OTP API: retrieve a code from your own test mailbox"
description: "Retrieve verification codes from your own Hotmail test mailbox using Microsoft OAuth and Mailera's read-scoped API, with freshness and safety checks."
url: https://mailera.app/en/blog/hotmail-otp-api
published: 2026-10-25
updated: 2026-10-25
---

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

Connect your existing Hotmail mailbox with Microsoft OAuth, then retrieve a recent verification code through a read-scoped API request. Keep mailbox access separate from the application that issues and validates the code.

## 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](https://mailera.app/en/providers/microsoft), not a separate Hotmail OTP service.

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

| Job | Responsibility | Where Mailera fits |
| --- | --- | --- |
| Generation | The application or identity provider issues the code. | Not the retrieval endpoint's job. |
| Delivery | The sending system delivers the verification email. | Mailera reads the connected receiving mailbox. |
| Retrieval | Your test finds the expected email and extracts its code. | The OTP endpoint handles code retrieval. |
| Verification | The issuing application accepts or rejects the submitted code. | Outside Mailera. |

Microsoft Entra's [`emailOtpSend` event](https://learn.microsoft.com/en-us/entra/identity-platform/custom-extension-email-otp-send-data) 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](https://mailera.app/en/product) explains how existing mailboxes connect to applications. For the provider-independent workflow, see [reading OTP emails from your own inbox](https://mailera.app/en/blog/otp-email-api-test-inbox).

![An owned test application sends email to Hotmail, Mailera retrieves the code, and the test submits it to the issuing application.](https://mailera.app/media/3e79a2965f6f8633/hotmail-otp-api-retrieve-a-code-from-your-own-test-mailbox-en-1200.jpg)
_Mailbox authorization, code retrieval and application-side verification are separate steps._

## 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](https://learn.microsoft.com/en-us/graph/auth-v2-user) 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](https://learn.microsoft.com/en-us/graph/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.

![Mailera Add mailbox screen with Sign in with Microsoft selected for a Hotmail connection.](https://mailera.app/media/d8e9591c875d36fe/email-app-passwords-connect-your-mailbox-to-an-ai-agent-add-en-1200.jpg)
_Use Sign in with Microsoft for the Hotmail mailbox connection._

![Mailera API key dialog restricted to a test mailbox group with only Read permission enabled.](https://mailera.app/media/047ef7ca00571d35/email-human-in-the-loop-an-approval-workflow-for-ai-agents-en-1200.jpg)
_Scope the key to the test group and enable only Read for retrieval._

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:

```bash
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](https://mailera.app/en/docs) 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.

```bash
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.

| Symptom | Check | Next action |
| --- | --- | --- |
| Code from the wrong account | The connected address and selected `id`. | Match the intended `email` in the mailbox list response; don't use an arbitrary first result. |
| No matching code | The `from`, `subject` and `since_minutes` values, and whether the application sent an email. | Inspect the expected message, then review the request parameters. |
| Mailbox appears disconnected | `GET /mailboxes/{id}/status`, which directly checks Microsoft sign-in. | Have the mailbox owner use **Reconnect** in the mailbox list. |
| Expected email is missing | Junk and `GET /mailboxes/{id}/placement`. | Diagnose Inbox or Spam placement separately from code extraction. |
| Old or mixed-up code | Overlapping attempts against the same mailbox. | Stop the overlap and begin a fresh, isolated test. |
| New email hasn't appeared yet | Delivery and mailbox synchronization. | Wait within the test deadline rather than generating repeated verification emails. |

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](https://mailera.app/en/security) 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](https://mailera.app/en/blog/email-for-ai-agents) for the broader setup. For MCP, [Mailera's tools by task](https://mailera.app/en/blog/mailera-mcp-tools) 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.

**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)