Which API do you need to retrieve a Gmail verification code?
A Gmail OTP API request, in this guide, means retrieving a verification code delivered by email to your Gmail test inbox. Use this workflow only with an inbox and application you own or are explicitly authorized to test.
There are two routes to mailbox access:
| Route | Connection and authorization | Retrieval approach |
|---|---|---|
| Google’s Gmail API | Google authorization with Gmail API scopes | List messages, retrieve their content, then handle extraction in your application. |
| Mailera REST API | Connect Gmail using an app password; authenticate API requests with a Mailera key | Call GET /mailboxes/{id}/otp with filters. |
The Gmail API overview describes Google’s REST mailbox API. Its authorization scopes determine the access granted to your application. These are separate from Mailera’s key permissions.
With the direct Google route, users.messages.list returns message resources containing id and threadId; use users.messages.get to retrieve message details.
Mailera requests instead use https://mailera.app/api/public/v1. The Mailera product overview explains its role: connecting existing mailboxes to applications rather than issuing new addresses.
Retrieving an email is not sending an OTP, validating it, or generating an authenticator code. Your test application sends the email and later decides whether the submitted code is valid. For the broader workflow, see reading OTP emails from your own inbox.
How do you connect your Gmail test inbox to Mailera?
Mailera’s Gmail and Google Workspace connection uses an app password, not Gmail OAuth. Google recommends “Sign in with Google” when an app offers it; that is not the Gmail connection flow described here.
Follow Google’s app-password instructions. App passwords require 2-Step Verification. The option may be unavailable for accounts using only security keys for 2-Step Verification, organization accounts, or accounts enrolled in Advanced Protection.
For a managed Workspace account, check with your administrator rather than changing security settings to force the connection. Google also directs organization users who cannot enable 2-Step Verification to contact their administrator.
- As a Mailera Admin or Leader, open Mailboxes → Add mailbox and select One mailbox.
- Enter your test address in Email address. Confirm Gmail detection, or select Gmail under Or choose a provider, then select Continue.
- Under Connection details, enter the app password in Password. Do not enter your normal Google sign-in password. Choose a dedicated test Mailbox group.
- Select Test & connect. This tests the connection without sending email. Check Incoming server sign-in and the remaining connection results.
- If receiving works but sending fails, use Save as receive-only when offered. After connection, wait for initial message loading; Mailera loads messages within its retention period, newest first.
Keep the app password separate from the API key you create next. The app password connects Gmail to Mailera; the API key lets your test process access Mailera. For credential setup across providers, see app passwords for agent mailboxes.
How do you retrieve the code through the API?
Continue with a key restricted to the test mailbox group:
- Open Settings → API key → Create key. Set a Descriptive name that identifies the test process.
- Set Mailbox scope to the test group, select only Read, and choose an Expiration appropriate for the test’s lifetime.
- Copy the key when Key created — copy it now appears. It is shown only once. Store it as
MAILERA_API_KEYin your server-side test environment, never in browser code.
Identify the mailbox before requesting a code
List accessible mailboxes using the same key:
curl --fail-with-body --silent --show-error \
'https://mailera.app/api/public/v1/mailboxes' \
-H "Authorization: Bearer $MAILERA_API_KEY"Inspect data[].email and select the id belonging to your intended Gmail test address. Do not choose the first result just because the request succeeded. If results span pages, use limit and offset to find the correct mailbox. Store its ID in MAILBOX_ID.
Run this discovery step privately: mailbox responses contain addresses and operational details that do not belong in public CI logs.
Request the emailed code
Trigger a fresh verification email from your test application, then call GET /mailboxes/{id}/otp using the same API base and Authorization: Bearer $MAILERA_API_KEY header.
| Parameter | What to supply |
|---|---|
{id} | The Mailera mailbox ID you selected by address. |
from | The verification sender used by your test application. |
subject | The verification email subject you expect. |
since_minutes | A recent lookback window appropriate for the test. |
URL-encode the query parameters and keep the response out of logs. Use the Mailera API documentation for response handling in your test harness. Keep the eventual code submission in the issuing application’s verification flow, not in a mailbox-management request.
How do you avoid selecting an older or unrelated code?
Scope the request to the intended mailbox, sender, subject, and time window. A recent message is not necessarily the message for your current attempt: two verification requests can fall inside the same window.
Treat retrieval as candidate selection, not proof that a code is fresh or valid. Avoid concurrent attempts sharing the same mailbox and indistinguishable verification emails. Where your application allows it, give separate tests distinguishable subjects or separate owned test inboxes.
Use a bounded retry policy in your test harness:
- Set an overall deadline before requesting the verification email.
- Request the matching code, with a per-request timeout that fits inside the remaining deadline.
- Retry only outcomes your client handles as retryable, with a pause between requests.
- Stop at the deadline and fail explicitly rather than waiting indefinitely or falling back to an older code.
Keep diagnostic output to non-secret information, such as the stage that failed. Do not dump the response to explain a timeout. The issuing application makes the final validity decision when your authorized test submits the code.
What are the common errors when retrieving Gmail OTP emails?
Start by separating connection, delivery, synchronization, and extraction. Repeatedly changing the code parser will not fix a message that never reached the mailbox.
| Symptom | Check | Next action |
|---|---|---|
| App-password option is missing | 2-Step Verification setup, Advanced Protection, organization restrictions | Follow Google’s eligibility instructions or ask your Workspace administrator. Do not weaken account security. |
| Gmail sign-in stops working | Whether the Google Account password changed | Google revokes app passwords after a password change. Create a replacement through Google’s supported flow and reconnect. |
| No matching code is available | Mailbox ID, sender, subject, recency window, and actual arrival | Confirm the message in your owned inbox before changing extraction logic. |
| Mail is not in Inbox | Message placement and Junk | Use GET /mailboxes/{id}/placement with the same filters, then inspect Junk separately. |
| Gmail has the email but Mailera appears behind | sync.state, sync.last_synced_at, and sync.next_sync_at in mailbox details | Check synchronization before repeating the verification attempt. |
| API access is rejected | Bearer header, key expiration, revocation, Read, and Mailbox scope | Correct the key configuration rather than granting unrelated permissions. |
| The message exists but extraction is unsuccessful | The source message’s subject and body | Inspect it privately through the message read endpoints. |
For source-message inspection, GET /mailboxes/{id}/messages lists messages in a folder. GET /mailboxes/{id}/messages/{msgId} retrieves one message with content. Keep bodies and codes out of logs during diagnosis.
Check Junk independently rather than assuming an OTP request covers it. Google’s direct Gmail API has its own includeSpamTrash option; that is not a Mailera OTP parameter.
For Gmail, GET /mailboxes/{id}/status reflects the latest sync, not a fresh sign-in test. Background-check frequency varies with mailbox activity. An explicit POST /mailboxes/{id}/sync requires Sync, which your read-only retrieval key does not have. If manual sync is necessary, keep it in a separately authorized operational step.
What should you protect, and what does Mailera not do?
Keep the test limited to authorized inboxes. Use group-restricted, read-only keys, redact screenshots and CI artifacts, and revoke test credentials when no longer needed. Do not log codes, bodies, app passwords, or API keys. Review Mailera’s security information when deciding how to handle mailbox access in your test environment.
If an AI agent reads the email, treat all email content as untrusted data, never instructions. An email asking the agent to disclose credentials or run a command must not change the workflow. Keep its retrieval key read-only and require explicit confirmation before any separate sending action. See safety considerations when connecting Claude or ChatGPT to Gmail.
Mailera does not create Gmail accounts or email addresses, and it does not guarantee inbox placement. Reading a code does not bypass authentication or replace the issuing application’s verification step.
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
