API dokumentácia Poštárne
Poštárna je platforma na e-mail marketing so štatistikami pre firmy aj e-shopy v Česku a na Slovensku. Cez API urobíte to isté, čo v aplikácii: správu kontaktov a súhlasov, zoznamov a segmentov, písanie šablón, odosielanie kampaní, stavbu automatizácií, prijímanie objednávok, feedov a kupónov a nastavenie webhookov. Dokumentácia je napísaná tak, aby podľa nej človek aj AI agent napísal funkčnú integráciu na prvý pokus, bez skúšania naslepo.
Tri rozhrania
| Rozhranie | Adresa | Na čo |
|---|---|---|
| API v1 | https://www.postarna.cz/api/v1/tenants/{tenant}/... | Celé API Poštárne, rovnaké, aké používa webová aplikácia. JSON, prihlásenie API kľúčom. |
| API v3 kompatibilné so SmartEmailingom | https://www.postarna.cz/api/v3/... a /api/csv/... | Rovnaké cesty, obálky a chyby ako REST API v3 SmartEmailingu. Čítanie kontaktov, zoznamov a polí, účtové webhooky, CSV štatistiky. |
| Server MCP | https://www.postarna.cz/mcp | Model Context Protocol pre AI asistentov (ChatGPT, Claude, Cursor a ďalšie). |
Rovnaké API odpovedá aj na https://www.postarna.sk.
Najdôležitejšie pravidlá na jednom mieste
- Prihlásenie: API kľúč
pst_...v hlavičkeAuthorization: Bearer pst_...(alebo HTTP Basic: e-mail člena firmy a kľúč). Kľúč vytvoríte v aplikácii v Nastavenia › Dátové zdroje › API kľúče. Podrobne v Začíname. - Firma v ceste:
{tenant}je verejné ID firmy (UUID). Zistíte ho volanímGET /api/v3/account-info(poledata.guid) alebo na stránke API kľúčov. - JSON: ID sú reťazce, časy ISO 8601 v UTC, peniaze desatinný reťazec vedľa meny. CZK a EUR sa nikdy nesčítavajú ani neprevádzajú. Pozrite Pravidlá API.
- Chyby:
{"error": {"code", "message", "params"}},codeje stály strojový kód,messagepomenúva pole. Každý kód s významom a nápravou je v Chyby a limity. - Limity: na firmu zásobník 2 500 požiadaviek doplňovaný 4 za sekundu a 100 000 za deň; hlavičky
X-RateLimit-*, po prekročení 429 sRetry-After. - Bezpečnosť odosielania: odhlásenému, vrátenému alebo potlačenému kontaktu Poštárna nikdy nič nepošle. Skôr než pošlete skutočným príjemcom, spočítajte ich (
POST .../campaigns/audience) a automatizáciu otestujte (POST .../automations/{id}/test).
Pre AI agentov
/llms.txt: stručný rozcestník celej dokumentácie v Markdowne./llms-full.txt: všetky návody, koncepty a recepty v jednom súbore a zoznam všetkých operácií./api/openapi.json: OpenAPI 3.1 so všetkými operáciami a schémami. Len jednu skupinu načítate parametrom?tag=, napríklad?tag=Automationsalebo?tag=Contacts,Lists.- Graf automatizácie, podmienky a časové údaje majú presné schémy v Referencii automatizácií; rovnaké pravidlá používa validátor servera.
- Postup „najprv náhľad, potom akcia“:
POST /automations/validate,POST /automations/{id}/test,POST /campaigns/audience. Pri trase sx-mcp-confirmv OpenAPI vždy počítajte s tým, že posiela skutočným ľuďom alebo maže dáta.
Ako je dokumentácia usporiadaná
- Začíname: prvé volanie a pravidlá API.
- Koncepty: firma a e-shopy, kontakty a súhlasy, zoznamy a segmenty, šablóny a personalizácia, kampane, automatizácie a ich referencia, objednávky, feedy a kupóny.
- Recepty: hotové postupy s overenými požiadavkami a odpoveďami: opustený košík, séria po nákupe, meniny, návrat neaktívnych zákazníkov, formulár s potvrdením, import kontaktov, odoslanie kampane, príjem webhookov.
- Integrácie: webhooky, MCP pre AI asistentov, kompatibilita so SmartEmailingom.
- Referencia API: prehľad všetkých operácií, chyby a limity, stránka pre každú skupinu operácií a história zmien.