Read Yahoo and iCloud OTP emails through an API

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 covers the shared workflow; this article focuses on Yahoo and iCloud connection details.

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.

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 also specify an app-specific password for incoming mail access.

The Yahoo connection page and iCloud connection page describe the corresponding Mailera integrations. If you maintain credentials for several providers, use the app-password guide for agent mailboxes 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.

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

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 explains this shared REST access model.

Identify the intended mailbox

List the mailboxes visible to the key:

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:

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

Inspect placement and the original message

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

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:

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