Přeskočit na obsah
API dokumentace

Kontakty a souhlasy

Kontakt

Kontakt je jedna e-mailová adresa ve firmě (adresa je ve firmě jedinečná, bez ohledu na velikost písmen). Má hlavní e-shop (shopId), profilová pole a stav.

Profilová pole (názvy v API): firstName, lastName, titleBefore, titleAfter, salutation, salutationFormal, vocativeFirstName (oslovení v 5. pádě, například „Petře“), vocativeLastName, gender (f, m, null), language (cs, sk ...), company, companyId (IČO), phone, mobile, street, city, postalCode, country (dvě písmena), birthday (YYYY-MM-DD), nameDay (MM-DD), note, affiliateId a vlastní pole customFields ({"<id pole>": hodnota}, ID polí z GET /custom-fields).

Stav kontaktu (status)

StavVýznamDostává e-maily
subscribedpřihlášenýano (pokud není potlačený a nemá slabý souhlas)
pendingčeká na potvrzení odběru (double opt-in)ne
unsubscribedodhlášenýne, nikdy znovu bez nového potvrzení
bouncedadresa je nedoručitelnáne
complainedoznačil e-mail jako spamne
customerzákazník bez marketingového souhlasu (vznikl z objednávky)ne (jen v rámci zákaznické výjimky e-shopu)

Poštárna nikdy znovu neobešle odhlášený, vrácený nebo potlačený kontakt. Odhlášený kontakt se znovu přihlásí jen novým potvrzením odběru (double opt-in), nikdy voláním API.

Původ souhlasu (consentBasis)

double_opt_in (potvrdil odběr), imported (doložený souhlas zadaný ručně nebo importem), soft_opt_in_customer (zákaznická výjimka), none. Pole consentWeak = slabý souhlas; takovým kontaktům kampaně ani automatizace nepíšou.

Účely zpracování a souhlasy

Účel zpracování (purpose) je druh souhlasu, například „Zasílání obchodních sdělení (newsletter)“. Každá firma má výchozí účel; seznam vrátí GET /purposes.

  • Souhlas kontaktu s účelem: GET /contacts/{id}/purposes, zápis POST /contacts/{id}/purposes, odvolání POST /contacts/{id}/purposes/{consentId}/withdraw.
  • Kampaň může vzít jen kontakty s platným souhlasem (onlyWithPurpose), segmenty a podmínky automatizací umí pravidlo purpose / contact_purpose.

Založení kontaktu

Kontakt přes API založíte jen tehdy, když máte doložený souhlas (například z vlastního formuláře nebo smlouvy). Tělo musí obsahovat purposeId (účel, ke kterému se souhlas vztahuje) a consentConfirmed: true (potvrzujete, že souhlas máte doložený).

Požadavek: 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
Odpověď: 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, pokud nepošlete vlastní.
  • Adresa, která je potlačená (odhlášená, vrácená, stížnost), vznikne s odpovídajícím stavem a potlačení zůstává.
  • listIds rovnou přidá kontakt do ručních nebo formulářových seznamů.
  • Adresa, která už je kontaktem, vrátí 409:
Požadavek: 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
Odpověď: 409 Conflict
{
  "error": {
    "code": "conflict",
    "message": "email"
  }
}

Když souhlas doložený nemáte, použijte formulář s potvrzením (double opt-in), viz recept. Kupující z objednávek (POST /orders) dostanou stav customer a e-maily nedostávají.

Hledání a úpravy

Požadavek: 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"
Odpověď: 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} mění profilová pole a vlastní pole, nikdy adresu, stav ani souhlas (400 email). Pole, která upravil člověk v aplikaci, importy a synchronizace nepřepíšou.

Požadavek: 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
Odpověď: 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": []
}

Další filtry seznamu kontaktů: status, list (ID seznamu), shop, engagement (A až E, N), source, createdFrom, createdTo, tab a záporné varianty stateOp=neq, listOp=neq a další (viz reference kontaktů).

Odhlášení, potlačení a blacklist

  • POST /contacts/{id}/unsubscribe odhlásí kontakt ze všeho, jako by klikl na odkaz v e-mailu: stav unsubscribed, adresa se potlačí, e-maily ve frontě se přeskočí, zápis do historie souhlasů.
Požadavek: 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
Odpověď: 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čení (suppressions) je seznam adres, na které se nesmí psát: odhlášení, nedoručitelné, stížnosti a ruční blacklist. GET /suppressions, ruční přidání POST /suppressions s {"email", "detail"}.
Požadavek: 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"
Odpověď: 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čení se maže jen po jednom (DELETE /suppressions/{email}), hromadné mazání databáze odmítne. Blacklist kontaktu: POST a DELETE /contacts/{id}/blacklist; adresa potlačená z jiného důvodu vrátí 409 suppression_locked.

Osobní údaje (GDPR)

  • GET /contacts/{id}/export: všechna data kontaktu (profil, souhlasy, seznamy, aktivity, objednávky).
  • POST /contacts/{id}/erase s tělem {"confirm": true}: nevratný výmaz na žádost člověka. Kontakt, jeho souhlasy, členství a historie zmizí, adresa se odstraní i z odeslaných e-mailů, objednávek a záznamu souhlasů. Zůstane jen otisk adresy (ne adresa), aby ji import ani synchronizace znovu nezaložily, a řádek potlačení, pokud se adresa odhlásila nebo byla nedoručitelná (pravidlo „nikdy znovu nepsat“).
  • DELETE /contacts/{id}: smaže kontakt s jeho členstvími, souhlasy a aktivitami; odeslané e-maily a záznamy zůstanou s adresou a potlačení se nemění. Pro žádost o výmaz používejte erase.

Shrnutí: komu e-mail odejde

E-mail kampaně nebo automatizace odejde jen kontaktu, který je současně:

  1. ve stavu subscribed,
  2. bez potlačení (odhlášení, nedoručitelnost, stížnost, blacklist),
  3. bez slabého souhlasu,
  4. u zákaznické výjimky ještě v její lhůtě,
  5. a u kampaně splňuje její publikum (seznamy, segmenty, vyloučení, účel).

Kontroluje se při výběru příjemců i těsně před odesláním každého e-mailu.