Guide
Contact lists
Segment contacts for campaigns. Lists do not grant marketing consent — use subscription subtypes for that.
Static vs smart
| Type | Membership | Create via API | Use case |
|---|---|---|---|
static | Manual — add/remove per contact | Yes (POST /api/v1/contact-lists) | Newsletter segment, VIP tag, import target |
smart | Computed from filter rules | Read only — create in dashboard | Locale segments, subtype consent, dynamic rules |
contact.lists on API responses
The
lists field on a contact reflects static memberships only (rows in contact_list_members). Smart-list membership is evaluated when viewing a list or sending a campaign — it is not stored as manual membership.List slugs
Every list has a URL-safe slug (auto-generated from name unless overridden). API and SDK use slugs, not UUIDs, for list membership.
bash
# Add to static lists on upsertcurl -X POST https://artamail.artatol.net/api/v1/contacts \ -H "Authorization: Bearer am_live_sk_xxx" \ -d '{ "email": "[email protected]", "lists": ["newsletter", "vip"] }'# Or modify membership explicitlycurl -X POST https://artamail.artatol.net/api/v1/contacts/user%40example.com/lists \ -d '{ "add": ["vip"], "remove": ["trial"] }'Unknown slugs and smart-list slugs return 400 VALIDATION_ERROR with details.invalid_lists — same rules for upsert and POST .../lists.
Smart list filters
Create and edit smart lists in Dashboard → Contacts. Filters support:
- Static list membership (in / not in)
- Contact locale
- Custom contact attributes
- Master subscribed flag
- Subtype consent (opted in / not)
- Email validation status
Campaign sends resolve both static and smart recipient lists at send time, with consent and validation filters applied.
Contact locales (dashboard)
Settings → Contact locales defines which language codes appear in the dashboard (contact edit, smart list locale filter). Stored as organizations.settings.supported_locales.
API locale is unrestricted
The API and SDK accept any valid locale code on contacts (e.g.
de, en-US) regardless of dashboard settings. Supported locales only affect in-app pickers.