Preskočiť na obsah
API dokumentácia

Lists

Contact lists with explicit membership (manual and form lists) and the lists bound to an e-shop (read only membership).

Technická referencia je v angličtine (rovnako ako strojovo čitateľný dokument OpenAPI). Celú skupinu pre AI agenta načítate z /api/openapi.json?tag=Lists.

Prihlásenie: Authorization: Bearer pst_... alebo HTTP Basic (e-mail člena firmy a API kľúč).

Operácie

MetódaCestaPopis
GET/api/v1/tenants/{tenant}/listsList contact lists
POST/api/v1/tenants/{tenant}/listsCreate a list
POST/api/v1/tenants/{tenant}/lists/mergeMerge lists into a new list (background)
POST/api/v1/tenants/{tenant}/lists/tagsChange labels of lists
GET/api/v1/tenants/{tenant}/lists/{list_id}Get a list
PATCH/api/v1/tenants/{tenant}/lists/{list_id}Update a list
DELETE/api/v1/tenants/{tenant}/lists/{list_id}Delete a list (only the list, with its contacts, or keeping contacts in other lists)
POST/api/v1/tenants/{tenant}/lists/{list_id}/autofillFill empty name day, gender and salutations of the members
POST/api/v1/tenants/{tenant}/lists/{list_id}/copyCopy a list with its members
GET/api/v1/tenants/{tenant}/lists/{list_id}/membersList members of a list
POST/api/v1/tenants/{tenant}/lists/{list_id}/membersAdd contacts to a list
POST/api/v1/tenants/{tenant}/lists/{list_id}/members/removeRemove contacts from a list
POST/api/v1/tenants/{tenant}/lists/{list_id}/members/unsubscribeUnsubscribe contacts from a list

List contact lists

GET /api/v1/tenants/{tenant}/lists

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: list_lists

Contact lists with member counts by bucket. shop = lists of the shop and of the whole company.

Filtry of the grid (routes_grid.py): ?tag= (repeatable, every label), ?idFrom=&idTo=, ?createdFrom=&createdTo= (calendar days), ?membersFrom=&membersTo= (members of any state except removed), ?activeFrom=&activeTo= (SE's Počet aktivních kontaktů), ?publicName= (part of the public name).

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
pagequeryintegerniePage number, from 1. default 1, min 1
pageSizequeryintegernieItems per page, 1 to 100. default 25, min 1, max 100
publicNamequerystringnie
qquerystringnieSearch text. max 200 chars
shopquerystringnieShop id filter.
sortquerystringnieSort fields separated by commas, "-" = descending, at most 3 (e.g. name,-id).
tagquerystringnieTag filter.

Odpovede

  • 200 OK: application/json object

Chyby

StavKódHodnoty message
400validationpublicName, q, sort, tag
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
429429 rate_limited: wait Retry-After seconds.

Create a list

POST /api/v1/tenants/{tenant}/lists

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: create_list

Creates a manual list.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Telo požiadavky (application/json)

PoleTypPovinnéPopis
namestringáno
publicNamestringáno
shopIdstring or nulláno
notifyOnUnsubscribebooleanáno
notifyOnAddbooleanáno
notestringáno
tagsarray of stringnie
signatureHtmlstringnie
senderEmailstringnie
senderNamestringnieSE's sendername and replyto of a list (API only in SE, SZ-04).
replyTostringnie

Odpovede

Chyby

StavKódHodnoty message
400validationreplyTo, senderEmail, senderName, signatureHtml, tags
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
409conflictlocked, name
429429 rate_limited: wait Retry-After seconds.

Merge lists into a new list (background)

POST /api/v1/tenants/{tenant}/lists/merge

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Bulk action Sloučit seznamy kontaktů (SZ-07): body {listIds (2 to 100), name, deleteSources}. Creates the new list named name now (409 conflict name_taken) and merges the members in the background (202 {list, jobId}; the notification list_merged tells when it is done). A contact in more lists keeps its most cautious state, nobody is subscribed again. deleteSources deletes the original lists afterwards (only the lists; 409 conflict locked when one of them is a system list).

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Telo požiadavky (application/json): Required by the server: listIds, name.

PoleTypPovinnéPopis
listIdsarray of stringáno
namestringáno
deleteSourcesbooleanáno

Odpovede

Chyby

StavKódHodnoty message
400validationlistIds, replyTo, senderEmail, senderName, signatureHtml, tags
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
409conflictlocked, name
429429 rate_limited: wait Retry-After seconds.

Change labels of lists

POST /api/v1/tenants/{tenant}/lists/tags

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Telo požiadavky (application/json): Required by the server: ids.

PoleTypPovinnéPopis
idsarray of stringáno
addarray of stringnie
removearray of stringnie
tagsarray of stringnie

Odpovede

  • 200 OK: application/json object

Chyby

StavKódHodnoty message
400validationids
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
429429 rate_limited: wait Retry-After seconds.

Get a list

GET /api/v1/tenants/{tenant}/lists/{list_id}

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: get_list

One list with counts and settings.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).

Odpovede

Chyby

StavKódHodnoty message
400validation
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
429429 rate_limited: wait Retry-After seconds.

Update a list

PATCH /api/v1/tenants/{tenant}/lists/{list_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: update_list

Changes a list (name, public name, notifications, note).

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).

Telo požiadavky (application/json)

PoleTypPovinnéPopis
namestringnie
publicNamestringnie
shopIdstring or nullnie
notifyOnUnsubscribebooleannie
notifyOnAddbooleannie
notestringnie
tagsarray of stringnie
signatureHtmlstringnie
senderEmailstringnie
senderNamestringnieSE's sendername and replyto of a list (API only in SE, SZ-04).
replyTostringnie

Odpovede

Chyby

StavKódHodnoty message
400validationreplyTo, senderEmail, senderName, signatureHtml, tags
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
409conflictlocked, name
429429 rate_limited: wait Retry-After seconds.

Delete a list (only the list, with its contacts, or keeping contacts in other lists)

DELETE /api/v1/tenants/{tenant}/lists/{list_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: delete_list (cez MCP len s náhľadom a potvrdením)

Deletes a manual list (memberships go, contacts stay).

SE's Smazat seznam with its three ways (?mode=, SZ-08): list (default) = only the list, its contacts stay (204); with_contacts = the list and its contacts, keep_used = the list and those of its contacts that are in no other list or segment: both run in the background (202 {jobId}; the notification list_deleted tells when it is done). Unsubscribed contacts keep their suppression, contacts a campaign was just sent to stay. 409 conflict locked for a system list.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).
modequerystringnie

Odpovede

Chyby

StavKódHodnoty message
400validationmode
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
409conflictlocked
429429 rate_limited: wait Retry-After seconds.

Fill empty name day, gender and salutations of the members

POST /api/v1/tenants/{tenant}/lists/{list_id}/autofill

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Row menu "Doplnit svátek, pohlaví a pozdrav" (SZ-06, core/contact_autofill.py): fills only empty fields of the members; {members, contacts, fields: {column: contacts}}.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).

Telo požiadavky (application/json)

object

Odpovede

Chyby

StavKódHodnoty message
400validation
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
429429 rate_limited: wait Retry-After seconds.

Copy a list with its members

POST /api/v1/tenants/{tenant}/lists/{list_id}/copy

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Row menu "Vytvořit kopii seznamu" (SZ-06): body {name}; 201 with the new list (members in their states, no automation starts), 404 unknown list, 409 conflict name_taken.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).

Telo požiadavky (application/json): Required by the server: name.

PoleTypPovinnéPopis
namestringáno

Odpovede

Chyby

StavKódHodnoty message
400validationreplyTo, senderEmail, senderName, signatureHtml, tags
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
409conflictlocked, name
429429 rate_limited: wait Retry-After seconds.

List members of a list

GET /api/v1/tenants/{tenant}/lists/{list_id}/members

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: list_list_members

Members of a list. bucket: active, unconfirmed, unsubscribed, bounced, complained, blacklisted.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).
bucketqueryone of: active, unconfirmed, unsubscribed, bounced, complained, blacklistednieBucket filter.
createdFromquerystringnie
createdToquerystringnie
engagementquerystringnie
importquerystringnie
listquerystringnie
listStatequerystringnie
pagequeryintegerniePage number, from 1. default 1, min 1
pageSizequeryintegernieItems per page, 1 to 100. default 25, min 1, max 100
qquerystringnieSearch text. max 200 chars
shopquerystringnieOnly objects of this shop (shop id).
sortquerystringnieSort fields separated by commas, "-" = descending, at most 3 (e.g. name,-id).
sourcequerystringnie
statequerystringnie
statusquerystringnieStatus filter.
tabquerystringnie

Odpovede

  • 200 OK: application/json object

Chyby

StavKódHodnoty message
400validationq, sort
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
409conflictlocked, name
429429 rate_limited: wait Retry-After seconds.

Add contacts to a list

POST /api/v1/tenants/{tenant}/lists/{list_id}/members

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: add_list_members (cez MCP len s náhľadom a potvrdením)

Adds contacts to a manual list (1 to 1000 ids). Never re-subscribes anyone who unsubscribed.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).

Telo požiadavky (application/json): Required by the server: contactIds.

PoleTypPovinnéPopis
contactIdsarray of stringáno

Odpovede

Chyby

StavKódHodnoty message
400validationcontactIds
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
409conflictlocked
429429 rate_limited: wait Retry-After seconds.

Remove contacts from a list

POST /api/v1/tenants/{tenant}/lists/{list_id}/members/remove

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: remove_list_members (cez MCP len s náhľadom a potvrdením)

Removes contacts from a manual list.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).

Telo požiadavky (application/json): Required by the server: contactIds.

PoleTypPovinnéPopis
contactIdsarray of stringáno

Odpovede

Chyby

StavKódHodnoty message
400validationcontactIds
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
409conflictlocked
429429 rate_limited: wait Retry-After seconds.

Unsubscribe contacts from a list

POST /api/v1/tenants/{tenant}/lists/{list_id}/members/unsubscribe

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Unsubscribes the given members from this list only (body {contactIds}); 409 locked for lists filled by an e-shop connection. Answers {unsubscribed: n}.

Parametre

NázovKdeTypPovinnéPopis
tenantpathstring (uuid)ánoPublic id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
list_idpathstringánoId of the list (string of digits).

Telo požiadavky (application/json): Required by the server: contactIds.

PoleTypPovinnéPopis
contactIdsarray of stringáno

Odpovede

  • 200 OK: application/json object

Chyby

StavKódHodnoty message
400validationcontactIds
401401 unauthorized: missing, unknown, revoked, expired or idle API key.
403403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404not_found
409conflictlocked
429429 rate_limited: wait Retry-After seconds.

Schémy

AddMembersResult

PoleTypPovinnéPopis
addednumberáno
alreadyMembernumberánoAlready confirmed or unconfirmed in the list.
skippednumberánoUnsubscribed from the list, unsubscribed, bounced, complained or suppressed: never re-subscribed by hand.

ContactListDetail

PoleTypPovinnéPopis
notifyOnUnsubscribebooleanáno
notifyOnAddbooleanáno
notestringánoPrivate note for the team.
signatureHtmlstringánoSE's Podpis v e-mailu pro tento seznam kontaktů (HTML), sanitized: {{cl_signature}} of e-mails to the list.
senderEmailstringánoSE's e-mail odesílatele of the list (lower case, '' = none): the signature goes into every e-mail sent from this address, and the list's e-mail notices go to the account's user with this address.
idstringáno
namestringáno
publicNamestringánoName shown on the unsubscribe page; empty = the name is used.
shopIdstring or nullánonull = list of the whole tenant, not bound to one e-shop.
systemKindone of: form, shop_contacts, shop_newsletter, shop_unsubscribed, nulláno
lockedbooleanánoSystem lists cannot be deleted.
manualMembersbooleanánoFalse for lists filled by an e-shop connection: members are not added or removed by hand (409).
tagsarray of stringánoLabels (štítky), at most 20.
countsListCountsáno
createdAtstringáno

ContactListSummary

PoleTypPovinnéPopis
idstringáno
namestringáno
publicNamestringánoName shown on the unsubscribe page; empty = the name is used.
shopIdstring or nullánonull = list of the whole tenant, not bound to one e-shop.
systemKindone of: form, shop_contacts, shop_newsletter, shop_unsubscribed, nulláno
lockedbooleanánoSystem lists cannot be deleted.
manualMembersbooleanánoFalse for lists filled by an e-shop connection: members are not added or removed by hand (409).
tagsarray of stringánoLabels (štítky), at most 20.
countsListCountsáno
createdAtstringáno

Error

PoleTypPovinnéPopis
errorobjectáno
json
{
  "error": {
    "code": "validation",
    "message": "email"
  }
}

GridTagsInput

Bulk label change: add and remove, or tags = the new labels of every row.

PoleTypPovinnéPopis
idsarray of stringáno
addarray of stringnie
removearray of stringnie
tagsarray of stringnie

ListAutofillResult

PoleTypPovinnéPopis
membersnumberáno
contactsnumberáno
fieldsmap of numberáno

ListCounts

PoleTypPovinnéPopis
totalnumberánoMembers without the removed state; the sum of byBucket.
byBucketobjectáno

ListInput

PoleTypPovinnéPopis
namestringáno
publicNamestringáno
shopIdstring or nulláno
notifyOnUnsubscribebooleanáno
notifyOnAddbooleanáno
notestringáno
tagsarray of stringnie
signatureHtmlstringnie
senderEmailstringnie
senderNamestringnieSE's sendername and replyto of a list (API only in SE, SZ-04).
replyTostringnie

ListJobQueued

202 of a deletion with contacts or of a merge: the work runs in the background, a notification tells when done.

PoleTypPovinnéPopis
jobIdstring or nulláno
queuedbooleannie

ListMember

PoleTypPovinnéPopis
listStateone of: unsubscribed, confirmed, unconfirmedánoState in this list; removed members are never returned.
bucketone of: active, unsubscribed, bounced, complained, blacklisted, unconfirmedáno
addedAtstringáno
changedAtstringáno
idstringáno
emailstringáno
firstNamestringáno
lastNamestringáno
statusone of: pending, subscribed, unsubscribed, bounced, complained, customeráno
engagementone of: A, B, C, D, E, Náno
excludedbooleanánoSE "Vyloučené": long inactive yet mailed often (recomputed weekly with the engagement).
shopIdstring or nullánoMain e-shop (contacts.shop_id), null when unknown.
suppressionReasonone of: invalid, manual, unsubscribed, hard_bounce, complaint, soft_bounce_limit, nullánoSet when the address is on the tenant suppression list.
blacklistedbooleannieOn the tenant's blacklist ("Na blacklistu"): a manual entry, or an entry of SmartEmailing's blacklist that keeps its own reason (migration 0180). Older servers leave it out: then suppressionReason 'manual' decides.
blacklistedAtstring or nullnieWhen the address went on the blacklist (the suppression's time), null when it is not on it ("Přidán na blacklist").
stateone of: active, bounced, blacklistednieSmartEmailing's 3-value contact state; older servers leave it out (contactState derives it).
createdAtstringáno
extramap of boolean or string or number or nullnieValues of the extra columns asked for (ContactQuery.fields): dates as YYYY-MM-DD, times as ISO.

ListMergeInput

Bulk action Sloučit seznamy kontaktů (SZ-07).

PoleTypPovinnéPopis
listIdsarray of stringáno
namestringáno
deleteSourcesbooleanáno

ListMergeResult

PoleTypPovinnéPopis
listContactListDetailáno
jobIdstring or nulláno

RemoveMembersResult

PoleTypPovinnéPopis
removednumberáno