База знаний
REST API
Документированный HTTP API с ключами, которые можно выпускать, ограничивать скоупами и отзывать.
Подробности
- Включён везде. API отдаёт 104 документированные операции на 68 путях (письма, цепочки, черновики, метки, контакты, аудитории, домены, шаблоны, правила, роли, участники, настройки, календарь, отслеживание, вебхуки и аккаунт) за зафиксированным документом OpenAPI 3.1, который можно прочитать без ключа по GET /openapi.json. Доступ определяется ключом рабочего пространства, который вы выпускаете в настройках.
- Надёжность, которой это раньше не хватало, сделана. Отправка записывает строку до того, как что-либо отправлено, с публичным идентификатором вида msg_ и 24 шестнадцатеричных символов, и GET /emails/{id} его разрешает, вместе с /events для пути по каждому получателю и /tracking для открытий и кликов. Idempotency-Key длиной 1–255 символов занимается через уникальный индекс по ключу вместе с вашим API-ключом, так что повтор после таймаута возвращает первый результат с Idempotency-Replayed: true, а не отправляет дважды. Отправка с ключом отвечает 200, когда она завершилась, и 202, пока она ещё в очереди или запланирована.
- Ключи выпускаются, ограничиваются скоупами, ротируются и отзываются в «Настройки → API-ключи». Каждый ключ, который выпускает консоль, — это oe_live_. Префикс oe_test_ понимают и верификатор, и путь отправки, где тестовая отправка записывается и отвечается как отправленная, ни разу не дойдя до транспорта, но выпустить такой ключ пока нельзя, и предложить эту опцию раньше, чем транспорт-заглушка окажется над Durable Object, значило бы выдать вам тестовый ключ, который доставляет по-настоящему. Ключ несёт скоуп отправки до 25 целых доменов и 50 отдельных адресов, причём целый домен покрывает и адреса, добавленные в него позже, необязательный срок истечения от 1 до 3650 дней и, по желанию, роль. Роль — это потолок, а не второе разрешение: GET /ping возвращает и скоупы самого ключа, и скоупы, которые ему оставила роль, так что у 403 для скоупа, который ключ прямо называет, есть видимая причина. Отзыв — это обновление, а не удаление, поэтому последующему вызову сообщают revoked_api_key, а не просто отказывают в аутентификации. Ротация сохраняет о ключе всё, кроме секрета: идентификатор, скоупы, скоуп отправки и история запросов продолжаются, старый секрет умирает в тот же миг, когда выпущен новый, а ключ с keys:write может ротировать сам себя через API. Те же действия — список, ротация, отзыв и включение — есть на MCP-сервере для всех, чья роль может управлять ключами.
- Чего действительно нет: у API нет собственного эндпоинта загрузки. Встроенные вложения идут в base64 при общем ограничении 5 MB, а файл побольше отправляется указанием по идентификатору файла, уже находящегося в рабочем пространстве, и уезжает ссылкой на скачивание. Возвраты обрабатываются в почтовом ящике, а не в журнале отправок: отчёт о доставке разбирается, сопоставляется с оригиналом по Message-ID, помечается меткой на цепочке и отправляется вебхуком email.bounced, но в строку отправки ничего не пишется, и у её статуса нет состояния bounced, поэтому через GET /emails вернувшееся письмо всё ещё читается как отправленное. Почта, отправленная из окна написания письма в приложении, в GET /emails тоже не появляется, потому что это окно не пишет через тот же путь отправки.