Znalostní báze

REST API

Zdokumentované HTTP API s klíči, které lze vydávat, omezovat oprávněními a odvolávat.

Podrobnosti

Zapnuto, všude. API obsluhuje 104 zdokumentovaných operací na 68 cestách (e-maily, vlákna, koncepty, štítky, kontakty, publika, domény, šablony, pravidla, role, členové, nastavení, kalendář, sledování, webhooky a účet) za závazným dokumentem OpenAPI 3.1, který si můžete přečíst bez klíče na GET /openapi.json. O přístupu rozhoduje klíč pracovního prostoru, který vydáte v Nastavení.
Trvanlivost, na kterou se tu dřív čekalo, je hotová. Odeslání zapíše řádek dřív, než se cokoli odešle, s veřejným id ve tvaru msg_ následovaného 24 hexadecimálními znaky, a GET /emails/{id} ho vyhledá, spolu s /events pro stopu podle jednotlivých příjemců a /tracking pro otevření a kliknutí. Idempotency-Key o délce 1–255 znaků se nárokuje proti unikátnímu indexu nad tímto klíčem a vaším API klíčem dohromady, takže opakovaný pokus po vypršení časového limitu vrátí první výsledek s Idempotency-Replayed: true, místo aby odeslal dvakrát. Odeslání s klíčem odpoví 200, jakmile je usazeno, a 202, dokud je stále ve frontě nebo naplánované.
Klíče se vydávají, omezují oprávněními, rotují a odvolávají v Nastavení → API klíče. Každý klíč, který konzole vydá, je oe_live_. Prefix oe_test_ ověřovací vrstva i odesílací cesta chápou, přičemž odeslání v testovacím režimu se zaznamená a odpoví se na ně jako na odeslané, aniž by kdy došlo na transport, ale zatím žádný takový klíč vydat nelze, a nabídnout tu možnost dřív, než bude prázdný transport sedět nad Durable Objectem, by vám dalo testovací klíč, který doručuje doopravdy. Klíč nese odesílací rozsah až 25 celých domén a 50 jednotlivých adres, přičemž celá doména pokrývá i adresy přidané do ní později, volitelnou platnost mezi 1 a 3650 dny a volitelně roli. Role je strop, ne druhé udělení práv: GET /ping vrací jak oprávnění na klíči, tak oprávnění, která mu role ponechala, takže 403 u oprávnění, které váš klíč výslovně uvádí, má viditelnou příčinu. Odvolání je aktualizace, ne smazání, takže pozdější volání dostane revoked_api_key, místo aby se prostě nepovedlo ověřit. Rotace zachová na klíči všechno kromě tajného řetězce: id, oprávnění, odesílací rozsah i historie požadavků pokračují, staré tajemství umírá v okamžiku vydání nového a klíč s keys:write může rotovat sám sebe přes API. Tytéž akce – výpis, rotace, odvolání a zapnutí – jsou na MCP serveru pro každého, jehož role smí klíče spravovat.
Co skutečně chybí: API nemá vlastní endpoint pro nahrávání. Vložené přílohy jdou jako base64 s celkovým stropem 5 MB a větší soubor se odesílá tak, že uvedete id souboru, který už v pracovním prostoru je, a ten pak putuje jako odkaz ke stažení. Odmítnutá doručení se řeší ve schránce, ne v odesílacím logu: zpráva o doručení se rozparsuje, spáruje s originálem podle Message-ID, označí štítkem na vlákně a odešle jako webhook email.bounced, ale nic se nezapíše zpět do odesílacího řádku, jehož stav žádnou hodnotu pro odmítnutí nemá, takže přes GET /emails se odmítnutá zpráva stále čte jako odeslaná. V GET /emails se neobjeví ani pošta odeslaná z okna pro psaní v aplikaci, protože to nezapisuje přes tutéž odesílací cestu.