Přeskočit na obsah
API dokumentace

Lists

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

Technická reference je anglicky (stejně jako strojově čitelný dokument OpenAPI). Celou skupinu pro AI agenta načtete z /api/openapi.json?tag=Lists.

Přihlášení: Authorization: Bearer pst_... nebo HTTP Basic (e-mail člena firmy a API klíč).

Operace

MetodaCestaPopis
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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo 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).

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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.
pagequeryintegernePage number, from 1. default 1, min 1
pageSizequeryintegerneItems per page, 1 to 100. default 25, min 1, max 100
publicNamequerystringne
qquerystringneSearch text. max 200 chars
shopquerystringneShop id filter.
sortquerystringneSort fields separated by commas, "-" = descending, at most 3 (e.g. name,-id).
tagquerystringneTag filter.

Odpovědi

  • 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ávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: create_list

Creates a manual list.

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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.

Tělo požadavku (application/json)

PoleTypPovinnéPopis
namestringano
publicNamestringano
shopIdstring or nullano
notifyOnUnsubscribebooleanano
notifyOnAddbooleanano
notestringano
tagsarray of stringne
signatureHtmlstringne
senderEmailstringne
senderNamestringneSE's sendername and replyto of a list (API only in SE, SZ-04).
replyTostringne

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem 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).

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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.

Tělo požadavku (application/json): Required by the server: listIds, name.

PoleTypPovinnéPopis
listIdsarray of stringano
namestringano
deleteSourcesbooleanano

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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.

Tělo požadavku (application/json): Required by the server: ids.

PoleTypPovinnéPopis
idsarray of stringano
addarray of stringne
removearray of stringne
tagsarray of stringne

Odpovědi

  • 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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: get_list

One list with counts and settings.

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: update_list

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

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).

Tělo požadavku (application/json)

PoleTypPovinnéPopis
namestringne
publicNamestringne
shopIdstring or nullne
notifyOnUnsubscribebooleanne
notifyOnAddbooleanne
notestringne
tagsarray of stringne
signatureHtmlstringne
senderEmailstringne
senderNamestringneSE's sendername and replyto of a list (API only in SE, SZ-04).
replyTostringne

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: delete_list (přes MCP jen s náhledem a potvrzení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.

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).
modequerystringne

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem 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}}.

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).

Tělo požadavku (application/json)

object

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem 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.

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).

Tělo požadavku (application/json): Required by the server: name.

PoleTypPovinnéPopis
namestringano

Odpovědi

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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: list_list_members

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

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).
bucketqueryone of: active, unconfirmed, unsubscribed, bounced, complained, blacklistedneBucket filter.
createdFromquerystringne
createdToquerystringne
engagementquerystringne
importquerystringne
listquerystringne
listStatequerystringne
pagequeryintegernePage number, from 1. default 1, min 1
pageSizequeryintegerneItems per page, 1 to 100. default 25, min 1, max 100
qquerystringneSearch text. max 200 chars
shopquerystringneOnly objects of this shop (shop id).
sortquerystringneSort fields separated by commas, "-" = descending, at most 3 (e.g. name,-id).
sourcequerystringne
statequerystringne
statusquerystringneStatus filter.
tabquerystringne

Odpovědi

  • 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ávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: add_list_members (přes MCP jen s náhledem a potvrzením)

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

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).

Tělo požadavku (application/json): Required by the server: contactIds.

PoleTypPovinnéPopis
contactIdsarray of stringano

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: remove_list_members (přes MCP jen s náhledem a potvrzením)

Removes contacts from a manual list.

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).

Tělo požadavku (application/json): Required by the server: contactIds.

PoleTypPovinnéPopis
contactIdsarray of stringano

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full

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

Parametry

NázevKdeTypPovinnéPopis
tenantpathstring (uuid)anoPublic 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_idpathstringanoId of the list (string of digits).

Tělo požadavku (application/json): Required by the server: contactIds.

PoleTypPovinnéPopis
contactIdsarray of stringano

Odpovědi

  • 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émata

AddMembersResult

PoleTypPovinnéPopis
addednumberano
alreadyMembernumberanoAlready confirmed or unconfirmed in the list.
skippednumberanoUnsubscribed from the list, unsubscribed, bounced, complained or suppressed: never re-subscribed by hand.

ContactListDetail

PoleTypPovinnéPopis
notifyOnUnsubscribebooleanano
notifyOnAddbooleanano
notestringanoPrivate note for the team.
signatureHtmlstringanoSE's Podpis v e-mailu pro tento seznam kontaktů (HTML), sanitized: {{cl_signature}} of e-mails to the list.
senderEmailstringanoSE'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.
idstringano
namestringano
publicNamestringanoName shown on the unsubscribe page; empty = the name is used.
shopIdstring or nullanonull = list of the whole tenant, not bound to one e-shop.
systemKindone of: form, shop_contacts, shop_newsletter, shop_unsubscribed, nullano
lockedbooleananoSystem lists cannot be deleted.
manualMembersbooleananoFalse for lists filled by an e-shop connection: members are not added or removed by hand (409).
tagsarray of stringanoLabels (štítky), at most 20.
countsListCountsano
createdAtstringano

ContactListSummary

PoleTypPovinnéPopis
idstringano
namestringano
publicNamestringanoName shown on the unsubscribe page; empty = the name is used.
shopIdstring or nullanonull = list of the whole tenant, not bound to one e-shop.
systemKindone of: form, shop_contacts, shop_newsletter, shop_unsubscribed, nullano
lockedbooleananoSystem lists cannot be deleted.
manualMembersbooleananoFalse for lists filled by an e-shop connection: members are not added or removed by hand (409).
tagsarray of stringanoLabels (štítky), at most 20.
countsListCountsano
createdAtstringano

Error

PoleTypPovinnéPopis
errorobjectano
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 stringano
addarray of stringne
removearray of stringne
tagsarray of stringne

ListAutofillResult

PoleTypPovinnéPopis
membersnumberano
contactsnumberano
fieldsmap of numberano

ListCounts

PoleTypPovinnéPopis
totalnumberanoMembers without the removed state; the sum of byBucket.
byBucketobjectano

ListInput

PoleTypPovinnéPopis
namestringano
publicNamestringano
shopIdstring or nullano
notifyOnUnsubscribebooleanano
notifyOnAddbooleanano
notestringano
tagsarray of stringne
signatureHtmlstringne
senderEmailstringne
senderNamestringneSE's sendername and replyto of a list (API only in SE, SZ-04).
replyTostringne

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 nullano
queuedbooleanne

ListMember

PoleTypPovinnéPopis
listStateone of: unsubscribed, confirmed, unconfirmedanoState in this list; removed members are never returned.
bucketone of: active, unsubscribed, bounced, complained, blacklisted, unconfirmedano
addedAtstringano
changedAtstringano
idstringano
emailstringano
firstNamestringano
lastNamestringano
statusone of: pending, subscribed, unsubscribed, bounced, complained, customerano
engagementone of: A, B, C, D, E, Nano
excludedbooleananoSE "Vyloučené": long inactive yet mailed often (recomputed weekly with the engagement).
shopIdstring or nullanoMain e-shop (contacts.shop_id), null when unknown.
suppressionReasonone of: invalid, manual, unsubscribed, hard_bounce, complaint, soft_bounce_limit, nullanoSet when the address is on the tenant suppression list.
blacklistedbooleanneOn 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 nullneWhen 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, blacklistedneSmartEmailing's 3-value contact state; older servers leave it out (contactState derives it).
createdAtstringano
extramap of boolean or string or number or nullneValues 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 stringano
namestringano
deleteSourcesbooleanano

ListMergeResult

PoleTypPovinnéPopis
listContactListDetailano
jobIdstring or nullano

RemoveMembersResult

PoleTypPovinnéPopis
removednumberano