API v1 & SMTP RelayOpenAPI 3.1

Портал разработчика & API Песочница

Полная документация по интеграции Antigravity ESP: REST API, SMTP Relay, вебхуки, примеры на 6 языках и интерактивный тестировщик запросов.

Скачать openapi.yamlRaw Spec
Базовый URL (Base URL)
http://localhost:18080/v1

Все запросы API версионированы через префикс /v1.

Аутентификация
Authorization: Bearer sk_...

Передавайте токен в заголовке Authorization. Ключи делятся на sk_live_ и sk_test_.

Формат ошибок (RFC 7807)
{ "error": { "code", "message", "details" } }

Единый стандарт для 400, 401, 403, 404, 422, 429 и 500 ответов.

Язык примеров кода:
POST/v1/send
Принимает одиночное письмо или батч. Немедленно ставит в очередь JetStream и возвращает 202 Accepted со сквозным message_id (ULID).
curl
curl -X POST http://localhost:18080/v1/send \
  -H "Authorization: Bearer sk_test_antigravity_dev_key" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": "transactional",
    "from": "noreply@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Подтверждение регистрации",
    "html": "<h1>Добро пожаловать!</h1>",
    "tags": ["welcome"]
  }'
Пример ответа (JSON)
{
  "status": "accepted",
  "message_id": "01J9X4T7M8K1N2P3Q4R5S6T7U8",
  "sandbox": true,
  "queued_at": "2026-10-06T03:00:00Z"
}
GET/v1/lists
Возвращает реестр адресных книг (списков контактов) аккаунта с количеством активных подписчиков.
curl
curl -X GET http://localhost:18080/v1/lists \
  -H "Authorization: Bearer sk_test_antigravity_dev_key"
Пример ответа (JSON)
{
  "data": [
    {
      "id": "lst_01J9X4T7M8K1N2P3Q4R5S6T7U8",
      "name": "Основная база клиентов",
      "description": "Покупатели интернет-магазина",
      "contacts_count": 14250,
      "created_at": "2026-10-01T12:00:00Z"
    }
  ]
}
POST/v1/contacts/batch
Создаёт или обновляет до 1000 контактов за один вызов с кастомными атрибутами, тегами и согласием.
curl
curl -X POST http://localhost:18080/v1/contacts/batch \
  -H "Authorization: Bearer sk_test_antigravity_dev_key" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "lst_01J9...",
    "contacts": [
      { "email": "alex@example.com", "attributes": { "first_name": "Алексей" } }
    ]
  }'
Пример ответа (JSON)
{
  "total": 2,
  "inserted": 2,
  "updated": 0,
  "errors": []
}
GET/v1/events?limit=50&type=delivered
Позволяет получить события доставки, открытий, кликов, bounce и отписок из ClickHouse с пагинацией.
curl
curl -X GET "http://localhost:18080/v1/events?limit=50&type=delivered" \
  -H "Authorization: Bearer sk_test_antigravity_dev_key"
Пример ответа (JSON)
{
  "events": [
    {
      "event_id": "evt_01J9X4...",
      "message_id": "01J9X4T7M8...",
      "type": "delivered",
      "email": "user@example.com",
      "timestamp": "2026-10-06T03:01:12Z",
      "isp": "yandex",
      "response_code": 250,
      "is_machine": false
    }
  ],
  "cursor": "cursor_next_token"
}
POST/v1/suppressions/check
Проверяет, заблокирован ли email в локальном стоп-листе аккаунта или глобальном стоп-листе платформы (спам-ловушки, hard bounces, жалобы).
curl
curl -X POST http://localhost:18080/v1/suppressions/check \
  -H "Authorization: Bearer sk_test_antigravity_dev_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "stream": "broadcast"}'
Пример ответа (JSON)
{
  "email": "user@example.com",
  "suppressed": false,
  "reason": null,
  "stream": "broadcast"
}