Contacts, segments, and topics

A broadcast is sent to contacts. This page covers the four things that describe your list: contacts, contact properties, segments, and topics. It ends with the rules that turn them into the recipients of one broadcast.

​

Contacts

A contact is a person you can send broadcasts to, identified by an email address. Your contacts make up the audience of your broadcasts.

• Each address can belong to only one contact in your organization.
• You cannot change the address of a contact after you create it. To use a different address, create a new contact.
• A contact holds values for the contact properties defined in your organization. You can set them when you create the contact or later with an update. A property you leave out at creation gets its default value, when its definition has one.

Listing contacts does not return their properties. Retrieve a contact to read them.

​

Deleting a contact

Deleting a contact removes it from every future broadcast, including one that is already sending and has not reached it yet. It also removes the contact’s segment memberships and topic memberships. Two records stay in place:

• The send records of broadcasts already sent to the contact, including the property values rendered into each message, stay as recorded until your data retention window removes them.
• An unsubscribe and a suppression for the address stay. Creating the contact again does not restore delivery to that address.

​

Contact properties

A contact property is a custom field on your contacts, such as a plan or a signup source. You first define the property for your organization, then set values on contacts. Do not store sensitive data in contact properties, such as health data, religious beliefs, or sexual orientation. The Terms of Service prohibit it. Rules for definitions:

• name and type cannot change after you create the definition. You can update description and defaultValue.
• An organization can hold up to 50 definitions.
• When a contact holds no value for a property, a broadcast personalizes it with the current default value. With no default, a string property renders empty and a number property renders 0.
• A contact created without the property stores the default value. Changing the default later does not update a value a contact already stores.
• You cannot delete a definition while any contact holds a value under its name.

Rules for values on a contact:

• You set values when you create the contact or with an update, keyed by property name. In an update, setting a key to null removes the value.
• Each name must match a definition exactly, letter case included, and the value must match its type. A name with no definition is refused.

​

Segments

A segment is a named list of contacts that you maintain yourself. A segment has no rules. A contact is in a segment when you add it, and it stays there until you remove it.

• A segment name holds letters, numbers, spaces, and the characters ' . , & -, up to 64 characters. Names are stored in lowercase and are unique within your organization.
• An organization can hold up to 25 segments.
• Adding a contact that is already a member succeeds and changes nothing. Removing a contact that is not a member returns a 404 response.
• You cannot delete a segment while a broadcast that targets it is draft, scheduled, queued, sending, or paused. Deleting a segment removes its memberships. Broadcasts that are sent or failed keep their segment id as recorded.

​

Topics

A topic is a kind of message that contacts can opt out of, for example a product newsletter. Every contact is subscribed to every topic by default. You only record an exception, an unsubscribe, for a contact that opted out.

• Topic names follow the same rules as segment names, and an organization can hold up to 25 topics.
• You set the state of a contact for one topic to subscribed or unsubscribed. Repeating the same state changes nothing. A subscribed record is removed when the topic is deleted.
• You cannot delete a topic while any contact has an unsubscribed record for it, or while a broadcast that targets it is draft, scheduled, queued, sending, or paused.

Reading the topics of a contact returns one entry per topic with the effective state and where it comes from:

​

How the recipients of a broadcast are chosen

When you send a broadcast, its recipient set is built in this order:

1. Base set. All contacts of your organization, or the members of the segment named on the broadcast.
2. Topic. When the broadcast names a topic, contacts with an unsubscribed record for that topic are removed. Contacts without a record stay, because they are subscribed by default.
3. Opt-outs and suppression. Addresses that used an unsubscribe link, and addresses on the suppression list, are always removed. See Unsubscribe and suppression.

The contacts that can be included are fixed when the broadcast is accepted. A contact created after that moment does not join a broadcast that is already running. For a scheduled broadcast, the contacts are fixed when the schedule fires, not when you schedule it. A change to segments, topics, or opt-outs while a broadcast is sending applies to the contacts it has not reached yet. A removed recipient gets no message and no send record, so it does not appear in the recipient list of the broadcast.

​

Next steps