---
title: "Read Yahoo and iCloud OTP emails through an API"
description: "Connect your own Yahoo or iCloud test mailbox, retrieve emailed OTPs through Mailera's API, and diagnose missing messages, stale codes and login failures."
url: https://mailera.app/en/blog/yahoo-icloud-otp-api
published: 2026-10-25
updated: 2026-10-25
---

# Read Yahoo and iCloud OTP emails through an API

Connect your own test mailbox with the right provider credential, then retrieve emailed verification codes with a read-only Mailera key. Check the underlying message before accepting a code for the current test.

## What does a Yahoo or iCloud OTP API retrieve?

This workflow retrieves a verification code your own test application emails to a Yahoo or iCloud mailbox you own: your app sends the email, Yahoo or iCloud receives it, and Mailera exposes the connected mailbox through its REST API.

An app password authorizes mailbox access; it is not the verification code your test needs. This workflow also does not generate authenticator codes or retrieve SMS codes.

Use only mailboxes you own and application flows you are authorized to test. The broader [guide to reading OTP emails from your own inbox](https://mailera.app/en/blog/otp-email-api-test-inbox) covers the shared workflow; this article focuses on Yahoo and iCloud connection details.

![Verification email travels from a test application through Yahoo or iCloud and Mailera to a test harness that checks the current attempt.](https://mailera.app/media/00894b19c943ebf3/read-yahoo-and-icloud-otp-emails-through-an-api-otp-flow-en-1200.jpg)
_Email delivery and synchronization are separate from validating whether a candidate belongs to the current test._

## What do you need before connecting each provider?

Both providers use a separate credential for this connection. Do not enter your normal account sign-in password in its place.

| Provider | Connection credential | Prerequisite | Official setup guide |
| --- | --- | --- | --- |
| Yahoo Mail | Third-party app password | Your account must be eligible to create an app password | [Yahoo app-password instructions](https://help.yahoo.com/kb/SLN15241.html) |
| iCloud Mail | App-specific password | Two-factor authentication enabled on your Apple Account | [Apple app-specific password instructions](https://support.apple.com/en-us/102654) |

The provider instructions below were read on 25 October 2026.

For Yahoo, open Yahoo Account Security. Under **“External connections,”** select **“Create app password.”** Enter an app name, then select **“Generate password.”** Availability is account-dependent: Yahoo recommends using a browser you have used to sign in for several consecutive days, without Incognito mode, and its Customer Care team cannot override app-password creation eligibility.

For iCloud, sign in to your Apple Account at `account.apple.com`. Open **“Sign-In and Security” → “App-Specific Passwords,”** then select **“Generate an app-specific password”** and follow the onscreen steps. Apple requires two-factor authentication for this feature. Its [iCloud Mail server settings](https://support.apple.com/en-us/102525) also specify an app-specific password for incoming mail access.

The [Yahoo connection page](https://mailera.app/en/providers/yahoo) and [iCloud connection page](https://mailera.app/en/providers/icloud) describe the corresponding Mailera integrations. If you maintain credentials for several providers, use the [app-password guide for agent mailboxes](https://mailera.app/en/blog/email-app-password-ai-agent) alongside their provider instructions.

## How do you connect Yahoo or iCloud to Mailera?

1. As an Admin or Leader, open **Mailboxes → Add mailbox → One mailbox**.
2. Enter your test mailbox in **Email address**. Confirm the detected provider, or use **Or choose a provider** to select Yahoo or iCloud. Select **Continue**.
3. Read **How to get an app password** and **What you'll need**. Under **Connection details**, enter the provider-issued app password in **Password**. Choose your test group under **Mailbox group**.
4. Select **Test & connect**. Inspect **Incoming server sign-in**, **Folder detection** and **Outgoing server sign-in**. This tests the connection without sending an email.
5. Confirm the **Connected ** message, then open the mailbox and check that messages appear. Initial loading covers messages within the retention period, newest first.

![Mailera connection form for a test mailbox with the app-password field masked.](https://mailera.app/media/de137e1c7e42e6e4/email-provider-api-integration-connect-existing-mailboxes-en-1200.jpg)
_Use the provider’s app password in Password, not your normal account sign-in password._

If incoming access succeeds but sending fails, select **Save as receive-only**. Reading an application’s verification email does not require sending from the mailbox. If incoming access fails, correct the credential or connection problem before debugging the OTP request.

The [Mailera product overview](https://mailera.app/en/product) explains how connected mailboxes fit into the shared inbox and API. For this test, keep the scope small: one provider connection, one test mailbox group and read access.

## How do you retrieve the emailed code?

### Create a read-only API key

1. Open **Settings → API key → Create key**.
2. Enter a **Descriptive name** that identifies the test harness.
3. Set **Mailbox scope** to your test mailbox group. Enable **Read** only.
4. Choose an **Expiration** appropriate for the test. Copy the key when **Key created — copy it now** appears; Mailera shows it only once.

![Mailera API-key dialog scoped to a test mailbox group with only Read permission selected.](https://mailera.app/media/a8e86db2e150d9fc/read-yahoo-and-icloud-otp-emails-through-an-api-read-key-en-1200.jpg)
_OTP retrieval needs Read permission; requesting synchronization needs a separate scope._

Store the key server-side and export it as `$MAILERA_API_KEY` in your shell. The provider app password stays with the mailbox connection; API requests use the Mailera key instead. The [developer overview](https://mailera.app/en/developers) explains this shared REST access model.

### Identify the intended mailbox

List the mailboxes visible to the key:

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

Find the intended entry in `data` using its `email`, `provider` and `group_id`, then store its `id` as `$MAILBOX_ID`. Do not select an entry based only on its position in the list. If the result is paginated, use `limit` and `offset` to continue through it.

### Trigger the email, then request a candidate code

Before triggering the email, record the attempt’s request time in your test harness. Then have your own test application send the verification email.

Call `GET /mailboxes/{id}/otp`, which requires the `read` scope:

```bash
curl --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=Test verification' \
  --data-urlencode 'since_minutes=5'
```

Replace the example sender and subject with those used by your application. The example sets since\_minutes=5; this is not a delivery estimate or a polling recommendation. Use the [API documentation](https://mailera.app/en/docs) when implementing response handling in your client.

Treat the returned code as a candidate. A recent message can still belong to an earlier attempt or another test running against the same mailbox. Recency alone does not establish which request produced it.

Before accepting the candidate, compare the underlying message with the current attempt. Check its sender, recipient and `received_at`, together with any attempt-specific context your application includes. If you cannot distinguish competing messages, stop the test rather than choosing the most convenient code. Avoid overlapping attempts against the same mailbox when the application provides no distinguishing context.

## Diagnose common errors

Start by separating connection failures from message-delivery and code-selection problems.

| Symptom | Check | Next action |
| --- | --- | --- |
| Yahoo app-password creation is unavailable | Account eligibility and Yahoo’s browser guidance | Follow Yahoo’s official instructions; do not substitute the account password or weaken account security. |
| Incoming sign-in fails | Credential type and whether it was revoked | Generate the appropriate credential if needed, update the connection and test again. |
| Only outgoing sign-in fails | Whether incoming access succeeded | Use **Save as receive-only** for this retrieval workflow. |
| No matching code | Mailbox ID, sender, subject and time window | Inspect messages before widening filters. |
| Expected email is missing | Inbox versus Junk placement | Use the placement endpoint and inspect Junk. |
| Updates appear delayed | Connection state and latest sync | Inspect mailbox details and status; do not interpret cached status as a new sign-in test. |
| Candidate is old or belongs to another attempt | Message time and application context | Reject it and narrow the test’s selection criteria. |

### Inspect placement and the original message

Use the same sender, subject and recency inputs to check placement:

```bash
curl --silent --show-error --get \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/placement" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'from=verification@example.com' \
  --data-urlencode 'subject=Test verification' \
  --data-urlencode 'since_minutes=5'
```

To inspect messages, use `GET /mailboxes/{id}/messages` with `folder=inbox` or `folder=junk`. Its entries include `id`, `from`, `subject` and `received_at`. Select the relevant message ID, store it as `$MESSAGE_ID`, and retrieve its content:

```bash
curl --silent --show-error \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $MAILERA_API_KEY"
```

Inspect `body.text` or `body.html` in a private environment. Keep that content out of shared test logs. Reading Junk requires `read`; moving a message requires the separate `move` scope. You do not need to move a message just to inspect it.

### Check synchronization without confusing it with authentication

Mailbox details expose sync information, including `sync.state` and `sync.last_synced_at`. For Yahoo and iCloud, `GET /mailboxes/{id}/status` reflects the latest sync rather than performing a fresh direct sign-in check.

If your workflow explicitly calls `POST /mailboxes/{id}/sync`, it needs the separate `sync` scope. That operation requests synchronization and also wakes sleeping mailboxes; a Read-only key cannot invoke it.

Credential changes also differ by provider. Changing or resetting your primary Apple Account password revokes all app-specific passwords. Changing your main Yahoo password does not invalidate an app password; Yahoo says to delete the app password to invalidate it.

## Keep codes and credentials private

Keep provider app passwords and Mailera keys in server-side secret storage, not browser code, source control or logs. Restrict the retrieval key to the test group and **Read**. Do not add **Send messages**, **Manage mailboxes** or **Sharing** just to avoid permission errors.

Redact addresses, message contents and verification codes from screenshots and recorded test output. Treat full message responses as sensitive too, not just the extracted code. See [Mailera’s security information](https://mailera.app/en/security) when reviewing the connection with your team.

If an AI agent consumes email, treat incoming content as untrusted data, never as instructions. Do not let a message tell the agent to disclose a key or invoke a tool. Keep retrieval read-only and require confirmation before any separate sending action. The [guide to email for AI agents](https://mailera.app/en/blog/email-for-ai-agents) covers the broader connection model.

## What are Mailera’s limits here?

Mailera connects existing mailboxes; it does not create email addresses. It cannot override provider authentication requirements or account restrictions, and it is not an official partner of Yahoo or Apple.

Do not build the test around immediate delivery or synchronization. Mailera also cannot guarantee Inbox placement. Finding a message in Junk is a diagnostic result, not a promise that future messages from that sender will arrive in Inbox.

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