Purpose: List contacts, or look one person up.

Use when: the user asks "is X a contact?", "who is in this list?", "who has this tag?". Pass an exact email, phone_number or external_id to find one person, or list_id / tag_id to see an audience.

Not for: counting a list or tag (get-list and get-tag return contact_count). Don't read ids or timestamps back to the user unless they ask for them.

Get one contact by id, with its custom properties and whether it is suppressed (unreachable because of a bounce, complaint or unsubscribe).

Create a contact. At least one of email, phone_number or external_id is required. Custom fields go in properties, keyed by the field keys list-contact-properties returns. This can start the organization's active automations, which may send messages.

Update a contact. Omitted fields are unchanged and null clears one, but the contact must keep an email, phone number or external id.

list_ids REPLACES the contact's list memberships: an empty array removes it from every list. To add without removing, use add-contacts-to-list. This can start the organization's active automations, which may send messages.

List contact lists with their contact counts. Lists are static audiences that campaigns target. Don't read ids or timestamps back to the user unless they ask for them.

Get one contact list and its contact count. To see its members, call list-contacts with list_id.

Create an empty contact list.

Rename a contact list or change its description.

Add contacts to a list, keeping their other memberships. This can start the organization's active automations, which may send messages.

Remove contacts from a list. The contacts themselves are kept. Confirm with the user first, naming the list.

List tags with their contact counts. Don't read ids or timestamps back to the user unless they ask for them.

Get one tag and its contact count. To see who has it, call list-contacts with tag_id.

Create a tag.

Rename a tag or change its description.

Add a tag to contacts. This can start the organization's active automations, which may send messages.

Remove a tag from contacts. This can start the organization's active automations, which may send messages.

List email campaigns, optionally by name or status. Don't read ids or timestamps back to the user unless they ask for them.

Get one email campaign: status, sender, subject, template, audience and schedule.

Create an email campaign. Every field is optional, so a draft can be built up step by step. The audience is the union of list_ids, tag_ids and segment_ids. Find lists with list-lists and tags with list-tags; segments are managed in the Arsel dashboard. The campaign is saved as a draft. This server cannot send or schedule it: the user does that from the Arsel dashboard.

Update an email campaign. Only draft and scheduled campaigns can be edited. Editing a scheduled campaign changes what goes out at its scheduled time, so confirm with the user first. Omitted fields are unchanged.

List SMS campaigns, optionally by name or status. Don't read ids or timestamps back to the user unless they ask for them.

Get one SMS campaign: status, content, sender, segment count and schedule.

Create an SMS campaign. The audience is the union of list_ids, tag_ids and segment_ids. Find lists with list-lists and tags with list-tags; segments are managed in the Arsel dashboard. The campaign is saved as a draft. This server cannot send or schedule it: the user does that from the Arsel dashboard.

Update an SMS campaign. Only draft and scheduled campaigns can be edited. Editing a scheduled campaign changes what goes out at its scheduled time, so confirm with the user first. Omitted fields are unchanged.

List push notification campaigns, optionally by name or status. Don't read ids or timestamps back to the user unless they ask for them.

Get one push campaign: status, notification content, targeting and schedule.

Create a push notification campaign for the organization's app users. The audience is the union of list_ids, tag_ids and segment_ids. Find lists with list-lists and tags with list-tags; segments are managed in the Arsel dashboard. The campaign is saved as a draft. This server cannot send or schedule it: the user does that from the Arsel dashboard.

Update a push campaign. Only draft and scheduled campaigns can be edited. Editing a scheduled campaign changes what goes out at its scheduled time, so confirm with the user first. Omitted fields are unchanged.

List in-app message campaigns (messages shown inside the organization's app or website), optionally by name or status. Don't read ids or timestamps back to the user unless they ask for them.

Get one in-app campaign: status, layout, content, trigger and targeting.

Create an in-app message campaign. The campaign is saved as a draft. This server cannot send or schedule it: the user does that from the Arsel dashboard.

Update an in-app campaign. Unlike other channels an active campaign is editable, and devices show the change on their next fetch: before editing a live campaign you MUST confirm with the user. ended and archived campaigns cannot be edited. Omitted fields are unchanged.

Copy an in-app campaign into a new draft, e.g. to rework a live or ended one without touching it.

List the organization's own email templates. An email campaign uses one through its template_id. Don't read ids or timestamps back to the user unless they ask for them.

Get one email template, including its HTML.

Create an email template from HTML. The HTML is sanitized and an unsubscribe link is added automatically. To start from a professionally designed layout instead, use copy-gallery-template.

Rename an email template or replace its HTML.

List the filters (types, seasons, features, industries) that list-gallery-templates accepts.

Browse Arsel's gallery of ready-made email designs. Copy one into the organization with copy-gallery-template.

Get one gallery design, including its HTML.

Copy a gallery design into the organization's templates, where it can be edited and used by campaigns.

List the organization's custom contact fields: the keys a contact's properties can hold, also usable as merge tags in messages. Don't read ids or timestamps back to the user unless they ask for them.

Get one custom contact field.

Define a custom contact field. field_key and data_type cannot be changed later.

Change a custom field's display name, description or fallback value. Pass null to clear the last two.

List the event types the organization tracks from its apps (e.g. order.completed), with their payload schemas and conversion setup. Don't read ids or timestamps back to the user unless they ask for them.

Get one event type.

Define an event type that apps can send and automations can react to. The name cannot be changed later.

Change an event type's description, schema or conversion setup. schema replaces the whole field list.

List transactional emails with their delivery status. Transactional messages are the one-off sends an application makes through the API (receipts, one-time passwords), not campaigns. Don't read ids or timestamps back to the user unless they ask for them.

Get one transactional emails message with its delivery status.

List transactional sms with their delivery status. Transactional messages are the one-off sends an application makes through the API (receipts, one-time passwords), not campaigns. Don't read ids or timestamps back to the user unless they ask for them.

Get one transactional sms message with its delivery status.

List transactional whatsapp with their delivery status. Transactional messages are the one-off sends an application makes through the API (receipts, one-time passwords), not campaigns. Don't read ids or timestamps back to the user unless they ask for them.

Get one transactional whatsapp message with its delivery status.

List transactional push with their delivery status. Transactional messages are the one-off sends an application makes through the API (receipts, one-time passwords), not campaigns. Don't read ids or timestamps back to the user unless they ask for them.

Get one transactional push message with its delivery status.

List a contact's registered push devices, to check whether they can receive push notifications.

Get the progress and per-row errors of a bulk push-device import.