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

Обзор

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

• Каждый ответ — это JSON, включая любую ошибку.
• Всё время указано в UTC в формате RFC 3339 — 2026-08-04T18:31:07Z.
• ID сообщений — непрозрачные строки. Не разбирайте их.
• Только приём. Эндпоинта для отправки почты нет — так и задумано.

Базовый URL

Только HTTPS; обычный HTTP перенаправляется. Версия указана в пути, и v1 не изменит свою форму у вас под ногами — для несовместимого изменения будет использован новый номер.

Аутентификация

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

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

Authorization: Bearer <your key>

Неверный или отсутствующий ключ на приватном домене даёт ответ 401 с кодом unauthorized. Ключи сравниваются за постоянное время, поэтому неверный ключ отклоняется столько же, сколько занимает подтверждение верного.

Эндпоинты

$ curl -G https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=k7fq2m@grabmail.io"

{
  "address": "k7fq2m@grabmail.io",
  "count": 1,
  "next": null,
  "messages": [
    {
      "id":          "01JR8W2K4Q",
      "from":        "no-reply@example.com",
      "subject":     "Your verification code",
      "date":        "2026-08-04T18:31:07Z",
      "seen":        false,
      "attachments": 0,
      "expires_at":  "2026-08-09T18:31:07Z"
    }
  ]
}

$ curl -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "id":      "01JR8W2K4Q",
  "from":    "no-reply@example.com",
  "to":      "k7fq2m@grabmail.io",
  "subject": "Your verification code",
  "date":    "2026-08-04T18:31:07Z",
  "text":    "Your code is 481920. It expires in 10 minutes.",
  "html":    null,
  "attachments": []
}

$ curl -X DELETE -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "deleted": true,
  "id": "01JR8W2K4Q"
}

Вложения

У каждого письма есть список вложений с готовыми URL. Загружайте вложение с той же авторизацией, что и само письмо.

GET /api/v1/attachment/{id}?mailbox={address}

Ответ всегда приходит как application/octet-stream с заголовком Content-Disposition: attachment, независимо от того, что указал отправитель. Это сделано намеренно: вернуть чужой text/html как есть означало бы позволить вложению исполниться как странице на этом источнике. Настоящий тип указан в JSON письма — там это данные, а не команда.

Ошибки

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

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":   "invalid_address",
  "message": "address must look like name@domain"
}

Никогда не принимайте решения по message. Используемые коды — invalid_address, unknown_domain, not_found и rate_limited.

Лимиты запросов

Один запрос в секунду на адрес. Опрашивать ящик раз в секунду — предусмотренный режим, и он никогда не ограничивается.

При превышении лимита вы получаете 429 с заголовком Retry-After в секундах. Дневной квоты и запаса на всплеск нет — управлять нечем.

Срок хранения

Письмо удаляется через 5 дней после получения — прочитано оно или нет. У каждого письма есть поле expires_at, так что вычислять эту дату самостоятельно не нужно.

Это жёсткий предел, а не настройка — никакой параметр его не продлевает. Если письмо должно пережить это окно, заберите его и сохраните на своей стороне.

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

Направьте свою MX-запись на smtp.grabmail.io, и каждый адрес на вашем домене начнёт отвечать через эти же эндпоинты — учить второй API не нужно, а прочитать ящики можно только вашим ключом.

Подключить домен →