An AI agent should not “figure out” how email works at runtime. Email is too stateful, too asynchronous, and too easy to parse incorrectly. If the agent needs to sign up for a service, receive an OTP, follow a magic link, or verify a workflow, it needs a narrow tool contract it can trust.
For Mailhook, the best starting point is the canonical llms.txt contract. Treat it as the source of truth for how an agent should discover Mailhook’s API surface, expected payloads, and integration details. Human-readable docs are useful, but agent workflows work best when the model is given a small, explicit, machine-oriented contract instead of a broad website crawl or a vague prompt.
The goal is simple: let the agent use email as a deterministic tool, not as a human mailbox.
Why agents should start with llms.txt
LLM agents are good at planning, summarizing, and choosing between tools. They are less reliable when asked to infer API details from scattered context. A contract-first setup reduces that ambiguity.
With Mailhook, the agent’s job is usually not “manage an email account.” It is more specific:
- Create a disposable inbox through an API.
- Use the returned email address in a signup, QA, or verification flow.
- Receive the incoming email as structured JSON.
- Wait through a webhook or polling path.
- Extract only the needed artifact, such as an OTP or verification URL.
- Avoid acting on hostile or irrelevant email content.
The Mailhook llms.txt file should be the reference your agent framework, tool wrapper, or orchestration layer reads before implementing those steps. It helps prevent the most common integration problem in agent systems: the model invents an endpoint, field, behavior, or security rule that does not exist.
What the llms.txt contract should define for your agent
Do not ask the model to memorize Mailhook’s full integration details from a long prompt. Instead, use llms.txt to shape a concise internal contract for your tools.
At a minimum, your implementation should verify these areas against the canonical contract:
| Contract area | Why it matters for agents | What to confirm in llms.txt |
|---|---|---|
| Inbox creation | Agents need an isolated address for a task or attempt. | The supported API pattern for creating disposable inboxes and the fields returned. |
| Message format | Agents should consume JSON, not scrape rendered mailboxes. | The structured JSON shape for received emails and identifiers. |
| Delivery options | Email arrival is asynchronous. | How to use real-time webhooks and the polling API. |
| Webhook security | Incoming HTTP requests must be authenticated before processing. | How signed payloads are represented and verified. |
| Domain strategy | Some workflows can use shared domains, while others need owned domains. | How instant shared domains and custom domain support are exposed. |
| Batch workflows | High-volume agents may process many inboxes or emails. | The supported batch processing semantics, if relevant to your workflow. |
This table is not a substitute for the contract. It is a checklist for turning the contract into safe agent tools.
The right mental model: Mailhook is an inbox primitive, not a mailbox UI
Traditional email automation often starts with a human mailbox. The test or agent logs into Gmail, searches for a subject line, opens HTML, clicks links, and hopes nothing changed. That model is fragile for autonomous systems.
Mailhook is built around programmable temporary inboxes. Instead of sharing one mailbox across many tests or agents, your system creates disposable inboxes via API and receives messages as structured JSON. That changes the architecture:
| Human mailbox model | Agent-ready Mailhook model |
|---|---|
| Persistent account | Disposable inbox resource |
| Shared address | Isolated address per task or attempt |
| Manual inbox search | API, webhook, or polling retrieval |
| HTML-first parsing | Structured JSON email output |
| Human judgment | Deterministic matchers and artifact extraction |
| Browser session security | Signed payloads and controlled tool access |
This distinction matters because an LLM agent should not be asked to “look through the inbox.” It should call a tool with a narrow purpose, such as wait_for_verification_email, and receive a minimal, validated result.
Build a small tool layer over the Mailhook contract
Do not expose a raw email API directly to the model unless your agent framework is designed for that level of control. A safer pattern is to create a wrapper layer that maps Mailhook’s contract into a few deterministic tools.
A practical tool set might look like this:
| Agent tool | Purpose | Recommended output to the model |
|---|---|---|
create_temp_inbox |
Provision a disposable inbox for a single workflow. | Email address, inbox ID, and correlation metadata. |
wait_for_email |
Wait for a relevant message through webhook-backed state or polling. | Message ID, sender, subject, received time, and matched reason. |
extract_verification_artifact |
Extract an OTP, magic link, or confirmation URL. | The single artifact plus confidence or validation status. |
get_safe_email_summary |
Show only sanitized, minimal message content. | Plain text summary and trusted metadata. |
process_email_batch |
Handle multiple inboxes or messages for high-volume runs. | Batch status, matched artifacts, and failures. |
These tool names are examples for your agent layer, not a claim about Mailhook endpoint names. Use Mailhook’s llms.txt for the exact API details, payload structure, authentication expectations, and webhook verification rules.
The important design choice is that your agent does not need raw MIME, browser access to a mailbox, or a large untrusted email body. It needs a bounded function call and a typed result.
A contract-first workflow for verification agents
A common Mailhook agent flow looks like this:
- The orchestrator reads the Mailhook llms.txt contract and configures the API client.
- The agent calls a tool to create a disposable inbox for the current attempt.
- The target application sends an email to the generated address.
- Mailhook delivers the received email as structured JSON through webhook notification or makes it available through polling.
- Your tool verifies signed webhook payloads before processing them.
- The tool selects the correct message using inbox ID, recipient address, sender, subject, and expected correlation signals.
- The tool extracts the minimum artifact, such as an OTP or verification link.
- The agent receives only that artifact, not the full raw email unless there is a debugging reason.
In pseudocode, the agent-facing layer might look like this:
async function verifyEmailSignup(agentTask) {
const inbox = await mailhookTools.createTempInbox({
purpose: "signup_verification",
correlationId: agentTask.id
})
await appUnderTest.startSignup({
email: inbox.email,
correlationId: agentTask.id
})
const message = await mailhookTools.waitForEmail({
inboxId: inbox.inboxId,
expectedPurpose: "signup_verification",
timeoutMs: 60_000
})
const artifact = await mailhookTools.extractVerificationArtifact({
messageId: message.messageId,
expectedType: "otp_or_magic_link"
})
return artifact
}
This example intentionally avoids endpoint paths and exact field names. Those belong in your Mailhook client, generated or implemented from the llms.txt contract, not in the agent’s reasoning loop.
Webhooks first, polling as a fallback
Agents often fail when they rely on fixed sleeps. “Wait 30 seconds, then check the inbox” is simple, but it creates flakes under parallel runs, retries, slow email delivery, and queue delays.
Mailhook supports real-time webhook notifications and a polling API, which lets you design a more reliable wait strategy. Use webhooks as the primary path when your infrastructure can receive inbound HTTP requests. Use polling as a fallback when local development, CI networking, or firewall constraints make webhooks inconvenient.
A robust agent tool should hide that complexity from the model. The agent should call wait_for_email; the tool should decide whether the matching message is already available from webhook state or whether it needs to poll.
For webhook handling, apply these rules before any LLM sees the message:
- Verify signed payloads according to the Mailhook contract.
- Parse only after authenticity checks pass.
- Store stable delivery and message identifiers for idempotency.
- Deduplicate repeated processing by message or artifact identifier.
- Return a minimal, typed result to the agent.
For polling, keep the loop bounded. Use a deadline, backoff, and narrow matchers. The agent should not be allowed to poll forever or trigger resend loops without explicit budget controls.
Treat structured JSON emails as the agent boundary
Email is messy. Headers can be duplicated. HTML can change. Links can be hidden behind tracking redirects. Message bodies can contain prompt injection text, malicious instructions, or content that looks relevant but belongs to a different attempt.
Mailhook’s structured JSON email output is the right boundary for agent workflows because it lets your code make deterministic decisions before the model gets involved. The LLM should not parse arbitrary HTML when a small deterministic extractor can do the job.
A safe agent-visible message view might include:
| Field type | Safe use | Caution |
|---|---|---|
| Provider or system identifiers | Correlation, dedupe, debugging. | Do not expose secrets unnecessarily. |
| Recipient and inbox ID | Confirm the message belongs to the current attempt. | Prefer inbox-scoped matching over shared inbox searches. |
| Sender and subject | Add intent signals for matching. | Treat sender-claimed fields as untrusted hints. |
| Plain text body excerpt | Help the agent understand context. | Keep excerpts short and sanitized. |
| Extracted artifact | Let the agent complete the workflow. | Validate links and consume OTPs once. |
If the agent only needs a six-digit code, give it the six-digit code. If it only needs a magic link, give it the validated link. Keeping raw content away from the model reduces prompt-injection risk and makes failures easier to debug.
Agent guardrails that belong outside the prompt
Prompt instructions are not enough to secure an email-capable agent. The guardrails should live in code, policy, and the tool contract.
Start with one disposable inbox per task, run, or attempt. Reusing inboxes creates stale-message bugs, parallel race conditions, and accidental cross-talk between agents. A fresh inbox gives your matchers a small search space.
Next, make correlation explicit. Store the inbox ID, generated email address, attempt ID, expected sender or domain, and expected artifact type. The agent should not select from a global mailbox. It should operate inside one known inbox and one known task context.
Then constrain artifact handling. If your workflow expects an OTP, extract an OTP. If it expects a verification URL, validate the URL against allowed domains before returning it to the agent. Do not let the model decide that a random link in an email “looks right.”
Finally, separate transport security from semantic parsing. Webhook signature verification answers “Did this payload come through the expected delivery path?” Message matching answers “Is this the email for this task?” Artifact validation answers “Is this safe and useful to act on?” Those are different checks, and they should happen in that order.
How to turn llms.txt into implementation work
A practical rollout does not need to be complicated. Start by making the contract a build-time or configuration-time dependency for your Mailhook client. Then wrap the raw client in task-specific tools.
Use this implementation checklist:
- Read the Mailhook llms.txt contract before writing or generating client code.
- Confirm the exact inbox creation, message retrieval, webhook, polling, and signature semantics.
- Implement a small wrapper layer with task-oriented tools instead of exposing raw API calls to the agent.
- Use disposable inboxes for isolation, especially for signups, OTPs, QA flows, and agent attempts.
- Prefer webhooks for low-latency delivery and keep polling as a bounded fallback.
- Verify signed payloads before parsing webhook JSON.
- Return structured, minimized artifacts to the model rather than raw email content.
- Log stable identifiers, such as inbox, message, delivery, attempt, and artifact IDs, for debugging.
- Keep shared versus custom domain choice in configuration, not in the agent’s prompt.
- Use batch email processing patterns when the orchestrator needs to run many inbox workflows in parallel.
The key is to let the contract govern the integration, while the agent only sees the safe task abstraction.
Common mistakes when agents skip the contract
The first mistake is endpoint hallucination. A model sees “temporary email API” and guesses REST paths, parameters, or response fields. That might look plausible in a demo but fail in production. Always bind the implementation to the canonical contract.
The second mistake is giving the LLM too much email content. Raw HTML, full headers, and arbitrary body text increase the chance of prompt injection and brittle parsing. Prefer structured JSON, deterministic extractors, and minimal agent-visible views.
The third mistake is treating webhooks as trusted just because they arrive at the right URL. Signed payloads exist for a reason. Verify authenticity before processing and keep signature verification outside the model’s control.
The fourth mistake is reusing inboxes across attempts. Even a good matcher can choose the wrong stale message when tests retry, agents run in parallel, or a provider resends an email. Disposable inboxes are cheap operational isolation.
The fifth mistake is letting the agent own waiting logic. Waiting for email should be a deterministic tool with deadlines, dedupe, and fallback behavior. The model can decide that it needs an email, but code should decide how to wait for it.
Where Mailhook fits in an agent stack
Mailhook provides the email-specific primitives that agents need without forcing them into human mailbox workflows:
- Disposable inbox creation via API.
- Structured JSON output for received emails.
- RESTful API access.
- Real-time webhook notifications.
- Polling API for retrieval fallback.
- Instant shared domains for quick starts.
- Custom domain support for teams that need domain control.
- Signed payloads for webhook security.
- Batch email processing for higher-volume workflows.
- No credit card required to get started.
That combination is especially useful for agents that need to complete signup verification, QA automation, client operations, or temporary email-driven workflows. The agent gets a controlled email interface. Your engineering team gets observability, safer parsing, and fewer mailbox-related flakes.
Frequently Asked Questions
What is the Mailhook llms.txt contract? It is the canonical integration reference Mailhook provides for LLMs and agent builders. Use https://mailhook.co/llms.txt to confirm the current API, payload, webhook, and integration details instead of relying on guessed behavior.
Should an AI agent call Mailhook’s API directly? Usually, it is safer to put a small tool layer between the agent and the API. The tool layer can enforce deadlines, verify webhook signatures, dedupe messages, validate links, and return only the minimal artifact the agent needs.
Why use disposable inboxes instead of a shared email account? Disposable inboxes isolate each task or attempt. That reduces stale-message bugs, parallel test races, accidental cross-talk, and complex mailbox searching.
Should agents use webhooks or polling to receive email? Use webhooks when possible for real-time delivery, then keep polling as a bounded fallback. The agent should call one wait tool, while your implementation chooses the best delivery path.
Is structured JSON safer than raw email for LLM workflows? Yes. Structured JSON lets your code match, dedupe, and extract artifacts before the model sees anything. This reduces fragile HTML scraping and limits prompt-injection exposure.
Does Mailhook replace a human email account? No. Mailhook is best modeled as programmable inbound inbox infrastructure for automation, QA, and agent workflows. It is not a general human mailbox UI or outbound email account.
Build Mailhook agents from the contract up
If your agent needs email, do not start with a prompt that says “check the inbox.” Start with the contract, then expose a few safe tools.
Read the Mailhook llms.txt contract, create disposable inboxes through the API, receive messages as structured JSON, and give your agents only the verified artifacts they need to complete the task.
You can explore Mailhook at mailhook.co and start building programmable temp inbox workflows without a credit card.
