Preskočiť na obsah
API dokumentácia

Kompatibilita so SmartEmailingom

Integrácia napísaná pre REST API v3 SmartEmailingu funguje s Poštárnou po zmene adresy, užívateľského mena a kľúča: rovnaké cesty, obálky, chyby, stránkovanie a formáty.

Prihlásenie

  • Adresa: https://www.postarna.cz/api/v3/ (namiesto https://app.smartemailing.cz/api/v3/).
  • HTTP Basic: užívateľské meno je e-mail aktívneho člena firmy, heslo je API kľúč Poštárne (pst_...). Funguje aj Authorization: Bearer pst_....
  • Platí rola a prístup kľúča aj limity požiadaviek firmy (hlavičky X-RateLimit-*, 429).
Požiadavka: GET /api/v3/account-info
curl -sS -X GET "https://www.postarna.cz/api/v3/account-info" \
  -u "$POSTARNA_USER:$POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "status": "ok",
  "meta": [],
  "data": {
    "account_id": 4,
    "guid": "3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f",
    "username": "admin@example.cz",
    "firstname": null,
    "surname": null,
    "company": "Example s.r.o.",
    "phone": null
  }
}

Operácie

Metóda a cestaČo robí
GET /pingtest spojenia (bez prihlásenia)
GET, POST /check-credentialsoverenie prihlásenia
GET /account-infoúčet; guid je ID firmy pre API v1
GET /contactskontakty: filtre emailaddress, id, blacklisted, hardbounced; expand=customfields
GET /contacts/{id}jeden kontakt
GET /contactlists, GET /contactlists/{id}zoznamy
GET /customfieldsvlastné polia; expand=customfield_options
GET, POST /web-hooks, DELETE /web-hooks/{id}účtové webhooky
  • Obálka: {"status": "ok" | "created" | "error", "meta": [] | {...}, "data": ...}.
  • Stránkovanie limit (východiskovo a najviac 500) a offset, meta {total_count, displayed_count, offset, limit}; select=a,b vyberie vlastnosti, sort=a,-b triedi.
  • Formáty ako SmartEmailing: časy YYYY-MM-DD HH:MM:SS v miestnom čase firmy, príznaky 0 a 1, pohlavie M / F, jazyk cs_CZ, sk_SK.
  • Chyby: 401 Authentication Failed, 403, 404 Not Found, 405 Method not allowed, 409 Already exists, 422 Validation failed: <parameter>, 429 Rate limit exceeded (...), vždy ako {"status": "error", "meta": [], "message": "..."}.

Čo zatiaľ chýba

Zápis cez API v3 neexistuje: import kontaktov, úpravy zoznamov a odosielanie e-mailov cez v3 vráti 405 (nikdy tichý úspech). Na zápis použite API v1 (kontakty, import, kampane).

CSV štatistiky

Na https://www.postarna.cz/api/csv/ s rovnakým prihlásením (len v hlavičke, nie v adrese), CSV s bodkočiarkou:

  • GET /statistics/email/automation-email-statistic-id[/{automation_id}]: e-mailové uzly automatizácií a ich ID štatistiky.
  • GET /statistics/email/{sent|opened|clicked|bounced|unsubscribed}-detail/{email_statistic_id} s interval_from a interval_to (YYYY-MM-DD HH:MM:SS, miestny čas): jeden riadok na kontakt a udalosť. ID štatistiky: c<id kampane>, alebo a<id automatizácie>:<kľúč uzla>. Strojové otvorenia a kliky sa nepočítajú.
  • GET /list-contacts?listid=: členovia zoznamu vo všetkých stavoch.

Ostatné metódy CSV API SmartEmailingu vracajú 404.