OTP
Code plus message context
Return the current candidate, message identifier, received time, and matching rule.
Message processing feature
Turn an inbound email into bounded, usable data.
Agents rarely need an entire raw message. They need a verified code, an expected link, a named attachment, or a small set of fields with enough context to make the next decision.
Direct answer
mails0 exposes structured message metadata, bodies, headers, attachments, links, and extracted verification codes through mailbox-scoped interfaces. The safe pattern is to list and filter first, select one current message, retrieve only the required field or attachment, validate it against the workflow, and keep raw message content out of general model context and analytics.
A bounded extraction pipeline
Each stage removes ambiguity before untrusted content reaches an agent or browser action.
- 01List metadata
Query the scoped mailbox by direction, time, sender, and recipient.
- 02Choose one message
Reject stale or duplicate candidates before reading the body.
- 03Extract one value
Return a code, expected-host link, header, or approved file.
- 04Validate the outcome
Confirm the external workflow reached the expected state.
Message model
Inspect the envelope before the payload
A message record should first answer who sent it, which mailbox received it, when it arrived, whether it belongs to the current thread, and what payload types are present. That metadata is cheaper to inspect and safer to expose than a full HTML body or attachment.
The retrieval query should include a trigger boundary. If a test requested a code at 10:14, a matching message from yesterday is not evidence that today's flow worked. Sender display names are also insufficient. Use addresses, expected domains, message timestamps, and known workflow state together.
| Field | Use it for | Do not assume |
|---|---|---|
| Envelope and recipients | Mailbox routing and tenant checks | The visible To header proves final delivery |
| Received time | Rejecting stale results | Clock order alone identifies the correct event |
| Headers | Thread and provider context | A familiar display name is trusted identity |
| Attachment metadata | Type, name, and size policy | The filename describes safe content |
Attachment handling
Download only after policy has enough information
An attachment introduces a second payload with its own parser and risk. List the filename, content type, size, and message relationship first. Reject unexpected formats and large files before moving bytes into a browser, model tool, or downstream document processor.
File extensions and MIME types can disagree. Treat both as hints, not proof. A production workflow should use isolated storage, malware scanning where appropriate, a strict size ceiling, and a parser selected by observed content. Do not execute macros or active content as part of routine extraction.
- Allow expected file types per workflow instead of globally.
- Store temporary files outside the repository and prompt history.
- Use content hashes to make retry processing idempotent.
- Delete short-lived files according to a documented retention rule.
Extraction contract
Return evidence with the extracted value
A useful extraction result is not only 123456. It includes which message produced the value, when that message arrived, which rule matched, and whether multiple candidates existed. That evidence lets the caller reject ambiguity without receiving every body in the inbox.
Links need equivalent treatment. Parse the URL, enforce the expected host and protocol, strip tracking parameters when the application allows it, and return the normalized target. The browser should still confirm the resulting page state instead of treating a successful navigation as verification.
Link
Normalized expected-host URL
Reject unknown schemes, hosts, redirects, and stale confirmation messages.
Attachment
Approved file reference
Return metadata and a bounded download path, not an unrestricted inbox export.
Failure handling
Make ambiguity an explicit result
Email delivery can be delayed, duplicated, reordered, or rewritten by an intermediary. The extraction tool should distinguish no message, one valid message, several candidates, parse failure, rejected attachment, and timeout. A single empty result hides the layer that needs repair.
Retries should reuse an idempotency key or a stored trigger marker. Repeating the signup action every time a poll returns empty can create multiple codes and make the newest-message rule unstable. The caller should decide whether to wait, retry the original action, or stop with evidence.
| Result | Meaning | Caller action |
|---|---|---|
| No candidate yet | Delivery may still be in flight | Continue bounded wait |
| Several current candidates | Trigger or filter is ambiguous | Stop and inspect metadata |
| Payload rejected | Type, size, host, or parser policy failed | Do not bypass automatically |
| Value accepted | A current message produced one valid value | Continue and assert external state |
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 message documentationMessage and attachment operations
Questions and answers
Questions about Attachments and extraction
Can mails0 retrieve email attachments?
Yes. The API and tools expose attachment metadata and retrieval for scoped mailbox messages. Apply file type, size, storage, and parser policy before passing a file to another system.
Should an agent receive the full email body?
Only when the task genuinely requires it. Prefer metadata filtering and a purpose-built extraction result for codes, links, headers, or attachments.
How do I prevent an old OTP from matching?
Record the trigger time, filter to messages received afterward, validate sender and recipient context, and stop when several current candidates remain ambiguous.
Start with a bounded inbox
Prove the smallest useful email loop.
Start with one scoped inbox and one expected message. Add durable identity, sending, and operational complexity only when the first loop works.