API Reference

Contact Lists API

List contact segments, create static lists, and manage membership by slug. Lists are for segmentation only — they do not grant marketing consent.

Static vs smart lists

Static lists — manual membership via API or dashboard. Use POST /api/v1/contacts/:email/lists to add or remove contacts.

Smart lists — membership is computed from filter rules (locale, subtype consent, list membership, custom attributes, etc.). Create and edit smart lists in the dashboard only. The API can read smart lists (list_type: "smart") but cannot create them or modify filters.

Campaign sends evaluate smart lists at send time. The lists field on a contact reflects static memberships only — not dynamic smart-list membership. See Contact Lists guide and Contacts API.

GET/api/v1/contact-lists

List all contact lists for your organization (static and smart).

Terminal

curl https://artamail.artatol.net/api/v1/contact-lists \
  -H "Authorization: Bearer am_live_sk_xxx"

Response

json

{
  "lists": [
    {
      "id": "list-uuid",
      "slug": "newsletter",
      "name": "Newsletter",
      "description": null,
      "list_type": "static",
      "contact_count": 128,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "list-uuid-2",
      "slug": "product-news-cs",
      "name": "Product news (CS)",
      "description": "Czech product updates segment",
      "list_type": "smart",
      "contact_count": 42,
      "created_at": "2024-02-01T08:00:00Z"
    }
  ],
  "test_mode": false
}

POST/api/v1/contact-lists

Create a static contact list. Slug defaults from the name when omitted.

Request Body

Field	Type	Required	Description
`name`	string	Yes	List display name
`description`	string	No	Optional description
`slug`	string	No	URL-safe identifier (auto-generated from name if omitted)

Example Request

Terminal

curl -X POST https://artamail.artatol.net/api/v1/contact-lists \
  -H "Authorization: Bearer am_live_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP customers",
    "slug": "vip",
    "description": "High-value accounts"
  }'

Response

json

{
  "id": "list-uuid",
  "slug": "vip",
  "name": "VIP customers",
  "description": "High-value accounts",
  "list_type": "static",
  "contact_count": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "test_mode": false
}

GET/api/v1/contact-lists/:slug

Retrieve a single list by slug.

Terminal

curl https://artamail.artatol.net/api/v1/contact-lists/vip \
  -H "Authorization: Bearer am_live_sk_xxx"

Returns 404 if the list is not found. Filter definitions for smart lists are not included in API responses — manage them in the dashboard.

List membership

Add or remove contacts from static lists via POST /api/v1/contacts/:email/lists. You can also pass lists on contact upsert to append static memberships in one call.

Test mode

With test API keys, list endpoints return simulated data with test_mode: true. Lists and memberships are not persisted.