OTP-верификация по электронной почте — один из тех потоков, которые “работают нормально”, пока вы не поместите их в CI, не запустите тесты параллельно или не позволите LLM-агенту управлять ими. Тогда обычные режимы отказа проявляются быстро: коллизии общих почтовых ящиков, фиксированные задержки, дублированные письма, повторы, которые пересылают коды, и хрупкий скрапинг HTML.
Верификация временной электронной почты становится надежной только тогда, когда вы относитесь к верификационному письму как к детерминированному потоку событий, привязанному к конкретному, краткосрочному почтовому ящику, а не как к “какому-то случайному адресу”, который вы надеетесь прочитать позже.
Это руководство описывает детерминированный OTP-поток, который можно повторно использовать в E2E тестах, QA автоматизации и цепочках инструментов агентов, с конкретными правилами дизайна для ожидания, дедупликации, извлечения и безопасности.
Что должна означать “верификация временной электронной почты” (для OTP)
Для OTP-верификации цель состоит не в том, чтобы “получить письмо” в общем смысле. Цель состоит в том, чтобы:
- Предоставить почтовый ящик, который изолирован для одной попытки.
- Инициировать ровно одно верификационное письмо для этой попытки.
- Ждать прибытия используя явные временные бюджеты, а не
sleep(10_000). - Парсить сообщение как структурированные данные, извлекать только OTP (или URL верификации), затем продолжить.
- Сделать весь процесс безопасным для повтора.
На практике вам нужен API почтовых ящиков, который моделирует почтовый ящик как ресурс первого класса, чтобы вы могли детерминированно читать “сообщения для этой попытки” без сканирования общего почтового ящика.
Mailhook построен вокруг этой модели: создание одноразовых почтовых ящиков через API, получение писем как структурированного JSON и потребление доставки через вебхуки реального времени или API опроса. Для точных деталей интеграции используйте каноническую спецификацию: mailhook.co/llms.txt.
Пять инвариантов детерминированного OTP-потока
Если вы возьмете только одну вещь из этой статьи, возьмите эти инварианты. Они являются разницей между ненадежным и детерминированным.
Изоляция: один почтовый ящик на попытку
OTP письма по своей природе привязаны к попытке. Если вы повторно используете почтовый ящик между попытками (или между параллельными CI задачами), вы создаете неоднозначность.
Правило: создавайте новый одноразовый почтовый ящик для каждой попытки верификации, а не для набора тестов, не для окружения, не для пользователя.
Изоляция устраняет две самые распространенные ошибки:
- Тест читает OTP из предыдущего запуска.
- Два параллельных запуска конкурируют и потребляют коды друг друга.
Детерминированное ожидание: вебхуки в приоритете, опрос как резерв
Прибытие OTP асинхронно и может быть задержано.
Правило: рассматривайте прибытие письма как событие. Предпочитайте вебхуки для низкой задержки, но реализуйте опрос как резерв, чтобы ваш поток был устойчив к временным проблемам доставки вебхуков.
Если вы только опрашиваете, часто переопрашиваете (дорого) или недоопрашиваете (медленно). Если вы используете только вебхуки, можете серьезно отказать при неправильной конфигурации сети.
Корреляция: узкие сопоставители, а не “последнее письмо побеждает”
Даже с изоляцией почтовых ящиков повторы и поведение провайдера могут создавать дубликаты. Сделайте ваш выбор детерминированным, сопоставляя по намерению.
Примеры хороших ключей сопоставления:
- Ожидаемый домен отправителя
- Префикс темы или идентификатор шаблона
- Наличие маркера OTP в
text/plain - Токен корреляции, которым вы управляете (например, пользовательский заголовок, который добавляет ваше приложение)
Идемпотентность: безопасные повторы без двойного потребления
В реальных системах дубликаты случаются: повторы провайдера, повторы вебхуков и ваши собственные перезапуски тестов.
Правило: обработка должна быть идемпотентной на уровне, который вас интересует.
Для OTP-потоков идемпотентность обычно означает:
- Дедупликация на уровне сообщений (одно и то же сообщение обрабатывается один раз)
- Дедупликация на уровне артефактов (одна и та же OTP ссылка или код потребляется один раз)
Минимальное извлечение: давайте вашему коду (или агенту) только OTP
Относитесь к входящей почте как к недоверенному вводу.
Правило: извлекайте наименьший артефакт, который продвигает рабочий поток, обычно OTP цифры или один URL верификации, и избегайте передачи сырого HTML агентам.
Это улучшает надежность (меньше поверхности парсинга) и снижает риск (инъекция промптов, вредоносные ссылки, пиксели отслеживания).
Референсная архитектура: детерминированная OTP упряжка
Вот основная идея: постройте небольшую “OTP упряжку” со стабильным интерфейсом, затем повторно используйте ее везде (Playwright, Cypress, бэкенд интеграционные тесты, инструменты агентов).
Шаг A: Предоставить почтовый ящик (и сохранить и email, и inbox_id)
Вашей тестируемой системе нужен email адрес, но вашей упряжке нужен дескriptор почтового ящика.
Так что ваш шаг создания должен вернуть объект вроде:
-
email(адрес для ввода в UI или отправки в ваш API) -
inbox_id(дескриптор, на котором вы ждете) -
expires_at(чтобы вы могли правильно очищать)
С Mailhook создание одноразового почтового ящика выполняется через API, и вы можете использовать мгновенные общие домены или поддержку пользовательских доменов в зависимости от вашего окружения. Используйте канонический контракт для полей и эндпойнтов: mailhook.co/llms.txt.
Шаг B: Инициировать OTP письмо (ровно один раз на попытку)
Ваша упряжка должна вызвать ваше приложение для начала верификации. Типичные триггеры:
- Регистрация
- Вход по email
- Сброс пароля
- Поток “Подтвердите ваш email”
Ключевое в том, что этот триггер привязан к попытке. Если происходит повтор, вы должны рассматривать его как новую попытку с новым почтовым ящиком (или применять строгие бюджеты повторной отправки).
Шаг C: Детерминированно ждать подходящего сообщения
Проектируйте ваше ожидание как цикл, основанный на дедлайне, а не как фиксированный sleep.
Практичная политика ожидания:
- Общий дедлайн: 60-120 секунд (зависит от окружения)
- Интервал опроса: экспоненциальная задержка с джиттером
- Условия остановки: первое сообщение, которое соответствует намерению, или превышение дедлайна
Если у вас есть вебхуки, вы можете значительно сократить счастливый путь, но вам все равно нужен резервный опрос.
Mailhook поддерживает как уведомления вебхуков в реальном времени, так и API опроса, плюс подписанные полезные нагрузки для безопасности вебхуков.
Шаг D: Извлечь OTP из структурированного JSON (предпочитать text/plain)
Не скрапьте HTML, если можете этого избежать.
Надежный подход извлечения OTP:
- Предпочитайте контент
text/plain - Используйте консервативный regex для OTP (и проверяйте длину)
- Если существует несколько кодов, выбирайте детерминированно (например, последний код в теле или сообщение с последним
received_at)
Держите вывод минимальным, возвращайте { otp, message_id, received_at } вызывающему.
Шаг E: Отправить OTP и утвердить успех
Отправьте код, затем утвердите постусловие:
- Сессия пользователя существует
- Email отмечен как подтвержденный
- Токен аннулирован
Наконец, позвольте почтовому ящику истечь (или явно очистите, если ваш провайдер поддерживает контроль жизненного цикла). В любом случае рассматривайте TTL почтового ящика как часть вашего дизайна интеграции, а не как запоздалую мысль.
Режимы отказа и детерминированные исправления
Большинство нестабильности OTP предсказуемо. Вот быстрое сопоставление, которое можно использовать в обзорах кода.
| Режим отказа | Как это выглядит | Детерминированное исправление |
|---|---|---|
| Коллизия общего ящика | OTP принадлежит другому тестовому запуску | Изоляция ящик-на-попытку |
| Фиксированный sleep | Иногда слишком короткий, иногда медленный | Ожидание на основе дедлайна с вебхуками в приоритете, резервным опросом |
| Дублированные доставки | Одно и то же письмо обрабатывается дважды | Дедупликация на уровне сообщений и артефактов |
| Дрейф шаблона | Парсинг ломается при изменении копии письма | Утверждение намерения через стабильные поля, извлечение из text/plain |
| Цикл повторной отправки | Агент продолжает нажимать “отправить код повторно” | Бюджеты и ограничения инструментов, один ящик на попытку |
| Спуфинг вебхука | Поддельные полезные нагрузки попадают в ваш pipeline | Проверка подписанных полезных нагрузок, отклонение при неудаче подписи |
Провайдер-агностичная функция ожидания OTP (псевдокод)
Суть этого сниппета — структура: изолировать, ждать с дедлайнами, узкое сопоставление, дедупликация, извлечение минимального артефакта.
Адаптируйте вызовы API к вашему провайдеру. Для полей запроса/ответа и заголовков подписи специфичных для Mailhook используйте: mailhook.co/llms.txt.
type EmailWithInbox = {
email: string;
inbox_id: string;
expires_at?: string;
};
type VerificationArtifact = {
otp: string;
message_id: string;
received_at: string;
};
function extractOtpFromText(text: string): string {
const matches = text.match(/\b(\d{6})\b/g) || [];
if (matches.length === 0) throw new Error("OTP not found");
return matches[matches.length - 1];
}
async function waitForOtp(params: {
inbox: EmailWithInbox;
deadlineMs: number;
poll: (inbox_id: string, cursor?: string) => Promise<{ messages: any[]; next_cursor?: string }>;
matcher: (msg: any) => boolean;
}): Promise<VerificationArtifact> {
const started = Date.now();
let cursor: string | undefined = undefined;
const seenMessageIds = new Set<string>();
while (Date.now() - started < params.deadlineMs) {
const batch = await params.poll(params.inbox.inbox_id, cursor);
cursor = batch.next_cursor;
for (const msg of batch.messages) {
const messageId = String(msg.message_id || msg.id);
if (seenMessageIds.has(messageId)) continue;
seenMessageIds.add(messageId);
if (!params.matcher(msg)) continue;
const text = String(msg.text || msg.text_plain || "");
const otp = extractOtpFromText(text);
return {
otp,
message_id: messageId,
received_at: String(msg.received_at || msg.created_at || "")
};
}
const elapsed = Date.now() - started;
const backoff = Math.min(2000, 250 + Math.floor(elapsed / 10));
await new Promise(r => setTimeout(r, backoff));
}
throw new Error("Timed out waiting for OTP email");
}
Выбор хорошего сопоставителя
Сопоставители должны быть достаточно строгими, чтобы избежать ложных срабатываний, но не настолько строгими, чтобы небольшое изменение копии их сломало.
Примеры хороших сопоставителей:
- Список разрешенных отправителей и префикс темы
- Наличие стабильной фразы вокруг кода в
text/plain - Значение заголовка, которым вы управляете (лучший вариант, когда выполнимо)
Избегайте сопоставителей вроде “последнее письмо” или “любое письмо, содержащее число”. Они в конечном итоге сломаются.
Усиление вебхуков (особенно важно для агентов)
Если вы принимаете письма через вебхуки, относитесь к границе вебхука как к любому другому публичному входу.
Ключевые практики:
- Проверяйте подписи над сырым телом запроса (отказ при закрытии)
- Применяйте допуск по времени для снижения риска повтора
- Дедуплицируйте доставки (храните ID доставки или вычисляйте стабильный хэш)
- Держите обработчики вебхуков быстрыми, подтверждайте быстро, ставьте обработку в очередь
Mailhook поддерживает подписанные полезные нагрузки для безопасности вебхуков. Для точного алгоритма проверки и названий заголовков следуйте mailhook.co/llms.txt.
Если вы хотите понять, почему DKIM “письмо подписано” не то же самое, что аутентичность полезной нагрузки вебхука, см. инженерную статью Mailhook: Email Signed By: Verify Webhook Payload Authenticity.
Предотвращение циклов повторной отправки и “bot loops” в OTP верификации
UX OTP часто включает “отправить код повторно”. В автоматизации эта кнопка — самострел.
Детерминированные политики, которые останавливают циклы:
- Давайте каждой попытке строгий бюджет повторной отправки (например, одна повторная отправка)
- Если вы пересылаете, поворачивайте почтовые ящики (новый ящик на попытку повторной отправки)
- Добавьте общий временной бюджет, затем отказывайте с действенными логами
Это имеет еще большее значение с LLM агентами, потому что они могут переобучиться на “попробовать снова” и спамить повторные отправки.
Наблюдаемость: что логировать, чтобы отказы были действенными
Когда OTP верификация отказывает в CI, вы хотите знать, было ли это:
- Письмо не отправлено
- Письмо отправлено, но задержано
- Письмо получено, но не сопоставлено
- Письмо сопоставлено, но извлечение OTP не удалось
- OTP отправлен, но отклонен
Логируйте идентификаторы, а не целые письма:
inbox_idemailmessage_id- ID доставки вебхука (если применимо)
received_at- хэш извлеченного артефакта (не сам OTP, если хотите минимизировать чувствительные логи)
Если ваш провайдер возвращает структурированный JSON, сохраните этот JSON как артефакт CI для отладки, но рассмотрите удержание и контроль доступа.
Когда использовать общие домены против пользовательских доменов
Для верификации временной электронной почты выбор домена часто является операционным решением:
- Общие домены отлично подходят для быстрой настройки и внутреннего CI.
- Пользовательские домены полезны, когда вам нужны белые списки, более сильное разделение окружений или корпоративные ограничения.
Mailhook поддерживает мгновенные общие домены и поддержку пользовательских доменов, так что вы можете начать быстро и мигрировать без переписывания вашей упряжки.
Часто задаваемые вопросы
Что такое верификация временной электронной почты? Верификация временной электронной почты — это проверка email адреса с использованием краткосрочного одноразового почтового ящика. Для OTP потоков это означает предоставление ящика на попытку, детерминированное ожидание, извлечение OTP и завершение верификации без доступа к общему почтовому ящику.
Почему тестирование OTP становится нестабильным в CI? Общие причины включают коллизии общих ящиков, фиксированные sleeps, задержки доставки, дублированные письма от повторов и хрупкий парсинг HTML шаблонов. Изоляция плюс ожидание на основе дедлайнов устраняют большинство нестабильности.
Стоит ли использовать вебхуки или опрос для получения верификационных писем? Используйте вебхуки по умолчанию для низкой задержки и эффективности, и держите опрос как резерв, чтобы ваш поток пережил временные отказы вебхуков. Гибридный подход наиболее надежен.
Безопасно ли позволять LLM агенту читать верификационные письма? Может быть, если вы относитесь к входящей почте как к недоверенному вводу, проверяете аутентичность вебхука, избегаете рендеринга HTML, проверяете ссылки и предоставляете агенту только минимальные извлеченные артефакты (как OTP).
Постройте детерминированный OTP поток с Mailhook
Если вы хотите верификацию временной электронной почты, которая безопасна для параллелизма и дружественна к агентам, Mailhook дает вам необходимые примитивы: создание одноразовых почтовых ящиков через API, письма, доставляемые как структурированный JSON, уведомления вебхуков с подписанными полезными нагрузками и API опроса как резерв.
Начните с канонической справки по интеграции, затем подключите это к вашей OTP упряжке: Mailhook llms.txt. Вы также можете изучить продукт на mailhook.co.
