> ## Documentation Index > Fetch the complete documentation index at: https://nuntly.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Contacts, segments, and topics > Manage the contact list behind your broadcasts. Store contact properties, group contacts into segments, let contacts opt out of topics, and understand how the recipients of a broadcast are chosen. 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. > [!NOTE] > > These resources need an API key with the `contact` permission. See [Set up Broadcast](https://nuntly.com/docs/guides/broadcast-setup.md#api-key-permissions). ## 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](#contact-properties) defined in your organization. You can set them when you [create the contact](https://nuntly.com/docs/api-reference/contacts/create-contact.md) or later with an [update](https://nuntly.com/docs/api-reference/contacts/update-contact.md). 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](https://nuntly.com/docs/api-reference/contacts/retrieve-contact.md) 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](https://nuntly.com/docs/guides/data-retention.md) window removes them. * An [unsubscribe](https://nuntly.com/docs/guides/broadcast-unsubscribe.md) and a [suppression](https://nuntly.com/docs/guides/broadcast-unsubscribe.md#suppression-list) 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](https://nuntly.com/docs/api-reference/contact-properties/create-contact-property.md) 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](https://nuntly.com/legal/terms-of-service) prohibit it. | Field | Description | | - | - | | `name` | Letters (either case), digits, and underscores, up to 64 characters, with at least one letter or underscore. Letter case counts: `Plan` and `plan` are different properties. `id`, `email`, `createdAt`, and `updatedAt` are reserved, in any letter case. | | `type` | `string` or `number`. | | `description` | Optional text. | | `defaultValue` | Optional value used to personalize a contact that holds no value for the property. It must match the type. | 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. > [!NOTE] > > A property's exact name and letter case are what a template references directly for personalization. See [Personalization](https://nuntly.com/docs/guides/broadcast-templates.md#personalization). ## 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](https://nuntly.com/docs/api-reference/segment-memberships/add-contact-segment.md), and it stays there until you [remove it](https://nuntly.com/docs/api-reference/segment-memberships/remove-contact-segment.md). * 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](https://nuntly.com/docs/api-reference/topic-memberships/update-contact-topic.md) 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](https://nuntly.com/docs/api-reference/topic-memberships/list-contact-topics.md) returns one entry per topic with the effective state and where it comes from: | Source | Meaning | | - | - | | `explicit` | A record that you set for this contact and topic. | | `default` | No record exists, so the contact is subscribed. | | `platform_opt_out` | The contact used an [unsubscribe link](https://nuntly.com/docs/guides/broadcast-unsubscribe.md). The state is `unsubscribed` for every topic, whatever you set. | ## 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](https://nuntly.com/docs/guides/broadcast-unsubscribe.md). 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](https://nuntly.com/docs/guides/broadcast-sending.md#recipients) of the broadcast. ## Next steps > [card] [Templates](https://nuntly.com/docs/guides/broadcast-templates.md) > > Write and publish the content of your broadcast > [card] [Create and send a broadcast](https://nuntly.com/docs/guides/broadcast-sending.md) > > Choose a segment and a topic, then send > [card] [Unsubscribe and suppression](https://nuntly.com/docs/guides/broadcast-unsubscribe.md) > > How opt-outs and the suppression list affect recipients This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.