API для временной почты: как устроена интеграция

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

Что такое API временной почты и зачем оно нужно

Временная (одноразовая, disposable) почта - это адрес, который существует короткое время, не требует регистрации и не привязан к личности владельца. Обычно им пользуются, чтобы не оставлять настоящий адрес на сомнительном сайте и не получать потом рассылки.

API превращает этот сценарий из ручного в автоматический. Вместо веб-интерфейса ваш код сам:

• создаёт новый почтовый ящик (или получает случайный адрес);
• ждёт входящее письмо;
• читает его тему, тело и вложения;
• удаляет ящик, когда он больше не нужен.

Для программиста это похоже на работу с очередью сообщений, где «очередь» - чей-то почтовый адрес, а «сообщение» - обычное письмо с кодом подтверждения или ссылкой.

Где это применяется на практике

Основные сценарии выглядят так:

1. Автоматизированное тестирование. Регистрация, сброс пароля, подтверждение email, уведомления - всё это завязано на почту. Без отдельного ящика на каждый прогон тесты либо ломаются о чужие письма, либо приходится городить общий ящик с ручной очисткой.
2. Приложения для приватности. Мобильные клиенты, браузерные расширения и боты, которые выдают пользователю одноразовый адрес.
3. QA и проверка рассылок. Проверить, как письмо выглядит и доходит, что в нём со ссылками, не попадает ли оно в спам.
4. Прототипы и демо. Когда нужно показать поток регистрации без реальных пользовательских данных.
5. Парсинг и мониторинг на легальных основаниях. Например, проверка собственных уведомлений: приходят ли они вообще и с какой задержкой.

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

Как устроен типичный API: общий принцип

Несмотря на различия между провайдерами, почти все REST API временной почты построены по одной схеме. Разберём её по шагам.

Шаг 1. Получить домен

Адрес состоит из локальной части и домена. Домены принадлежат провайдеру, и их список может меняться. Поэтому многие API предлагают отдельный запрос «какие домены сейчас доступны». Жёстко прописывать домен в коде не стоит: он может быть заблокирован целевым сервисом или выведен из обращения.

Шаг 2. Создать ящик

Есть два подхода:

• Генерация на стороне провайдера. Вы вызываете метод, и вам возвращают случайный адрес. Удобно для быстрых сценариев.
• Создание по вашим параметрам. Вы сами задаёте имя (и иногда пароль), провайдер регистрирует ящик. Удобно для тестов, где адрес должен быть предсказуемым: например, test-run-4812@домен.

Часто при создании ящика возвращается токен доступа, и дальше запросы к этому ящику подписываются им.

Шаг 3. Дождаться письма

Здесь есть три механизма:

• Polling (опрос). Код раз в несколько секунд запрашивает список писем. Просто, но создаёт лишнюю нагрузку и задержку.
• Long polling. Запрос висит, пока не придёт письмо или не истечёт таймаут. Эффективнее, но поддерживается не везде.
• Push: webhook или SSE/WebSocket. Провайдер сам сообщает о новом письме. Это самый быстрый вариант, но webhook требует публичного адреса вашего сервера, а значит, сложнее в локальной разработке и CI.

Шаг 4. Прочитать письмо

Метод получения письма обычно отдаёт тему, отправителя, текстовую и HTML-версии тела и список вложений. Для извлечения кода подтверждения или ссылки используют регулярные выражения или парсинг HTML.

Шаг 5. Очистка

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

Пример запроса: как это выглядит в коде

Ниже схематичный пример на JavaScript (Node.js 18+, где fetch встроен). Он повторяет логику публичного API Mail.tm, но имена полей и адреса могут отличаться у других провайдеров и со временем меняться, поэтому сверяйтесь с актуальной документацией.

const BASE = "https://api.mail.tm";

async function api(path, options = {}) {
  const res = await fetch(BASE + path, {
    ...options,
    headers: { "Content-Type": "application/json", ...(options.headers || {}) },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status} on ${path}`);
  return res.json();
}

async function getInbox() {
  // 1. Узнаём доступный домен
  const domains = await api("/domains");
  const domain = domains["hydra:member"][0].domain;

  // 2. Создаём ящик
  const address = `test${Date.now()}@${domain}`;
  const password = "temporary-password-123";
  await api("/accounts", {
    method: "POST",
    body: JSON.stringify({ address, password }),
  });

  // 3. Получаем токен
  const { token } = await api("/token", {
    method: "POST",
    body: JSON.stringify({ address, password }),
  });

  return { address, token };
}

async function waitForMessage(token, timeoutMs = 60000) {
  const started = Date.now();
  while (Date.now() - started < timeoutMs) {
    const list = await api("/messages", {
      headers: { Authorization: `Bearer ${token}` },
    });
    const items = list["hydra:member"];
    if (items.length > 0) return items[0];
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error("Письмо не пришло за отведённое время");
}

Что здесь важно с инженерной точки зрения:

• Таймаут обязателен. Без него тест зависнет навсегда, если письмо не придёт.
• Пауза между опросами. Три секунды - разумный компромисс; слишком частые запросы можно упереться в rate limit.
• Уникальность адреса. Метка времени в имени защищает от коллизий при параллельных прогонах.

Какие бывают варианты: сравнение подходов

Условно все решения делятся на три группы. Конкретные цены и лимиты у провайдеров меняются, поэтому в таблице их нет - проверяйте на официальных сайтах.

Выбирать по этой таблице надо не «что лучше», а «что подходит под ваш риск». Для личного скрипта хватит публичного сервиса. Для CI в компании, где тесты запускаются десятки раз в день, лучше платформа с гарантиями или собственная песочница.

Отдельно о песочницах вроде Mailpit

Этот вариант принципиально отличается от остальных: письма не выходят в интернет вообще. Ваше приложение отправляет почту на локальный SMTP-сервер, а тест читает её через HTTP API песочницы. Для проверки собственных уведомлений это идеальный вариант: нет зависимости от сторонних доменов, нет задержек доставки, нет блокировок. Минус один: вы не проверяете реальную доставку через внешний SMTP-провайдер, а только то, что письмо сформировано правильно.

Как выбрать: критерии

Перед выбором ответьте себе на несколько вопросов:

• Что именно тестируется? Формирование письма или реальная доставка через интернет? От этого зависит, нужна ли песочница или внешний сервис.
• Принимает ли целевой сервис такие домены? Многие сайты блокируют регистрацию с известных одноразовых доменов. Для собственных продуктов эту проблему решает отдельный тестовый домен, который вы контролируете.
• Насколько критична приватность содержимого? Если в письмах есть персональные данные пользователей, публичные ящики недопустимы: их может прочитать любой, кто угадает адрес.
• Какой нужен объём? Сотни писем в день - это уже вопрос лимитов и тарифа.
• Как быстро нужно получать письмо? Для автотестов задержка в минуту может быть неприемлемой, поэтому стоит смотреть на поддержку push-уведомлений.
• Что со вложениями и HTML? Не все API отдают вложения или полную HTML-версию.
• Насколько хорошая документация и стабильна ли схема API? Это сильно влияет на стоимость поддержки интеграции.

Два мини-кейса

Кейс 1. Автотест регистрации в интернет-магазине

Команда разрабатывает интернет-магазин. Пользователь регистрируется, получает письмо со ссылкой подтверждения, переходит по ней и только после этого может оформить заказ. Раньше тестировщик делал это вручную перед каждым релизом.

Автоматизация выглядит так:

1. Тест вызывает API и создаёт ящик с уникальным именем.
2. Через браузерный драйвер заполняется форма регистрации с этим адресом.
3. Тест ждёт письмо с таймаутом 60 секунд.
4. Из HTML письма регулярным выражением извлекается ссылка подтверждения.
5. Драйвер переходит по ссылке и проверяет, что аккаунт активирован.
6. Ящик удаляется.

Типичные проблемы, с которыми столкнётся команда:

• Письмо приходит позже таймаута из-за очереди на стороне почтового сервиса магазина. Решение: увеличить таймаут и логировать время отправки и получения, чтобы понимать реальную задержку.
• Параллельные прогоны в CI путаются между собой. Решение: включать в адрес идентификатор сборки.
• При смене вёрстки письма ломается регулярное выражение. Решение: добавить в письмо стабильный атрибут, например data-testid на ссылку, и искать её по нему.

В этом сценарии удобнее всего коммерческая платформа или собственный домен с catch-all: домен подконтролен команде, и магазин не блокирует собственные адреса.

Кейс 2. Расширение браузера с одноразовым адресом

Разработчик пишет расширение, которое по клику вставляет в поле формы временный адрес и показывает входящие письма во всплывающем окне.

Что здесь нужно продумать:

• Время жизни адреса. Пользователь ожидает, что письмо с кодом придёт за минуту-две, но может вернуться к адресу через час. Нужно заранее решить, сколько хранить ящик, и объяснить это в интерфейсе.
• Безопасность. Токен ящика не стоит хранить дольше необходимого. А содержимое писем - показывать с осторожностью: HTML из письма может содержать скрипты и трекинговые пиксели, поэтому его нужно отображать в изолированном контейнере (sandbox iframe) или предварительно очищать.
• Зависимость от провайдера. Если расширение построено на одном публичном API и тот закроется или изменит схему, продукт перестанет работать. Разумно с самого начала закладывать абстракцию над провайдером, чтобы можно было переключиться.
• Приватность пользователя. Если расширение отправляет адрес и письма через ваш сервер-посредник, вы начинаете обрабатывать чужие данные и отвечать за них.

Нюансы, ограничения и спорные моменты

Блокировка одноразовых доменов

Многие сервисы сверяют домен регистрации со списками известных временных почт и отказывают. Это обычная практика антифрода. Поэтому адрес из публичного API не гарантирует, что регистрация пройдёт. Если вы тестируете чужой сервис, это может быть непреодолимой преградой; если свой, проблема решается белым списком тестовых доменов.

Публичные ящики не приватны

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

Нестабильность бесплатных API

У бесплатных публичных сервисов нет обязательств. Они могут ограничить частоту запросов, поменять формат ответа, сменить домены или закрыться. Для разовых скриптов это нормально, для продакшена - нет.

Правовые и этические рамки

Отдельно о том, о чём лучше помнить сразу:

• Правила целевого сервиса. Автоматическая регистрация аккаунтов обычно нарушает условия использования. Если ваш тест создаёт аккаунты на чужом сайте, это может закончиться блокировкой, а в отдельных случаях и претензиями.
• Персональные данные. Если в тестовых письмах окажутся реальные данные пользователей, а ящик публичный, это утечка. В российском контексте это затрагивает требования 152-ФЗ «О персональных данных», в европейском - GDPR. На тестовых контурах лучше использовать синтетические данные.
• Использование для злоупотреблений. Спам, накрутка отзывов и голосований, обход банов - это именно те сценарии, из-за которых одноразовые домены блокируют повсеместно. Законные применения от этого страдают.

Доставляемость и задержки

Письмо не обязано приходить мгновенно. Серые списки, очереди у отправителя, антиспам-фильтры на стороне получателя - всё это добавляет задержку. В тестах нельзя закладываться на фиксированную паузу («подождать пять секунд»): нужен опрос с таймаутом.

Спорный вопрос: нужна ли вообще временная почта в тестах

Часть команд считает, что для собственного продукта внешний сервис не нужен: достаточно песочницы вроде Mailpit, а тестовая отправка через мок SMTP. Другие настаивают, что без проверки реальной доставки есть риск пропустить проблемы с настройкой DNS, SPF, DKIM и репутацией отправителя. Оба подхода обоснованы, и на практике их часто комбинируют: быстрые тесты на песочнице при каждом коммите и редкие сквозные проверки с реальной доставкой перед релизом.

Практический чек-лист перед запуском интеграции

• Определено, зачем нужна временная почта и какой сценарий вы покрываете.
• Выбран тип провайдера под требования к приватности и стабильности.
• Домен не прописан в коде жёстко, список берётся из API или конфигурации.
• Для каждого прогона создаётся уникальный адрес.
• Установлен таймаут ожидания письма и пауза между опросами.
• HTML писем не исполняется в основном контексте приложения.
• Ящики удаляются после использования.
• Учтены лимиты запросов и обработка ошибок 429 и 5xx с повторными попытками.
• Обработан сценарий, когда провайдер недоступен.
• В тестах нет реальных персональных данных.

Частые вопросы

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

Да, есть публичные сервисы с бесплатным доступом, например Mail.tm и Guerrilla Mail. Но у бесплатных вариантов есть лимиты на частоту запросов, а условия могут меняться без предупреждения. Перед использованием проверьте актуальную документацию и правила провайдера.

Можно ли использовать временную почту для автотестов?

Можно, и это один из самых распространённых сценариев. Для регулярных тестов в команде лучше брать коммерческую платформу или собственную песочницу, чтобы не зависеть от стабильности бесплатного сервиса и не рисковать блокировкой домена.

Безопасно ли получать письма с кодами через публичный API?

Для некритичных тестовых аккаунтов - допустимо. Но в большинстве публичных сервисов письма доступны любому, кто знает адрес, поэтому для важных аккаунтов и данных пользователей такой способ небезопасен.

Почему сайт не принимает адрес временной почты?

Многие сервисы блокируют известные одноразовые домены, чтобы бороться со злоупотреблениями. Если вы тестируете собственный продукт, добавьте тестовый домен в разрешённые. Если чужой, обойти это ограничение корректно не получится, и пытаться его обходить не стоит.

Чем временная почта через API отличается от Mailpit и MailHog?

Сервисы временной почты принимают письма из интернета на публичных или подконтрольных провайдеру доменах. Mailpit и MailHog работают как локальная SMTP-песочница: они перехватывают письма вашего приложения и никуда не отправляют. Первое подходит для проверки реальной доставки, второе - для быстрой проверки содержимого писем без внешних зависимостей.

Итоги

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

Если вы только начинаете, возьмите публичный API и повторите пример из статьи на тестовом аккаунте, чтобы понять поток данных. Если задача серьёзнее, сначала определите, что вы проверяете: реальную доставку или только содержимое письма. От этого зависит, нужен ли внешний сервис, коммерческая платформа или локальная песочница.