Baza wiedzy

REST API

Udokumentowane API HTTP z kluczami, które można wydawać, ograniczać zakresem i unieważniać.

Szczegóły

Włączone, wszędzie. API udostępnia 104 udokumentowane operacje na 68 ścieżkach (wiadomości, wątki, wersje robocze, etykiety, kontakty, odbiorcy, domeny, szablony, reguły, role, członkowie, ustawienia, kalendarz, śledzenie, webhooki i konto) za zatwierdzonym dokumentem OpenAPI 3.1, który możesz przeczytać bez klucza pod GET /openapi.json. O dostępie decyduje klucz obszaru roboczego wydawany przez Ciebie w Ustawieniach.
Trwałość, na którą to wcześniej czekało, jest gotowa. Wysyłka zapisuje wiersz, zanim cokolwiek zostanie wyekspediowane, z publicznym id w postaci msg_ i 24 znaków szesnastkowych, a GET /emails/{id} go rozwiązuje, wraz z /events dla śladu per odbiorca i /tracking dla otwarć i kliknięć. Idempotency-Key o długości 1–255 znaków jest rezerwowany na unikalnym indeksie złożonym z klucza i Twojego klucza API, więc ponowienie po przekroczeniu czasu zwraca pierwszy wynik z Idempotency-Replayed: true zamiast wysyłać dwa razy. Wysyłka z kluczem odpowiada 200, gdy się ustabilizuje, i 202, gdy wciąż jest w kolejce albo zaplanowana.
Klucze są wydawane, zakresowane, rotowane i unieważniane w Ustawienia → Klucze API. Każdy klucz wydany przez konsolę jest kluczem oe_live_. Prefiks oe_test_ jest rozumiany przez weryfikator i przez ścieżkę wysyłki, gdzie wysyłka w trybie testowym jest zapisywana i potwierdzana jako wysłana, nigdy nie docierając do transportu, ale nic nie potrafi jeszcze takiego klucza wydać, a udostępnienie tej opcji, zanim transport-pustak stanie nad Durable Object, dałoby Ci klucz testowy, który dostarcza naprawdę. Klucz niesie zakres wysyłki obejmujący do 25 całych domen i 50 pojedynczych adresów, przy czym cała domena obejmuje też adresy dodane do niej później, opcjonalne wygaśnięcie od 1 do 3650 dni i opcjonalnie rolę. Rola jest sufitem, a nie drugim nadaniem: GET /ping zwraca zarówno zakresy na kluczu, jak i zakresy, które zostawiła mu rola, więc 403 dla zakresu, który klucz wyraźnie wymienia, ma widoczną przyczynę. Unieważnienie jest aktualizacją, a nie usunięciem, więc późniejsze wywołanie dostaje revoked_api_key zamiast po prostu nie przejść uwierzytelnienia. Rotacja zachowuje w kluczu wszystko oprócz sekretu: id, zakresy, zakres wysyłki i historia żądań trwają dalej, stary sekret umiera w chwili wydania nowego, a klucz z keys:write może rotować sam siebie przez API. Te same akcje listowania, rotacji, unieważniania i włączania są na serwerze MCP dla każdego, czyja rola może zarządzać kluczami.
Czego naprawdę brakuje: API nie ma własnego endpointu do wgrywania plików. Załączniki wbudowane idą jako base64 pod wspólnym limitem 5 MB, a większy plik wysyła się, wskazując po id plik już obecny w obszarze roboczym, który wędruje jako link do pobrania. Odbicia są obsługiwane w skrzynce, a nie w logu wysyłki: raport o dostarczeniu jest parsowany, dopasowywany do oryginału po Message-ID, etykietowany na wątku i wypychany jako webhook email.bounced, ale nic nie zapisuje tego z powrotem do wiersza wysyłki, którego status nie ma stanu bounced, więc przez GET /emails odbita wiadomość wciąż wygląda na sent. Poczta wysłana z okna tworzenia wiadomości w aplikacji również nie pojawia się w GET /emails, bo edytor nie zapisuje przez tę samą ścieżkę wysyłki.