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

API GPTMail

Використовуйте API GPTMail, щоб створювати тимчасові поштові скриньки, переглядати й читати листи та видаляти пошту через HTTPS із заголовком X-API-Key. Він підходить для автоматизованих тестів, конвеєрів 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 для AI-інструментів, баз знань або README.

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

AI
llms.txt

·

llms-full.txt

(Markdown)

Швидкий старт

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

  • Більшість ендпоінтів скриньки вимагають параметр email, наприклад ?email=demo@example.com.

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

  • Якщо ви вже знаєте підтримуваний домен на цьому сайті, не обов'язково спочатку викликати ендпоінт генерації email. Можна локально скласти prefix@domain і одразу викликати API скриньки — це економить один запит API.

Обмеження частоти запитів і повторні спроби

  • GET і POST /api/generate-email мають спільний ліміт: 30 запитів за 10 секунд з однієї IP-адреси джерела. Це стосується як публічних, так і особистих API-ключів. Різні ключі та клієнти за однією IP-адресою ділять цей ліміт.

  • Перевищення ліміту повертає HTTP 429 і блокує створення адрес на 10 секунд. Перед повторною спробою зачекайте час, указаний у Retry-After. Якщо цього заголовка немає, зачекайте щонайменше 10 секунд, а потім повторюйте спроби зі збільшенням інтервалів. Уникайте одночасних повторних спроб від клієнтів з однієї IP-адреси.

  • Це правило не стосується перегляду списку листів у скриньці та читання окремих листів. Денні й загальні квоти API-ключів діють незалежно. Очікування 10 секунд не відновлює вичерпану квоту ключа.

Основні ендпоінти

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

Прочитати статистику всього сайту.

Приклад потоку

Нижче два поширені варіанти: дозволити сервісу згенерувати скриньку або запросити фіксований префікс. Якщо ви вже знаєте підтримуваний домен на цьому сайті, можете також скласти адресу локально й одразу запитувати її.

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