Preskočiť na obsah
API dokumentácia

Kampane

Kampaň je jednorazová rozosielka (newsletter) jedného e-shopu. Nič neodíde z konceptu: odoslanie spustí len schválenie s potvrdeným počtom príjemcov.

Stavy

AkciaZo stavuDo stavu
POST /campaigns/{id}/approve so sendAtdraftscheduled
POST /campaigns/{id}/approve so sendAt: nulldraftsending
nastal čas odoslaniascheduledsending (alebo paused s recipient_drift, keď sa počet príjemcov zmenil o viac než 5 %)
automatická pauzasendingpaused (bounce_rate, complaint_rate, unsubscribe_rate, template_error)
POST /campaigns/{id}/pausescheduled, sendingpaused (manual)
POST /campaigns/{id}/resumepausedsending, alebo scheduled, keď ešte nezačala
POST /campaigns/{id}/canceldraft, scheduled, sending, pausedcancelled
odišiel posledný e-mailsendingcompleted

Iný prechod = 409 conflict / status. Upravovať (PATCH, obsah) ide len koncept.

Koncept

POST /campaigns založí koncept; povinné sú len name a shopId, zvyšok doplníte neskôr.

  • senderId: overený odosielateľ e-shopu kampane (GET /senders).
  • fromName, subject (do 200 znakov), preheader.
  • audience: komu kampaň ide (pozrite nižšie).
  • trackOpens, trackClicks (východiskovo true), utm ({source, medium, campaign, term?, content?} alebo null), linkParams, headers (vlastné hlavičky X-...).
  • templateId je len informácia, odkiaľ sa obsah skopíroval. Obsah kampane uložíte cez PUT /campaigns/{id}/content ({editor, html, design, baseVersion}, pri novej kampani baseVersion: 0).

Publikum

audience
{"listIds": ["42"], "segmentIds": [], "excludeListIds": [], "excludeInactive": true,
 "excludeEmails": [], "onlyWithPurpose": false, "purposeIds": []}
  • listIds, segmentIds: zoznamy e-shopu kampane alebo celej firmy a segmenty e-shopu kampane (najviac 100 ID v každom poli).
  • excludeListIds, excludeEmails (najviac 1 000 adries): vylúčenie.
  • excludeInactive: vynechá kontakty s angažovanosťou E.
  • onlyWithPurpose a purposeIds: len kontakty s platným súhlasom pre niektorý z účelov.

POST /campaigns/audience spočíta príjemcov a dôvody vylúčenia (každý kontakt má jeden dôvod): not_mailable (odhlásený, nedoručiteľný, sťažnosť, potlačený), unconfirmed, weak_consent, exception_expired, no_purpose, excluded_list, excluded_manual, inactive. Platí recipients + súčet excluded = matched.

Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/audience
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/audience" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "shopId": "17",
  "audience": {
    "listIds": [
      "44"
    ],
    "segmentIds": [],
    "excludeListIds": [],
    "excludeInactive": true,
    "excludeEmails": [],
    "onlyWithPurpose": false,
    "purposeIds": []
  }
}
JSON
Odpoveď: 200 OK
{
  "matched": 1,
  "recipients": 1,
  "excluded": {
    "not_mailable": 0,
    "unconfirmed": 0,
    "weak_consent": 0,
    "exception_expired": 0,
    "no_purpose": 0,
    "excluded_list": 0,
    "excluded_manual": 0,
    "inactive": 0
  }
}

Schválenie (odoslanie)

POST /campaigns/{id}/approve s {"sendAt", "expectedRecipients"}:

  • sendAt: null = odoslať hned, inak čas 5 minút až 365 dní dopredu (ISO 8601 so zónou).
  • expectedRecipients: počet príjemcov, ktorý ste práve spočítali a užívateľ potvrdil. Keď sa skutočný počet líši o viac než 5 %, server vráti 409 conflict / recipients s params.expected a params.actual a kampaň zostane konceptom:
Požiadavka: POST /api/v1/tenants/{tenant}/campaigns/151/approve
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/campaigns/151/approve" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "sendAt": "2026-10-02T07:00:00.000Z",
  "expectedRecipients": 250
}
JSON
Odpoveď: 409 Conflict
{
  "error": {
    "code": "conflict",
    "message": "recipients",
    "params": {
      "expected": 250,
      "actual": 1
    }
  }
}

Kontroly v tomto poradí: stav draft, subject, fromName, senderId (overený odosielateľ rovnakého e-shopu), content (bez obsahu nejde odoslať), lint (chyba kontroly obsahu, params.codes), audience (aspoň jeden zoznam alebo segment a aspoň jeden príjemca), sendAt, expectedRecipients.

Čo musí byť nastavené, aby e-maily odišli

  • Overený odosielateľ e-shopu (doména s SPF, DKIM a DMARC, Nastavenia › Odosielanie; cez API /sending/...).
  • Zapnuté odosielanie firmy: GET /sending-mode vracia sendingEnabled (hlavný vypínač firmy, zapína ho len prihlásený človek) a sendingState (schválenie ostrého odosielania platformou). Dokým je vypnuté, naplánované kampane čakajú a automatizácia nikoho nepustí; testovacie e-maily chodia.
  • Denné limity a zahrievanie novej domény rozložia veľké rozosielky v čase.

Štatistiky

GET /campaigns/{id} vracia stats (sent, delivered, opened, clicked, bounced, complained, unsubscribed; unikátne kontakty, delivered + bounced = sent). Podrobne: GET /stats/campaigns/{id}, /activity, /conversions, /recipients (aj CSV), /heatmap v skupine Štatistiky. Strojové otvorenia a kliky (skenery odkazov) sa nepočítajú.

Jazykové varianty

Kampaň môže mať jazykové varianty pre kontakty s iným jazykom (/campaigns/{id}/variants): náhľad rozdelenia (/variants/preview), schválenie (/variants/approve), pauza, obnovenie a zrušenie celej skupiny. API kľúčom sa dajú volať; AI asistent cez MCP skupinu variant neschváli (posiela ju len človek v aplikácii).