API dokumentace Poštárny
Poštárna je platforma pro e-mail marketing se statistikami pro firmy i e-shopy v Česku a na Slovensku. Přes API uděláte totéž co v aplikaci: spravujete kontakty a souhlasy, seznamy a segmenty, píšete šablony, posíláte kampaně, stavíte automatizace, přijímáte objednávky, feedy a kupóny a necháte si posílat webhooky. Dokumentace je psaná tak, aby podle ní člověk i AI agent napsal funkční integraci napoprvé, bez zkoušení naslepo.
Tři rozhraní
| Rozhraní | Adresa | K čemu |
|---|---|---|
| API v1 | https://www.postarna.cz/api/v1/tenants/{tenant}/... | Celé API Poštárny, stejné, jaké používá webová aplikace. JSON, přihlášení API klíčem. |
| API v3 kompatibilní se SmartEmailingem | https://www.postarna.cz/api/v3/... a /api/csv/... | Stejné cesty, obálky a chyby jako REST API v3 SmartEmailingu. Čtení kontaktů, seznamů a polí, účtové webhooky, CSV statistiky. |
| Server MCP | https://www.postarna.cz/mcp | Model Context Protocol pro AI asistenty (ChatGPT, Claude, Cursor a další). |
Stejné API odpovídá i na https://www.postarna.sk.
Nejdůležitější pravidla na jednom místě
- Přihlášení: API klíč
pst_...v hlavičceAuthorization: Bearer pst_...(nebo HTTP Basic: e-mail člena firmy a klíč). Klíč vytvoříte v aplikaci v Nastavení › Datové zdroje › API klíče. Podrobně v Začínáme. - Firma v cestě:
{tenant}je veřejné ID firmy (UUID). Zjistíte ho volánímGET /api/v3/account-info(poledata.guid) nebo na stránce API klíčů. - JSON: ID jsou řetězce, časy ISO 8601 v UTC, peníze desetinný řetězec vedle měny. CZK a EUR se nikdy nesčítají ani nepřevádějí. Viz Pravidla API.
- Chyby:
{"error": {"code", "message", "params"}},codeje stálý strojový kód,messagejmenuje pole. Každý kód s významem a nápravou je v Chyby a limity. - Limity: na firmu zásobník 2 500 požadavků doplňovaný 4 za sekundu a 100 000 za den; hlavičky
X-RateLimit-*, po překročení 429 sRetry-After. - Bezpečnost odesílání: odhlášenému, vrácenému nebo potlačenému kontaktu Poštárna nikdy nic nepošle. Než pošlete skutečným příjemcům, spočítejte je (
POST .../campaigns/audience) a automatizaci otestujte (POST .../automations/{id}/test).
Pro AI agenty
/llms.txt: stručný rozcestník celé dokumentace v Markdownu./llms-full.txt: všechny návody, koncepty a recepty v jednom souboru a seznam všech operací./api/openapi.json: OpenAPI 3.1 se všemi operacemi a schématy. Jen jednu skupinu načtete parametrem?tag=, například?tag=Automationsnebo?tag=Contacts,Lists.- Graf automatizace, podmínky a časové údaje mají přesná schémata v Referenci automatizací; stejná pravidla používá validátor serveru.
- Postup „nejdřív náhled, potom akce“:
POST /automations/validate,POST /automations/{id}/test,POST /campaigns/audience. U trasy sx-mcp-confirmv OpenAPI vždy počítejte s tím, že posílá skutečným lidem nebo maže data.
Jak je dokumentace uspořádaná
- Začínáme: první volání a pravidla API.
- Koncepty: firma a e-shopy, kontakty a souhlasy, seznamy a segmenty, šablony a personalizace, kampaně, automatizace a jejich reference, objednávky, feedy a kupóny.
- Recepty: hotové postupy s ověřenými požadavky a odpověďmi: opuštěný košík, série po nákupu, svátky, návrat neaktivních zákazníků, formulář s potvrzením, import kontaktů, odeslání kampaně, příjem webhooků.
- Integrace: webhooky, MCP pro AI asistenty, kompatibilita se SmartEmailingem.
- Reference API: přehled všech operací, chyby a limity, stránka pro každou skupinu operací a historie změn.