How an AI agent receives a verification code by email

An AI agent receives a verification code by owning the inbox the code is sent to. The agent signs up with its own address, waits for the message, and reads the code or the confirmation link from it. A human's own sign-in codes are different: they must stay out of every agent's reach.

Updated

How does an AI agent get a verification code by email?

An AI agent gets a verification code the way a human does: the site sends it to an address, and whoever reads that address reads the code. The work is in the steps around it.

  1. Give the agent an inbox of its own. One address per agent keeps codes apart and gives each account one clear owner.
  2. Note the time, then submit the address on the site's sign-up or sign-in form.
  3. Wait for the message with a call that blocks until mail arrives. A loop that lists the inbox every few seconds is slower and wastes requests.
  4. Take the code, or the confirmation link, from the message.
  5. Use it straight away. Most codes expire within minutes and work once.

Two habits make the flow reliable. Match the message to the request by sender and by arrival time, so an old code is never reused. And keep the model away from the raw email where you can: pulling a code out of a message is a parsing job, not a reasoning job.

A one-time code and a confirmation link prove the same thing, that the agent reads the address, but they ask the agent to do different things.

One-time codeConfirmation link
What arrivesA short number or string to type backA URL to open
What the agent doesSubmits the code in the session that asked for itOpens the link, then returns to the flow
Main riskReading the wrong code, or an old oneOpening a link that does not belong to the site
Check firstSender and arrival timeThe link's domain matches the site

A link deserves more care than a code. A code does nothing until it is typed into the right form. A link takes the agent wherever it points, so compare its domain with the site the agent signed up on before opening it.

How do you wait for a code with Trotta Mail?

With Trotta Mail, an agent gets an inbox with one call and no account, and every message arrives with its codes and confirmation links already extracted. Create the inbox:

shell
curl -X POST https://api.trotta.email/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "riley"}'

The answer carries api_key, inbox.id and inbox.address. Keep the key: it is shown once. After the agent submits riley@trotta.email on the site, wait for the code:

shell
curl -G https://api.trotta.email/v1/inboxes/inb_7Qh2mXc4/wait \
  -d has_code=true -d from=harbor.example -d timeout=60 \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY"
The answer, shortened
{
  "message": {
    "id": "msg_8Kd2pXw1",
    "from": { "address": "no-reply@harbor.example", "name": "Harbor" },
    "subject": "Your Harbor verification code",
    "text": "Your verification code is 481920. It expires in 10 minutes.",
    "extracted": {
      "codes": [{ "value": "481920", "kind": "otp" }],
      "verify_links": []
    },
    "auth_kind": "code"
  },
  "timed_out": false
}

The request stays open until a matching message is delivered, for up to 60 seconds. On a timeout it returns { "message": null, "timed_out": true }: call it again. In TypeScript, with npm install trotta-mail:

typescript
import { TrottaMail } from "trotta-mail";

const mail = new TrottaMail({ apiKey: process.env.TROTTA_MAIL_API_KEY });
const inboxId = "inb_7Qh2mXc4";

const since = new Date();
await submitSignUpForm("riley@trotta.email"); // your agent fills the form

// Returns as soon as a message with a code is delivered, or null on a timeout.
const msg = await mail.inboxes.wait(inboxId, {
  hasCode: true,
  from: "harbor.example",
  after: since,
  timeout: 60,
});
if (!msg) throw new Error("No code arrived within 60 seconds");

const code = msg.extracted.codes[0].value; // "481920"

In Python, over plain HTTP:

python
import os

import requests

API = "https://api.trotta.email/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['TROTTA_MAIL_API_KEY']}"}


def wait_for_code(inbox_id: str, sender: str, since: str) -> str:
    """since is an ISO 8601 time taken just before the form was submitted."""
    response = requests.get(
        f"{API}/inboxes/{inbox_id}/wait",
        params={"has_code": "true", "from": sender, "after": since, "timeout": 60},
        headers=HEADERS,
        timeout=70,
    )
    response.raise_for_status()
    message = response.json()["message"]
    if message is None:
        raise TimeoutError("No code arrived within 60 seconds")
    return message["extracted"]["codes"][0]["value"]

For a confirmation link, read extracted.verify_links. has_code waits for mail that carries a code, so for a message with a link and no code, filter by from or subject. Through MCP the same wait is the wait_for_message tool:

A tool call
{
  "name": "wait_for_message",
  "arguments": { "inbox_id": "inb_7Qh2mXc4", "has_code": true, "timeout": 60 }
}

What are the risks when an agent reads verification mail?

A verification email is mail from outside, so it carries the risks of any mail, plus one of its own: it opens an account.

  • Fake verification mail. A message that looks like the site's can carry a link to a lookalike domain. An agent that opens every "confirm your address" link will open that one too.
  • Instructions in the message. Text aimed at the model can ride along with a real-looking code. If the model reads the body, it reads the instruction.
  • Code theft. Whoever can steer the agent can ask it to pass a code on. See verification code theft.
  • Stale codes. Without a time filter, the agent may submit the code from an earlier attempt.
  • The site's rules. Some sites do not allow automated sign-ups. Check the terms before you automate one.

Trotta Mail screens a verification email before it is delivered, like every message. The agent reads the safe view, links that are not clean are defanged, and mail the guard holds never comes back from wait. No filter catches everything: a cleverly worded message with no technical tell can still be delivered, which is why the domain check above stays in your code.

Why must a human's own sign-in codes stay out of an agent's reach?

A human's sign-in codes must stay out of an agent's reach because whoever reads them can take the account. An agent connected to a human's mailbox can be steered by one injected message: request a password reset on a site, read the reset email, hand the account over. Email is the recovery channel for most other accounts.

The rule is simple. An agent reads codes sent to its own inbox, for accounts it created. It never reads codes sent to a human.

Trotta Mail enforces the rule with sealed login mail. In a human's mailbox, a message that carries a one-time code, a password reset link or a sign-in link does not exist for any API key or MCP tool. It is absent from reads, lists, search, wait, events and webhooks, whatever the key's scopes.

InboxLogin mail startsWho reads a code
An agent's own inboxOpenThe agent's key, and a signed-in human
A human's mailboxSealedThe human, in the web app. No key and no tool

Only a signed-in human can open a mailbox's login mail to keys, and the change is written to the audit log. A key can seal an inbox, never unseal one. The security model has the full rules.

To give an agent an address for its own sign-ups, start with the quickstart or see the sign-up and verification use case.

Questions

Can an AI agent complete two-factor authentication by email?

Yes, when the second factor is a code sent to an inbox the agent owns. It should never complete one that goes to a human's phone, authenticator app or mailbox.

How long should an agent wait for a verification code?

One wait request holds for up to 60 seconds. On a timeout, call it again, and stop after a fixed number of tries so a failed sign-up does not hang the agent.

What if the code never arrives?

Check the address the agent typed, then the inbox's counts.held. A wait never returns held mail, and a human reviews what the guard is holding.

Does the agent need a human to set up its inbox?

No. POST /v1/agents/signup needs no account and no key. A human can claim the agent later with the claim_url in the answer.

Can the code arrive at an address on my own domain?

Yes, on a paid plan. Addresses on the Free plan are at trotta.email, and your own domain starts on the Developer plan.

Give your agent an inbox of its own. Free for two inboxes. No card.