Přeskočit na obsah
API dokumentace

Kompatibilita se SmartEmailingem

Integrace napsaná pro REST API v3 SmartEmailingu funguje s Poštárnou po změně adresy, uživatelského jména a klíče: stejné cesty, obálky, chyby, stránkování a formáty.

Přihlášení

  • Adresa: https://www.postarna.cz/api/v3/ (místo https://app.smartemailing.cz/api/v3/).
  • HTTP Basic: uživatelské jméno je e-mail aktivního člena firmy, heslo je API klíč Poštárny (pst_...). Funguje i Authorization: Bearer pst_....
  • Platí role a přístup klíče i limity požadavků firmy (hlavičky X-RateLimit-*, 429).
Požadavek: GET /api/v3/account-info
curl -sS -X GET "https://www.postarna.cz/api/v3/account-info" \
  -u "$POSTARNA_USER:$POSTARNA_API_KEY"
Odpověď: 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
  }
}

Operace

Metoda a cestaCo dělá
GET /pingtest spojení (bez přihlášení)
GET, POST /check-credentialsověření přihlášení
GET /account-infoúčet; guid je ID firmy pro API v1
GET /contactskontakty: filtry emailaddress, id, blacklisted, hardbounced; expand=customfields
GET /contacts/{id}jeden kontakt
GET /contactlists, GET /contactlists/{id}seznamy
GET /customfieldsvlastní pole; expand=customfield_options
GET, POST /web-hooks, DELETE /web-hooks/{id}účtové webhooky
  • Obálka: {"status": "ok" | "created" | "error", "meta": [] | {...}, "data": ...}.
  • Stránkování limit (výchozí a nejvýš 500) a offset, meta {total_count, displayed_count, offset, limit}; select=a,b vybere vlastnosti, sort=a,-b řadí.
  • Formáty jako SmartEmailing: časy YYYY-MM-DD HH:MM:SS v místním čase firmy, příznaky 0 a 1, pohlaví 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: <parametr>, 429 Rate limit exceeded (...), vždy jako {"status": "error", "meta": [], "message": "..."}.

Co zatím chybí

Zápis přes API v3 není: import kontaktů, úpravy seznamů a odesílání e-mailů přes v3 vrátí 405 (nikdy tichý úspěch). Pro zápis použijte API v1 (kontakty, import, kampaně).

CSV statistiky

Na https://www.postarna.cz/api/csv/ se stejným přihlášením (jen v hlavičce, ne v adrese), CSV se středníkem:

  • GET /statistics/email/automation-email-statistic-id[/{automation_id}]: e-mailové uzly automatizací a jejich ID statistiky.
  • GET /statistics/email/{sent|opened|clicked|bounced|unsubscribed}-detail/{email_statistic_id} s interval_from a interval_to (YYYY-MM-DD HH:MM:SS, místní čas): jeden řádek na kontakt a událost. ID statistiky: c<id kampaně>, nebo a<id automatizace>:<klíč uzlu>. Strojová otevření a kliky se nepočítají.
  • GET /list-contacts?listid=: členové seznamu ve všech stavech.

Ostatní metody CSV API SmartEmailingu vrací 404.