Verification Code Extraction

mails-agent automatically extracts verification codes, OTPs, and confirmation codes from incoming emails. This is the core primitive that enables AI agents to complete signup flows, handle 2FA challenges, and verify email addresses autonomously.

Supported Languages

The extraction engine recognizes verification code patterns in four languages:

Language	Code	Example patterns
English	EN	"Your code is 482910", "Verification code: 5839"
Chinese	ZH	"验证码：483920", "您的验证码是 291048"
Japanese	JA	"認証コード: 583920", "確認コードは 492013"
Korean	KO	"인증 코드: 384920", "인증번호는 583021"

How It Works

Codes between 4 and 8 characters (digits or alphanumeric) are detected
Both the email subject line and body are scanned
Subject-line codes take priority (many services put the code in the subject for quick access)
Common patterns like "code is", "code:", "OTP", and their translations are matched
Extraction runs automatically on every inbound email -- no configuration needed

API Endpoint

GET/v1/code — Wait for a verification code (long-poll)

This endpoint long-polls until a verification code arrives or the timeout expires. It returns the most recently extracted code for the mailbox.

Query parameters

Parameter	Type	Default	Description
`to`	string	-	Mailbox address to watch for incoming codes (optional)
`timeout`	number	30	Max seconds to wait (1-55)
`since`	string	-	ISO 8601 timestamp. Only consider emails after this time.

Example: curl

# Wait up to 60 seconds for a code sent to [email protected]
curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/[email protected]&timeout=60"

{
  "id": "msg_abc123",
  "code": "482910",
  "from": "[email protected]",
  "subject": "Your verification code is 482910",
  "received_at": "2026-04-01T12:30:00Z"
}

If no code arrives before the timeout, the endpoint returns HTTP 200 with code set to null:

{
  "code": null
}

CLI Usage

# Wait for a code (blocks until received or timeout)
mails code --to [email protected] --timeout 30

# Output: 482910

# Use in a script
CODE=$(mails code --to [email protected] --timeout 60)
echo "Got code: $CODE"

Python SDK

from mails_agent import MailsClient

client = MailsClient(api_url="https://mails-worker.genedai.workers.dev",
                     token="your-api-key", mailbox="[email protected]")

# Synchronous -- blocks until code arrives
result = client.wait_for_code(timeout=60)
if result:
    print(f"Verification code: {result.code}")

# Async
import asyncio
from mails_agent import AsyncMailsClient

async def get_code():
    client = AsyncMailsClient(api_url="https://mails-worker.genedai.workers.dev",
                              token="your-api-key", mailbox="[email protected]")
    result = await client.wait_for_code(timeout=60)
    return result.code if result else None

Use Cases

Agent self-signup

An AI agent creates an account on a third-party service using its mails-agent email address, then retrieves the verification code to complete registration:

# 1. Agent fills signup form with [email protected]
# 2. Wait for the verification email
CODE=$(mails code --to [email protected] --timeout 60)
# 3. Agent submits the code to complete signup

Two-factor authentication (2FA)

When a service sends a 2FA code via email, the agent can retrieve it in real time:

result = client.wait_for_code(timeout=30)
if result:
    # Submit the 2FA code to continue the login flow
    print(f"2FA code: {result.code}")

Email verification for existing accounts

Confirm email ownership during account settings changes:

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/code?timeout=45"