Preskočiť na obsah
API dokumentácia

Kontakty a súhlasy

Kontakt

Kontakt je jedna e-mailová adresa vo firme (adresa je vo firme jedinečná, bez ohľadu na veľkosť písmen). Má hlavný e-shop (shopId), profilové polia a stav.

Profilové polia (názvy v API): firstName, lastName, titleBefore, titleAfter, salutation, salutationFormal, vocativeFirstName (oslovenie v 5. páde, napríklad „Petre“), vocativeLastName, gender (f, m, null), language (cs, sk ...), company, companyId (IČO), phone, mobile, street, city, postalCode, country (dve písmená), birthday (YYYY-MM-DD), nameDay (MM-DD), note, affiliateId a vlastné pole customFields ({"<id poľa>": hodnota}, ID polí z GET /custom-fields).

Stav kontaktu (status)

StavVýznamDostáva e-maily
subscribedprihlásenýáno (ak nie je potlačený a nemá slabý súhlas)
pendingčaká na potvrdenie odberu (double opt-in)nie
unsubscribedodhlásenýnie, nikdy znovu bez nového potvrdenia
bouncedadresa je nedoručiteľnánie
complainedoznačil e-mail ako spamnie
customerzákazník bez marketingového súhlasu (vznikol z objednávky)nie (len v rámci zákaznickej výnimky e-shopu)

Poštárna nikdy znovu neoslovuje odhlásený, vrátený alebo potlačený kontakt. Odhlásený kontakt sa znovu prihlási len novým potvrdením odberu (double opt-in), nikdy volaním API.

Pôvod súhlasu (consentBasis)

double_opt_in (potvrdil odber), imported (doložený súhlas zadaný ručne alebo importom), soft_opt_in_customer (zákaznická výnimka), none. Pole consentWeak = slabý súhlas; takým kontaktom kampane ani automatizácie nepíšu.

Účely spracúvania a súhlasy

Účel spracúvania (purpose) je druh súhlasu, napríklad „Zasielanie obchodných oznámení (newsletter)“. Každá firma má východiskový účel; zoznam vráti GET /purposes.

  • Súhlas kontaktu s účelom: GET /contacts/{id}/purposes, zápis POST /contacts/{id}/purposes, odvolanie POST /contacts/{id}/purposes/{consentId}/withdraw.
  • Kampaň môže vziať len kontakty s platným súhlasom (onlyWithPurpose), segmenty a podmienky automatizácií zvládnu pravidlo purpose / contact_purpose.

Založenie kontaktu

Kontakt cez API založíte len tak, keď máte doložený súhlas (napríklad z vlastného formulára alebo zmluvy). Telo musí obsahovať purposeId (účel, ku ktorému sa súhlas vzťahuje) a consentConfirmed: true (potvrdzujete, že súhlas máte doložený).

Požiadavka: POST /api/v1/tenants/{tenant}/contacts
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "email": "jana.novakova@example.cz",
  "shopId": "3",
  "purposeId": "2",
  "consentConfirmed": true,
  "firstName": "Jana",
  "lastName": "Nováková",
  "city": "Brno"
}
JSON
Odpoveď: 201 Created
{
  "id": "1202",
  "email": "jana.novakova@example.cz",
  "firstName": "Jana",
  "lastName": "Nováková",
  "status": "subscribed",
  "engagement": "N",
  "excluded": false,
  "shopId": "3",
  "suppressionReason": null,
  "blacklisted": false,
  "blacklistedAt": null,
  "state": null,
  "createdAt": "2026-10-01T08:00:00.000Z",
  "phone": "",
  "mobile": "",
  "titleBefore": "",
  "titleAfter": "",
  "salutation": "",
  "salutationFormal": "",
  "vocativeFirstName": "",
  "vocativeLastName": "",
  "gender": null,
  "language": "cs",
  "company": "",
  "companyId": "",
  "street": "",
  "city": "Brno",
  "postalCode": "",
  "note": "",
  "affiliateId": "",
  "country": null,
  "birthday": null,
  "nameDay": null,
  "source": "manual",
  "consentBasis": "imported",
  "statusAt": "2026-10-01T08:00:00.000Z",
  "consentAt": "2026-10-01T08:00:00.000Z",
  "consentWeak": false,
  "softBounces": 0,
  "lastSentAt": null,
  "lastOpenAt": null,
  "lastClickAt": null,
  "suppressedAt": null,
  "engagementAt": null,
  "suppressionNote": null,
  "customFields": {},
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "stats90d": {
    "received": 0,
    "opened": 0,
    "clicked": 0,
    "bestHour": null
  },
  "lists": [],
  "recentActivities": [
    {
      "id": "consent-2",
      "type": "status_change",
      "at": "2026-10-01T08:00:00.000Z",
      "title": "purpose_assigned"
    }
  ],
  "orders": [],
  "orderTotals": [],
  "editedFields": [],
  "sources": []
}
  • Nový kontakt dostane source: "manual", consentBasis: "imported" a jazyk e-shopu, ak nepošlete vlastný.
  • Adresa, ktorá je potlačená (odhlásená, vrátená, sťažnosť), vznikne s príslušným stavom a potlačenie zostáva.
  • listIds rovno pridá kontakt do ručných alebo formulárových zoznamov.
  • Adresa, ktorá už je kontaktom, vráti 409:
Požiadavka: POST /api/v1/tenants/{tenant}/contacts
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "email": "jana.novakova@example.cz",
  "shopId": "3",
  "purposeId": "2",
  "consentConfirmed": true
}
JSON
Odpoveď: 409 Conflict
{
  "error": {
    "code": "conflict",
    "message": "email"
  }
}

Keď doložený súhlas nemáte, použite formulár s potvrdením (double opt-in), pozrite recept. Kupujúci z objednávok (POST /orders) dostanú stav customer a e-maily nedostávajú.

Vyhľadávanie a úpravy

Požiadavka: GET /api/v1/tenants/{tenant}/contacts
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts?q=jana.novakova%40example.cz" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "items": [
    {
      "id": "1202",
      "email": "jana.novakova@example.cz",
      "firstName": "Jana",
      "lastName": "Nováková",
      "status": "subscribed",
      "engagement": "N",
      "excluded": false,
      "shopId": "3",
      "suppressionReason": null,
      "blacklisted": false,
      "blacklistedAt": null,
      "state": "active",
      "createdAt": "2026-10-01T08:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}

PATCH /contacts/{id} mení profilové polia a vlastné polia, nikdy adresu, stav ani súhlas (400 email). Polia, ktoré upravil človek v aplikácii, importy a synchronizácie neprepíšu.

Požiadavka: PATCH /api/v1/tenants/{tenant}/contacts/1202
curl -sS -X PATCH "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts/1202" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "phone": "+420 600 000 000",
  "customFields": {}
}
JSON
Odpoveď: 200 OK
{
  "id": "1202",
  "email": "jana.novakova@example.cz",
  "firstName": "Jana",
  "lastName": "Nováková",
  "status": "subscribed",
  "engagement": "N",
  "excluded": false,
  "shopId": "3",
  "suppressionReason": null,
  "blacklisted": false,
  "blacklistedAt": null,
  "state": null,
  "createdAt": "2026-10-01T08:00:00.000Z",
  "phone": "+420 600 000 000",
  "mobile": "",
  "titleBefore": "",
  "titleAfter": "",
  "salutation": "",
  "salutationFormal": "",
  "vocativeFirstName": "",
  "vocativeLastName": "",
  "gender": null,
  "language": "cs",
  "company": "",
  "companyId": "",
  "street": "",
  "city": "Brno",
  "postalCode": "",
  "note": "",
  "affiliateId": "",
  "country": null,
  "birthday": null,
  "nameDay": null,
  "source": "manual",
  "consentBasis": "imported",
  "statusAt": "2026-10-01T08:00:00.000Z",
  "consentAt": "2026-10-01T08:00:00.000Z",
  "consentWeak": false,
  "softBounces": 0,
  "lastSentAt": null,
  "lastOpenAt": null,
  "lastClickAt": null,
  "suppressedAt": null,
  "engagementAt": null,
  "suppressionNote": null,
  "customFields": {},
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "stats90d": {
    "received": 0,
    "opened": 0,
    "clicked": 0,
    "bestHour": null
  },
  "lists": [],
  "recentActivities": [
    {
      "id": "consent-2",
      "type": "status_change",
      "at": "2026-10-01T08:00:00.000Z",
      "title": "purpose_assigned"
    }
  ],
  "orders": [],
  "orderTotals": [],
  "editedFields": [],
  "sources": []
}

Ďalšie filtre zoznamu kontaktov: status, list (ID zoznamu), shop, engagement (A až E, N), source, createdFrom, createdTo, tab a záporné varianty stateOp=neq, listOp=neq a ďalšie (pozrite referencia kontaktov).

Odhlásenie, potlačenie a blacklist

  • POST /contacts/{id}/unsubscribe odhlási kontakt zo všetkého, ako by kliknul na odkaz v e-maile: stav unsubscribed, adresa sa potlačí, e-maily v poradí sa preskočia, zápis do historie súhlasov.
Požiadavka: POST /api/v1/tenants/{tenant}/contacts/1202/unsubscribe
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts/1202/unsubscribe" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "note": "Požádala telefonicky"
}
JSON
Odpoveď: 200 OK
{
  "id": "1202",
  "email": "jana.novakova@example.cz",
  "firstName": "Jana",
  "lastName": "Nováková",
  "status": "unsubscribed",
  "engagement": "N",
  "excluded": false,
  "shopId": "3",
  "suppressionReason": "unsubscribed",
  "blacklisted": false,
  "blacklistedAt": null,
  "state": null,
  "createdAt": "2026-10-01T08:00:00.000Z",
  "phone": "+420 600 000 000",
  "mobile": "",
  "titleBefore": "",
  "titleAfter": "",
  "salutation": "",
  "salutationFormal": "",
  "vocativeFirstName": "",
  "vocativeLastName": "",
  "gender": null,
  "language": "cs",
  "company": "",
  "companyId": "",
  "street": "",
  "city": "Brno",
  "postalCode": "",
  "note": "",
  "affiliateId": "",
  "country": null,
  "birthday": null,
  "nameDay": null,
  "source": "manual",
  "consentBasis": "imported",
  "statusAt": "2026-10-01T08:00:00.000Z",
  "consentAt": "2026-10-01T08:00:00.000Z",
  "consentWeak": false,
  "softBounces": 0,
  "lastSentAt": null,
  "lastOpenAt": null,
  "lastClickAt": null,
  "suppressedAt": "2026-10-01T08:00:00.000Z",
  "engagementAt": null,
  "suppressionNote": null,
  "customFields": {},
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "stats90d": {
    "received": 0,
    "opened": 0,
    "clicked": 0,
    "bestHour": null
  },
  "lists": [
    {
      "listId": "41",
      "name": "VIP zákazníci",
      "state": "confirmed",
      "changedAt": "2026-10-01T08:00:00.000Z",
      "listSize": 1
    }
  ],
  "recentActivities": [
    {
      "id": "consent-4",
      "type": "unsubscribed",
      "at": "2026-10-01T08:00:00.000Z",
      "title": "admin"
    },
    {
      "id": "consent-3",
      "type": "status_change",
      "at": "2026-10-01T08:00:00.000Z",
      "title": "suppressed"
    },
    {
      "id": "consent-2",
      "type": "status_change",
      "at": "2026-10-01T08:00:00.000Z",
      "title": "purpose_assigned"
    }
  ],
  "orders": [],
  "orderTotals": [],
  "editedFields": [],
  "sources": []
}
  • Potlačenie (suppressions) je zoznam adries, na ktoré sa nesmie písať: odhlásenie, nedoručiteľné, sťažnosti a ručný blacklist. GET /suppressions, ručné pridanie POST /suppressions s {"email", "detail"}.
Požiadavka: GET /api/v1/tenants/{tenant}/suppressions
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/suppressions" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "items": [
    {
      "email": "jana.novakova@example.cz",
      "reason": "unsubscribed",
      "source": "admin",
      "detail": "",
      "blacklisted": false,
      "createdAt": "2026-10-01T08:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}
  • Potlačenie sa maže len po jednom (DELETE /suppressions/{email}), hromadné mazanie databázy odmietne. Blacklist kontaktu: POST a DELETE /contacts/{id}/blacklist; adresa potlačená z iného dôvodu vráti 409 suppression_locked.

Osobné údaje (GDPR)

  • GET /contacts/{id}/export: všetky dáta kontaktu (profil, súhlasy, zoznamy, aktivity, objednávky).
  • POST /contacts/{id}/erase s telom {"confirm": true}: nevratný výmaz na žiadosť človeka. Kontakt, jeho súhlasy, členstvá a história zmiznú, adresa sa odstráni aj z odoslaných e-mailov, objednávok a záznamu súhlasov. Zostane len odtlačok adresy (nie adresa), aby ju import ani synchronizácia znovu nezaložili, a riadok potlačenia, ak sa adresa odhlásila alebo bola nedoručiteľná (pravidlo „nikdy znovu nepísať“).
  • DELETE /contacts/{id}: zmaže kontakt s jeho členstvami, súhlasmi a aktivitami; odoslané e-maily a záznamy zostanú s adresou a potlačenie sa nemení. Na žiadosť o výmaz používajte erase.

Shrnutie: komu e-mail odíde

E-mail kampane alebo automatizácie odíde len kontaktu, ktorý je súčasne:

  1. v stave subscribed,
  2. bez potlačenia (odhlásenie, nedoručiteľnosť, sťažnosť, blacklist),
  3. bez slabého súhlasu,
  4. pri zákaznickej výnimke ešte v jej lehote,
  5. a pri kampani spĺňa jej publikum (zoznamy, segmenty, vylúčenie, účel).

Kontroluje sa pri výbere príjemcov aj tesne pred odoslaním každého e-mailu.