API временной почты: получение и парсинг писем в формате JSON

Электронная почта — упрямая зависимость в автоматизации. Она приходит с опозданием, происходят дубликаты, HTML-шаблоны меняются, а граничные случаи MIME незаметно ломают парсеры. API временной почты решает проблему инфраструктуры, предоставляя одноразовые почтовые ящики по запросу, и решает проблему интеграции, доставляя каждое сообщение как структурированный JSON, чтобы ваши тесты и AI-агенты обрабатывали почту как данные, а не как веб-страницу.

Это руководство объясняет, как должно выглядеть «получение и парсинг писем в формате JSON» на практике, как выбирать между доставкой через вебхуки и поллинг, и как безопасно извлекать одноразовые пароли и магические ссылки.

Что такое API временной почты (и что он должен делать)

API временной почты — это дружественный к автоматизации способ программно создавать почтовые ящики, получать входящую почту для этих ящиков и обрабатывать сообщения из кода.

Для QA и агентских рабочих процессов выигрышная модель — сначала почтовый ящик:

• Вы создаёте свежий почтовый ящик на каждый запуск или попытку.
• Вы получаете обратно маршрутизируемый email-адрес плюс хендл почтового ящика (часто inbox_id).
• Вы ожидаете сообщения детерминированно (сначала вебхуки, поллинг как резерв).
• Вы парсите сообщение как JSON и извлекаете минимальный артефакт (одноразовый пароль, URL подтверждения).
• Вы удаляете или ротируете почтовый ящик.

Последний пункт важен: недолговечные почтовые ящики уменьшают коллизии между тестами и ограничивают радиус поражения, если что-то утечёт.

«Получение писем как JSON» означает стабильный контракт, а не парсинг по принципу «как получится»

Электронная почта определяется стандартами, такими как RFC 5322 и MIME (RFC 2045), но реальная почта часто содержит:

• Дублированные или свёрнутые заголовки
• Многочастные тела с text/plain и text/html
• Странные кодировки
• Вложения и встроенные ресурсы
• Заголовки цепочек, которые присутствуют, отсутствуют или неправильно сформированы

Провайдер, возвращающий JSON, должен нормализовать эти детали в контракт, на который вы можете положиться. При оценке любого API временной почты спросите, достаточно ли стабилен JSON-вывод, чтобы писать против него утверждения.

Рекомендуемые JSON-поля для автоматизации и агентов

Практичный JSON-payload обычно нуждается в:

JSON-поле (концепция)	Почему это важно	Заметки для надёжности
message_id (ID провайдера)	Стабильный идентификатор для идемпотентности	Не полагайтесь только на Subject или From
received_at	Детерминированные временные бюджеты	Предпочтите серверное время получения vs клиентскую оценку
to, from	Маршрутизация и корреляция	Нормализуйте регистр и форматирование адресов
subject	Отладка и нестрогое сопоставление	Полезно, но не заслуживает доверия для строгого сопоставления
headers (нормализованные)	Криминалистика и корреляция	Обрабатывайте дубликаты и свёрнутые заголовки
text (простой)	Безопасная, стабильная цель парсинга	Предпочтите text/plain для извлечения
html (опционально)	Человеческий осмотр, резерв	Рассматривайте как недоверенный ввод
attachments (метаданные + получение)	Рабочие процессы, которые отправляют файлы по почте	Делайте обработку вложений явной
raw (опционально)	Отладка и повторная обработка	Помогает, когда шаблоны меняются

Если вы строите инструменты для LLM, рассмотрите возможность предоставления минимизированного представления модели (например: from, to, subject, received_at, text и небольшой набор извлечённых артефактов) и держите raw или HTML вне контекста агента, если это действительно не нужно.

Паттерны доставки: вебхуки против поллинга (и почему большинству команд нужны оба)

Есть два способа получать сообщения от API временной почты:

Вебхуки (push)

Вебхуки управляются событиями: провайдер вызывает ваш эндпоинт, когда приходит сообщение.

Они идеальны, когда:

• Вам нужна низкая задержка
• Вы хотите меньше API-вызовов
• Вы запускаете много параллельных почтовых ящиков и хотите поток событий

Операционно вебхуки требуют от вас размышлений о повторных попытках, проверке подписи и идемпотентной обработке.

Поллинг (pull)

Поллинг проще в развёртывании: ваш код повторно спрашивает API, пришли ли сообщения.

Он полезен, когда:

• Ваша среда не может принимать входящие веб-запросы (некоторые настройки CI)
• Вы хотите сначала простую реализацию
• Вам нужен резервный путь, когда вебхуки задерживаются или блокируются

Поллинг должен быть тщательно спроектирован, чтобы избежать фиксированных задержек, пропущенных сообщений и дублированной обработки.

Рекомендуемый гибридный подход

В production-автоматизации наиболее надёжный подход:

• Сначала вебхуки для быстрой доставки
• Поллинг как резерв для восстановления (если ваш вебхук-эндпоинт был недоступен, если произошёл деплой, или если уведомление было потеряно)

Вот быстрое сравнение:

Механизм	Сильная сторона	Частая ошибка	Исправление
Вебхук	Быстро, масштабируемо	Повторы, подделка, повторные попытки	Проверяйте подписи, обеспечивайте идемпотентность
Поллинг	Просто, дружелюбно к файрволлам	Лимиты скорости, фиксированные задержки, дубликаты	Откат, курсоры, просмотренные ID
Гибридный	Наиболее надёжный	Больше движущихся частей	Держите единый контракт «ждать сообщение»

Как безопасно парсить письма как JSON (особенно для LLM-агентов)

Даже когда провайдер даёт вам JSON, содержимое email всё ещё недоверенный ввод. JSON-формат просто упрощает применение последовательных правил.

Предпочитайте text/plain для детерминированного извлечения

Для потоков одноразовых паролей и подтверждения text/plain обычно меняется реже, чем HTML, и избегает связанных с разметкой ошибок парсинга.

Если вы должны прибегнуть к HTML, делайте это с явными предохранителями:

• Не рендерьте HTML в инструменте агента
• Удаляйте теги и декодируйте сущности перед поиском
• Избегайте автоматического «нажатия» ссылок

Извлекайте минимальные артефакты, а не «смысл»

Для автоматизации вам обычно нужен один из этих артефактов:

• Числовой одноразовый пароль
• URL подтверждения (магическая ссылка)
• Ссылка сброса пароля

Цель — минимальное детерминированное извлечение, а не суммаризация.

Простая политика извлечения:

• Принимайте максимум одного кандидата на одноразовый пароль, соответствующего вашему формату
• Принимайте максимум одного кандидата URL, соответствующего разрешённому домену и ожидаемому префиксу пути
• Если есть несколько кандидатов, падайте с объяснимой ошибкой и логируйте ID сообщений

Валидируйте ссылки перед их использованием (гигиена SSRF и открытых редиректов)

Если ваша автоматизация следует URL из email, рассматривайте это как границу безопасности:

• Составьте whitelist доменов, которые вы контролируете
• Отклоняйте IP-литералы и назначения частных сетей
• Не следуйте неограниченным цепочкам редиректов

OWASP SSRF Prevention Cheat Sheet — полезная основа для безопасности следования ссылкам.

Правила детерминизма для CI и агентских рабочих процессов

Большинство нестабильных email-тестов падают по предсказуемым причинам: коллизии общих почтовых ящиков, наивные задержки и слабое сопоставление.

Используйте модель почтового ящика на попытку

Если вы переиспользуете почтовые ящики между запусками, в конечном итоге вы прочтёте неправильный email. Чистое исправление: создавайте одноразовый почтовый ящик на попытку (или хотя бы на запуск) и рассматривайте его inbox_id как свою область.

Добавьте корреляцию, которую вы контролируете

Делайте сопоставление узким и объяснимым:

• Включайте идентификатор запуска в действие, которое запускает email (например: уникальный email-адрес регистрации на запуск, или токен корреляции в метаданных, которые ваша система повторяет)
• Предпочитайте стабильные идентификаторы из JSON-payload нечёткому сопоставлению subject

Проектируйте идемпотентность заранее

Предполагайте, что дубликаты случатся:

• Вебхуки могут повторяться
• Поллинг может возвращать одно и то же сообщение несколько раз
• Ваш собственный job runner может перезапуститься

Используйте стабильный ключ, такой как inbox_id + message_id (и иногда хеш извлечённого артефакта), чтобы обеспечить обработку одного и того же логического email один раз.

Пакетная обработка для масштаба

Если вы принимаете много почты (нагрузочные тесты, большие QA-наборы или флоты агентов), пакетное извлечение и обработка уменьшает накладные расходы и делает ваш пайплайн более предсказуемым.

Минимальный пример интеграции (псевдокод, независимый от провайдера)

Ниже представлена справочная форма, которая хорошо работает как для QA-связок, так и для LLM-инструментов.

Создание почтового ящика

// Псевдокод, смотрите документы вашего провайдера для точных эндпоинтов
const inbox = await emailApi.createInbox({
  // опционально: стратегия домена, URL вебхука, метаданные
});

// Используйте inbox.email при регистрации, создании пользователей или запуске рабочего процесса

Ожидание сообщения (гибридный подход)

async function waitForMessage({ inboxId, timeoutMs }) {
  const deadline = Date.now() + timeoutMs;

  // Предпочтите вебхук в реальных системах, но держите поллинг как резерв.
  // Эта функция представляет единый контракт: «верните первое подходящее сообщение или истечение времени».

  while (Date.now() < deadline) {
    const messages = await emailApi.listMessages({ inboxId });

    const candidate = pickBestCandidate(messages);
    if (candidate) return candidate;

    await sleep(backoffMs());
  }

  throw new Error(`Истекло время ожидания email для почтового ящика ${inboxId}`);
}

Извлечение одноразового пароля или магической ссылки из JSON

function extractArtifact(messageJson) {
  const text = messageJson.text ?? "";

  const otp = text.match(/\b\d{6}\b/)?.[0];
  if (otp) return { type: "otp", value: otp };

  const url = findFirstAllowlistedUrl(text, {
    allowlistDomains: ["example.com"],
  });
  if (url) return { type: "url", value: url };

  throw new Error(`Не найден одноразовый пароль или разрешённый URL в сообщении ${messageJson.message_id}`);
}

Важная часть — не regex, а контракт: ждите детерминированно, парсите JSON, извлекайте минимально, падайте громко, когда неоднозначно.

Реализация с Mailhook

Mailhook построен вокруг именно этой модели автоматизации:

• Создание одноразовых почтовых ящиков через API
• Получение писем как структурированного JSON
• Уведомления вебхуков в реальном времени (с подписанными payload)
• API поллинга для резерва
• Общие домены для мгновенной настройки и поддержка пользовательских доменов
• Пакетная обработка email

Для канонических, машиночитаемых деталей интеграции (эндпоинты, формы payload, специфика проверки подписи) используйте llms.txt справочник Mailhook: Mailhook llms.txt.

Вы также можете изучить продукт на Mailhook.

Чек-лист оценки API временной почты (быстрый тест на вменяемость)

Используйте это для сравнения провайдеров, не теряясь в маркетинге:

• Можете ли вы создавать почтовые ящики программно и изолировать их по запускам?
• Приходят ли сообщения как нормализованный JSON со стабильными ID и временными метками?
• Поддерживаются ли вебхуки, и подписаны ли payload?
• Доступен ли поллинг как резерв с семантикой, избегающей дубликатов?
• Можете ли вы выбирать между общими доменами и пользовательскими доменами?
• Поддерживается ли пакетная обработка, если вам нужна пропускная способность?
• Можете ли вы сохранять сырой исходник для отладки, не заставляя агентов читать сырой HTML?

Часто задаваемые вопросы

Что такое API временной почты? API временной почты позволяет создавать одноразовые почтовые ящики через API, получать входящую почту для этих ящиков и извлекать сообщения из кода (часто как JSON).

Почему мне следует парсить письма как JSON вместо скрапинга HTML? JSON делает payload электронной почты стабильным и машиночитаемым. Скрапинг HTML хрупкий, небезопасный для агентов и ломается при изменении шаблонов.

Должен ли я использовать вебхуки или поллинг для получения писем? Используйте вебхуки для низкой задержки и масштаба, и держите поллинг как резерв для надёжности. Гибридный паттерн «сначала вебхуки, поллинг как резерв» наиболее надёжен.

Как безопасно извлекать одноразовые пароли или ссылки подтверждения из email? Предпочитайте text/plain, извлекайте минимальный артефакт детерминированно (один одноразовый пароль или один URL из whitelist), и валидируйте ссылки перед их выполнением.

Как предотвратить дубликаты в потоках вебхуков и поллинга? Рассматривайте email как поток событий at-least-once. Дедуплицируйте, используя стабильные ключи, такие как inbox_id + message_id, и делайте обработчики идемпотентными.

Попробуйте Mailhook для JSON-первой автоматизации email

Если вам нужен API временной почты, который подходит LLM-агентам и QA-автоматизации, Mailhook предоставляет одноразовые почтовые ящики через API и доставляет входящие сообщения как структурированный JSON с вебхуками (подписанные payload) и поллинг-резервом.

Получите точный контракт интеграции здесь: Mailhook llms.txt, затем начните на mailhook.co (кредитная карта не требуется).