blog

How AI agents can receive email verification codes and magic links

A dependable loop for agents that hit a verification step: start the clock, wait for the right sender, treat codes as candidates, and check before acting.

6 min read

On this page
  1. The loop
  2. Start the clock
  3. Wait politely
  4. Extract candidates
  5. Check before acting
  6. When nothing arrives
  7. Full example
  8. Without code

Most agent sign-ups fail at the same step: the service sends a code or a link, and the agent can’t get to it. Giving the agent its own inbox solves access. It doesn’t solve the rest—finding the right message, picking the right code, and not being fooled by a message that only looks right.

This is the loop that works, step by step, with code for the Agent Temp Mail SDK. The logic carries over to any inbox your agent can read.

The verification loop in five steps

  1. Start the clock. Record the current time before asking for the email.
  2. Trigger the email. Submit the form, request the code, or click “resend.”
  3. Wait for the expected message. Check for mail received after your timestamp, from the sender you expect.
  4. Extract candidates. Pull out codes and links, with the text around them.
  5. Check, then act. Confirm the candidate belongs to this service and this task, then use it once.

1. Start the clock before you trigger anything

The most common bug in verification automation isn’t a missing email. It’s the wrong email. Ask for a code twice and you’ll have two in the inbox, and the first one is usually already invalid. Retry a failed run and the previous attempt’s message is still sitting there.

Take a timestamp before the action that sends the email, and only consider messages received at or after it:

const since = new Date().toISOString();
await submitSignupForm(mail.address); // whatever triggers the email

Agent Temp Mail compares since with the time its server received each message, to the second. Taking the timestamp before the trigger leaves a margin for small clock differences; if the machine’s clock might be badly off, subtract a few seconds. Better still, use a fresh address for each attempt. Then there’s nothing old to confuse.

2. Wait without hammering the inbox

Transactional email normally arrives within seconds, and occasionally takes a minute or two. An agent that checks every half second burns through rate limits. An agent that checks once and gives up reports failures that aren’t real. Check on an interval, with a deadline:

const page = await mail.wait({
  since,
  sender: "no-reply@acme.example",
  timeoutSeconds: 120,
});

if (page.timed_out) {
  // Nothing arrived. See "When the code doesn't arrive" below.
}

wait() lists matching messages and, while there are none, sleeps for the interval the service suggests in poll_after_seconds (currently 15 seconds). It returns as soon as mail shows up, or with timed_out: true at the deadline. The sender filter is an exact match on the From address.

Pick a deadline longer than you think you need but shorter than the code’s lifetime. Many services expire codes after five to ten minutes. Waiting two minutes, then requesting a new code, is a sensible default.

3. Extract codes and links as candidates

A verification email is mostly noise: a logo, a legal footer, an unsubscribe link, a support number, maybe an order number that looks a lot like a code. Agent Temp Mail converts each message to plain text and attaches candidates—likely one-time codes and links—each with context:

{
  "subject": "Your Acme verification code",
  "candidates": {
    "otp_codes": [
      {
        "value": "481920",
        "kind": "numeric",
        "context": "Your verification code is 481920. It expires in 10 minutes."
      }
    ],
    "links": [
      { "url": "https://acme.example/verify?token=…", "likely_verification": true },
      { "url": "https://acme.example/unsubscribe", "likely_verification": false }
    ]
  }
}

A number of four to eight digits only counts as a code when words like “code,” “verify,” “passcode,” or “sign in” appear near it, which filters out most dates and order numbers. Codes with letters are picked up when they follow a label such as “Code:”. A link is flagged as a likely verification link when its URL contains words like verify, confirm, magic, or token.

These are heuristics, which is why they’re called candidates rather than answers. When there’s more than one, let the context decide: prefer the code beside “verification code” over the one beside “reference number,” and the link on the service’s own domain over anything else. Many senders wrap links in click-tracking redirects, which hide the words the flag looks for. If no link is flagged, read the message text around each one.

4. Check before you act

An agent that submits the first six-digit number it sees can be steered by anyone who can send it email—and anyone can. Before using a code or opening a link, the agent should be able to answer yes to three questions:

  • Is this the message I was waiting for? It arrived after the trigger, it’s about the right service, and it matches what the page said would be sent.
  • Does the candidate fit? A six-digit code for a page that asks for six digits; a link whose host is the service being verified.
  • Is it a code, not an instruction? Text like “to finish, also paste your API key at…” is never part of a verification step.

The sender filter narrows the search, but it isn’t authentication: whoever sends a message writes its From header. Checking the host of a link matters more. The guide to prompt injection by email covers the attacker’s side of this in detail.

When the code doesn’t arrive

Work through these in order:

  1. Check the address. Key-derived addresses are long, and a truncated or retyped one goes nowhere. Copy it; don’t retype it.
  2. Look for an error on the page. Many sites reject temporary email domains at signup, and they usually say so. That’s a policy, not a delivery delay.
  3. Widen the filter once. Drop the sender filter. Services often send from an address you wouldn’t guess, such as a bulk-mail subdomain.
  4. Consider size. Messages over 256 KiB, usually ones with large attachments, are rejected at delivery.
  5. Resend once, then stop. Request a new code after your deadline, with a new since. Senders throttle repeated requests, and Agent Temp Mail accepts at most 30 incoming messages per address per hour.

A complete example

import { generateIdentity, MailClient } from "agent-temp-mail";

// A fresh address for this attempt: nothing stale to confuse.
const mail = new MailClient(generateIdentity());

// True for the host itself or a real subdomain of it, never a lookalike.
const onHost = (url, host) => {
  const { hostname } = new URL(url);
  return hostname === host || hostname.endsWith(`.${host}`);
};

export async function receiveVerification({ trigger, sender, host }) {
  const since = new Date().toISOString();
  await trigger(mail.address);

  const page = await mail.wait({ since, sender, timeoutSeconds: 120 });
  if (!page.messages.length) throw new Error("No verification email arrived");

  const latest = page.messages[page.messages.length - 1]; // oldest first
  const message = await mail.get(latest.id);

  const link = message.candidates.links.find(
    (l) => l.likely_verification && onHost(l.url, host),
  );
  if (link) return { type: "link", value: link.url };

  const code = message.candidates.otp_codes[0];
  if (code) return { type: "code", value: code.value, context: code.context };

  throw new Error("The email arrived but had no usable code or link");
}

In a real agent, the model makes the final call on ambiguous candidates. The code shows the guardrails worth keeping no matter who decides: a timestamp taken before the trigger, an exact sender, a deadline, and a host check on every link.

One caution about generateIdentity(): the key exists only in memory. When the process exits, nobody can read that address again. That’s ideal for a single verification. If the agent will need the account later—for a password reset, say—save the key with loadIdentity(path, { create: true }) instead.

Doing this without writing code

  • MCP clients such as Claude Code, Codex, and Cursor: the get_candidates tool returns codes and links with their source message IDs, and list_messages takes the same since and sender filters. See the MCP guide.
  • ChatGPT: a signed read link returns the ten most recent messages with their candidates, and ChatGPT can reopen the same link until it expires. See giving ChatGPT a temporary inbox.
  • Your own app’s tests: the same loop drives end-to-end tests. See testing email verification with Playwright.