Verification codes and magic links

Agents that sign up for things need to read a login code or click a magic link. Agentboxd pulls both out of every inbound message and gives you a long-poll endpoint that waits for them.

#The flow

• Create (or reuse) an inbox for the agent.
• Record the time, before triggering the email.
• Have the agent submit the sign-up form with the inbox address.
• Call waitForVerification with that time as since. It returns as soon as a matching email arrives.

const inbox = await mr.inboxes.create({ client_id: 'signup-agent' });
const since = new Date().toISOString(); // record the time before you trigger the email

await signUp({ email: inbox.address }); // your agent fills in the form

const v = await mr.messages.waitForVerification(inbox.id, {
  since,
  from: 'github.com',
  timeout: 60,
});
if (!v) throw new Error('no verification email within 60 s');

console.log(v.code ?? v.link, v.confidence); // "48213907" 1

from datetime import datetime, timezone

inbox = mr.inboxes.create(client_id="signup-agent")
since = datetime.now(timezone.utc).isoformat()

sign_up(email=inbox["address"])  # your agent fills in the form

v = mr.messages.wait_for_verification(inbox["id"], since=since, from_="github.com", timeout=60)
if v is None:
    raise RuntimeError("no verification email within 60 s")
print(v["code"] or v["link"], v["confidence"])

#What comes back

{
  "data": {
    "code": "48213907",
    "link": null,
    "confidence": 1,
    "jev_probability": 0.99,
    "message_id": "a0000000-…",
    "from": "GitHub <noreply@github.com>",
    "subject": "Your GitHub launch code",
    "received_at": "2026-09-24T12:00:04.000Z"
  }
}

#How detection works

Detection is deterministic first. A number or code only counts when it sits close to a word like “code”, “verification” or “one-time”, and anything that looks like a phone number, date, price, year or order number is dropped. Regex results are capped at confidence 0.7.

Then JEV, a fast decision model, answers “is this a login, one-time-code or confirm-your-email message?”. If its probability is 0.8 or more, confidence rises to at least 0.95; under 0.2, it drops to at most 0.2. In our smoke test, a login-code email came back as verification with confidence 1.00.

Every message also carries ai.verification, so you can read codes from messages.list or a webhook too.

#Safety

Only use a code or link for a sign-up your agent started. A code in an unexpected email is a phishing signal, not an instruction. The MCP server tells models the same thing.