Contacts and audiences
A contact is one record per address: its name, its fields, its tags, and whatever blocks it. An audience is a list of contacts, the one a campaign goes to. Your agent keeps them up to date; nothing here sends an e-mail.
The directory
Every address has a global record in the space: a name, free fields (fields, text values such as prenom or societe) and tags (labels). list_contacts searches the directory (address, name, fields), filters by tag, by audience or by subscription state. get_contact reads a record, its audiences and its effective block.
The subscription state says what the space knows: subscribed (no known block, which is not proof of consent), unsubscribed (unsubscribed) or blocked (another effective block: bounce, complaint, manual block). A blocked address receives nothing more, from any inbox (see Unsubscribes).
The directory and audiences need a key that reaches every inbox of the space: a key limited to some inboxes is refused (contact_scope, audience_scope).
Audiences
save_audience creates an audience or renames it; import_contacts adds or updates 1 to 500 contacts in it at a time (a batch containing an error is refused as a whole); remove_audience_contact removes an address from it. An address appears only once per audience.
An audience keeps its own copy of each contact’s fields: changing the global record (save_contact) rewrites neither the audiences nor the campaigns already scheduled. set_contact_audiences chooses all of a record’s audiences at once: a new membership copies the global record, the ones that remain keep their fields.
Removing a contact from an audience does not touch a campaign already scheduled. To stop every send to an address, block it (add_suppression).
The tools
list_contacts
The space’s global directory, independent of audiences: search, tags, membership, and unsubscribe or other effective block. Access: read.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | text | no | Search in the address, the name and the fields. |
label | text | no | Exact tag. |
audience_id | aud_… identifier | no | Limit to one of the space’s audiences. |
subscription | text | no | subscribed: no known block (not proof of consent). unsubscribed: unsubscribed. blocked: another effective block. |
offset | integer | no | The rank of the first item returned, from 0 to 100,000: the next_offset value from the previous call. |
limit | integer | no | The number of records returned, from 1 to 200. 100 by default. |
get_contact
Global record, audiences and effective block. Access: read.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | text | yes | Exact address of the contact. |
save_contact
Creates or updates the global record: properties left out are kept. Access: send.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | text | yes | Unique address: creates the record if it does not exist. |
name | text | no | Name. Absent: kept; empty: erased. |
fields | object | no | Replaces the global fields if given; fields specific to audiences stay unchanged. |
labels | list | no | Replaces the global tags if given. |
set_contact_audiences
Replaces all of the contact’s memberships with audience_ids (empty: none). Access: send.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | text | yes | Exact address of the existing record. |
audience_ids | list | yes | All of the record’s audiences, 200 at most. An empty list removes it from all of them. |
list_audiences
The space’s audiences, their origin and number of contacts. Access: read.
get_audience
An audience’s contacts, 200 per page; continue from next_offset. Access: read.
| Parameter | Type | Required | Description |
|---|---|---|---|
audience_id | aud_… identifier | yes | Audience. |
offset | integer | no | The rank of the first item returned, from 0 to 100,000: the next_offset value from the previous call. |
save_audience
Creates an audience, or renames the one given by audience_id. Access: send.
| Parameter | Type | Required | Description |
|---|---|---|---|
audience_id | aud_… identifier | no | Audience to rename, optional. |
name | text | yes | Name of the audience. |
import_contacts
Adds or updates 1 to 500 contacts. Access: send.
| Parameter | Type | Required | Description |
|---|---|---|---|
audience_id | aud_… identifier | yes | Target audience. |
contacts | list | yes | From 1 to 500 contacts: email (required), name, fields (text values) and labels. An invalid batch is refused as a whole. |
remove_audience_contact
Removes the address from an audience. Access: send.
| Parameter | Type | Required | Description |
|---|---|---|---|
audience_id | aud_… identifier | yes | Audience. |
email | text | yes | Exact address. |