Документация API

API GPTMail

Используйте GPTMail API, чтобы создавать временные почтовые ящики, получать списки писем, читать и удалять письма по HTTPS с заголовком X-API-Key. API подходит для автоматизированных тестов, CI/CD-конвейеров и QA-процессов.

Как получить API Key

Buy API requests

Purchase API requests with GPTMail points. Earn points through daily check-ins and public domains, or buy points with LDC at a 1:1 rate.

Buy with points / add requests

Вариант 2: добавить свой домен

После проверки MX публичного домена: отправлен без входа в аккаунт → ключ API (20000 запросов); отправлен после входа → 200 баллов. Каждый домен получает только одну награду. Важно: после подключения этот суффикс домена становится публичным для всех пользователей сайта, и другие тоже смогут создавать адреса на нём. После активации не удаляйте, не заменяйте и не меняйте MX-запись, указывающую домен на наш сервис. Иначе при последующих проверках домен могут сочесть настроенным неверно. Если при проверке MX окажется недействительным, домен будет отключён. Если MX останется недействительным при 3 проверках подряд, связанная API Key тоже будет отключена. Если MX снова станет действительным, домен автоматически включат снова.

Домены

Публичный ключ для тестирования

Для тестирования передавайте общий публичный ключ, показанный ниже, в заголовке X-API-Key. Он меняется каждый день, и для него действует дневной лимит в 200 000 запросов, общий для всех пользователей.

Осталось сегодня

Сброс через

Загрузка актуальной квоты для публичного ключа…

Справочник API ниже можно скопировать как Markdown для ИИ-инструментов, баз знаний или README.

Базовый URL: https://mail.chatgpt.org.uk

AI
llms.txt

·

llms-full.txt

(Markdown)

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

  • X-API-Key: YOUR_KEY — самый простой вариант. Для быстрых тестов подставьте вместо YOUR_KEY ежедневный публичный ключ, показанный выше.

  • Для большинства endpoint’ов ящика нужен параметр email, например ?email=demo@example.com.

  • Ответы GPTMail API используют JSON с полями success, data и error, а также usage, если используется API-ключ. Ошибки Cloudflare, включая ответы об ограничении частоты запросов, могут вместо этого возвращать HTML. Перед разбором JSON проверяйте HTTP-статус и Content-Type.

  • Если вы уже знаете поддерживаемый на этом сайте домен, не обязательно сначала вызывать endpoint создания адреса. Соберите prefix@domain локально и сразу вызывайте API ящика — это экономит один запрос.

Ограничения частоты запросов и повторные попытки

  • GET и POST /api/generate-email имеют общий лимит 30 запросов за 10 секунд на один IP-адрес источника. Это относится как к публичным, так и к личным API-ключам. Разные ключи и клиенты за одним IP-адресом делят этот лимит.

  • При превышении этого лимита возвращается HTTP 429, и создание адресов блокируется на 10 секунд. Перед повторной попыткой подождите время, указанное в Retry-After. Если этого заголовка нет, подождите не менее 10 секунд, а затем повторяйте попытки с увеличивающейся задержкой. Избегайте одновременных повторных попыток от клиентов с общим IP-адресом.

  • Это правило не распространяется на получение списка писем или чтение отдельных писем. Дневные и общие квоты API-ключей по-прежнему действуют независимо. Ожидание 10 секунд не восстанавливает исчерпанную квоту ключа.

Основные endpoints

POST / GET
/api/generate-email

Создаёт временный почтовый ящик. Используйте GET для самого простого случайного сценария или POST с prefix и domain, когда нужен явный контроль.

GET
/api/emails?email=...

Получает письма для ящика.

GET
/api/email/{id}?email=...

Получает одно письмо: текст, HTML, сырые заголовки и метаданные.

DELETE
/api/email/{id}?email=...

Удаляет одно письмо по ID.

DELETE
/api/emails/clear?email=...

Удаляет все письма в ящике.

GET
/api/stats

Читает статистику по всему сайту.

Пример сценария

Два распространённых варианта: пусть сервис создаст ящик или запросите фиксированный префикс. Если вы уже знаете поддерживаемый домен, можно собрать адрес локально и сразу обращаться к API.

1) Сгенерировать случайный временный email-адрес

curl 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Пример ответа
{
  "success": true,
  "data": {
    "email": "a3f9c2b1@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

2) Сгенерировать с фиксированным префиксом (напр. demo@example.com)

curl -X POST 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: PUBLIC_API_KEY' \
  -d '{"prefix":"demo"}'
Пример ответа
{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 2,
    "remaining_today": 199998
  }
}

3) Список писем во входящих

Если домен уже известен и поддерживается, пропустите шаг 1 и запрашивайте сразу.

curl 'https://mail.chatgpt.org.uk/api/emails?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Пример ответа
{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "e5a7f3...",
        "email_address": "demo@example.com",
        "from_address": "noreply@github.com",
        "subject": "Your code: 654321",
        "content": "Your verification code is 654321",
        "html_content": "...",
        "has_html": true,
        "timestamp": 1709654321,
        "created_at": "2024-03-05T12:18:41Z"
      }
    ],
    "count": 1
  }
}

4) Прочитать одно письмо — текст, HTML-тело и метаданные

Замените EMAIL_ID на id, полученный на шаге 3. Также передавайте адрес ящика в параметре email (в том числе при удалении и скачивании вложений): тогда письмо читается напрямую из своего ящика, а не ищется по ID. С API-ключом параметр email необязателен, но его передача ускоряет поиск.

curl 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Пример ответа
{
  "success": true,
  "data": {
    "id": "e5a7f3...",
    "email_address": "demo@example.com",
    "from_address": "noreply@github.com",
    "subject": "Your code: 654321",
    "content": "Your verification code is 654321",
    "html_content": "<p>Your code is 654321</p>",
    "has_html": true,
    "timestamp": 1709654321,
    "raw_size": 2048,
    "created_at": "2024-03-05T12:18:41Z"
  }
}

5) Удалить одно письмо по ID

С API-ключом параметр email необязателен, но его передача ускоряет поиск.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Пример ответа
{
  "success": true,
  "data": {
    "message": "Email deleted"
  }
}

6) Очистить весь ящик — удалить все письма для этого адреса

Каждый вызов удаляет одну партию. Пока ответ содержит "has_more": true, вызывайте его снова, пока он не вернёт false.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/emails/clear?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Пример ответа
{
  "success": true,
  "data": {
    "message": "Deleted 3 emails",
    "count": 3,
    "has_more": false
  }
}

Структура ответа

Успешные ответы обычно выглядят так. При аутентификации по API Key смотрите сведения о квоте в usage.

{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

Расширенная статистика

  • /api/statistics/24h возвращает одно 24-часовое окно почасового распределения; используйте offset=1,2,... для более ранних окон.
  • /api/statistics/top-subjects возвращает самые частые темы писем.
  • /api/statistics/top-domains возвращает наиболее активные домены.
  • /api/statistics/top-senders возвращает наиболее активных отправителей.
GPTMail