Быстрый старт

От нуля до сообщения, прочитанного через HTTP, за четыре команды. Без аккаунта, без ключа, без SDK.

1. Выберите адрес

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

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

shell

$ ADDR="ci-$(openssl rand -hex 4)@grabmail.io"; echo "$ADDR"

2. Отправьте на него что-нибудь

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

Наши почтовые серверы принимают сообщения размером до 5 MB. Всё, что больше, отклоняется ещё на этапе SMTP, так что отправитель узнаёт об этом сразу, а не остаётся в неведении.

shell

$ curl -sX POST https://your-app.example/signup --data-urlencode "email=$ADDR"

3. Опрашивайте ящик

Один запрос в секунду — предусмотренный ритм, и он никогда не ограничивается. Пустой ящик отвечает 200 с count: 0 — никогда 404, так что вашему циклу не нужно обрабатывать этот случай отдельно.

Этот фрагмент сдаётся через минуту, а не крутится бесконечно — это то, что нужно в CI.

опрашивайте, пока оно не придёт

$ for i in $(seq 60); do
  ID=$(curl -sG https://grabmail.io/api/v1/mailbox --data-urlencode "address=$ADDR" | jq -r '.messages[0].id // empty')
  [ -n "$ID" ] && break
  sleep 1
done; echo "$ID"

4. Прочитайте и выбросьте

Заберите письмо и извлеките то, за чем пришли — здесь это шестизначный код из текстовой части.

Удалять необязательно: всё удалится само через 5 дней. В CI делайте это в любом случае, тогда следующий запуск начнётся с чистого ящика.

чтение и удаление

$ curl -sG https://grabmail.io/api/v1/message/$ID --data-urlencode "mailbox=$ADDR" \
  | jq -r .text | grep -oE '[0-9]{6}'

curl -sX DELETE -G https://grabmail.io/api/v1/message/$ID --data-urlencode "mailbox=$ADDR"

Подключение к CI

Две привычки не дают набору тестов, читающему настоящую почту, стать нестабильным:

Новый адрес на каждый запуск: Формируйте его из идентификатора сборки или случайного суффикса. Повторное использование одного адреса между прогонами означает, что вчерашнее письмо может пройти сегодняшнюю проверку.
Крайний срок, а не счётчик попыток: Опрашивайте с таймаутом по настенным часам, как описано выше. При замедлении отправителя число повторов незаметно растёт.
Никогда не полагайтесь на время доставки: Почта приходит не синхронно. Проверяйте, что сообщение приходит, а не что оно приходит в конкретную секунду.
Используйте собственный домен для чего-то реального: Публичный почтовый ящик доступен для чтения любому, кто угадает адрес. Это нормально для одноразовой регистрации и не годится для тестового окружения с данными клиентов. Одна MX-запись решает проблему.

Для ИИ-агентов: MCP

Агент не может прочитать эту страницу, выбрать нужный эндпоинт и составить запрос. Он спрашивает у сервера, какие инструменты существуют, и вызывает их. grabmail запускает для этого сервер Model Context Protocol по адресу https://grabmail.io/mcp — без ключа, без аккаунта.

Направьте любой MCP-клиент на этот эндпоинт. Claude Desktop, Cursor, Continue и OpenAI Agents SDK — все понимают эту форму.

Шесть инструментов: create_inbox, list_domains, list_messages, read_message, delete_message и wait_for_message.

mcp.json

$ {"mcpServers":{"grabmail":{"url":"https://grabmail.io/mcp"}}}

Главное — это wait_for_message. Агенту нужен одноразовый ящик почти всегда из-за кода подтверждения, стоящего между ним и следующим шагом. Вместо цикла опроса, который тратит токены, он запрашивает адрес, отправляет форму и блокируется, пока не придёт письмо:

Ждёт до 25 секунд и возвращает письмо целиком — отправителя, тему, тело — либо сообщает о тайм-ауте, чтобы агент мог просто вызвать инструмент снова.

Можно также ждать конкретное письмо: передайте subject_contains или from_contains, и всё остальное, что придёт, будет проигнорировано.

MCP · wait_for_message

$ curl -sX POST https://grabmail.io/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"wait_for_message","arguments":{"address":"you@grabmail.io","subject_contains":"code"}}}'

Есть также спецификация OpenAPI 3.1 (YAML) для генераторов кода и llms.txt для всего, что предпочитает читать обычный текст.

Справочник по API

Каждый параметр, каждый код состояния, форма ошибки.

Открыть справочник →

Лимиты

Что ограничено, что нет и что происходит при достижении предела.

Открыть лимиты →

Собственный домен

Сделайте каждый ящик на своём домене приватным только для себя.

Смотреть настройку →