Scope
Correct mailbox
Use a dedicated or explicitly bound recipient so unrelated messages are outside the result set.
Direct answer
How do you extract OTP codes from email with an API?
Match the correct message first, then parse the code with context and a bounded timeout.
Direct answer
Bind a dedicated inbox, record when the OTP request was triggered, wait for a new inbound message to that recipient, validate expected sender context, and parse a code near verification keywords or delimiters. Reject stale messages, dates, and ambiguous candidates. With mails0, use mails code, the HTTP endpoint, Python SDK, or MCP wait_for_code tool.
Decision map
Select the message before selecting the code
- 01Correct mailbox
Use a dedicated or explicitly bound recipient so unrelated messages are outside the result set.
- 02Current request window
Ignore messages before the OTP request and stop at a deadline.
- 03Expected message
Use sender, subject, direction, and verification language before parsing candidate strings.
Correct order
Select the message before selecting the code
Time
Current request window
Ignore messages before the OTP request and stop at a deadline.
Context
Expected message
Use sender, subject, direction, and verification language before parsing candidate strings.
Implementation
Retrieve and use the code
-
01
Trigger the OTP request
Record recipient and start time immediately before the application call.
-
02
Wait for matching inbound email
Poll or subscribe under the scoped mailbox with a bounded timeout.
-
03
Parse with contextual rules
Prefer candidates near code keywords and explicit delimiters; reject date-like numeric strings.
-
04
Submit and verify once
Use the code, assert success, and separately test expiry and replay behavior.
Extract code
mails code --to [email protected] --timeout 60Ambiguity
Do not return the first number in the body
Verification messages often contain dates, account numbers, order numbers, support phone numbers, and footer text. A robust parser uses context and retains the selected message identity for debugging.
If several plausible candidates remain, return an explicit ambiguity error or narrow the query rather than guessing. The application can then request a new code or escalate.
- Prefer recent inbound mail after the trigger.
- Use recognized verification keywords and delimiters.
- Support expected alphanumeric formats.
- Reject common years and YYYYMMDD date patterns.
- Do not log the code broadly after use.
Interface
Choose a retrieval interface
| Environment | Interface | Result handling |
|---|---|---|
| Shell or coding agent | mails code | Use exit status and stdout only in the scoped task. |
| MCP assistant | wait_for_code | Return structured tool result without key exposure. |
| Python test | SDK method | Await typed result and assert application state. |
| Backend service | HTTP plus event handling | Persist message ID and processing state idempotently. |
Evidence
Sources and product scope
Product behavior is verified against the mails0 source and documentation. External comparisons link to official vendor documentation checked on 2026-08-15.
- mails0 source repositoryImplementation, license, and deployment source
- mails0 code extraction docsSupported patterns and examples
Questions and answers
Related questions
Can OTP codes contain letters?
Yes. Some services use alphanumeric codes. Configure or choose a parser that supports the formats your applications send.
How do I avoid extracting a date?
Require verification context, reject common year and date patterns, and test the parser against real product templates.
What should happen when two possible codes are found?
Narrow by sender, time, subject, or message identity. If ambiguity remains, fail explicitly instead of guessing.
Start with a bounded inbox
Give the agent an inbox, then prove the workflow.
Start with a receive-only temporary mailbox. Move to a permanent identity or self-hosted deployment only after the workflow reaches a real email value event.