# Migrating from Audiences to Segments

> How MailBlastr moved from per-audience Contacts to a global Contacts model with Segments and Topics — what changed, how unsubscribes work now, and what to do.

MailBlastr has changed how contacts are organized. Previously, each contact belonged to exactly one **audience**, and creating a contact with the same email address in a different audience produced a completely separate object.

In the new model, contacts are **independent of audiences** — audiences are now called **[segments](https://www.mailblastr.com/docs/segments/overview)**. A contact can belong to zero, one, or many segments and still counts as a single contact toward your quota.

> **Note:** Contact API endpoints that previously took an `audience_id` are now scoped by **sending domain**: pass `domain` when creating a contact and `?domain=` when listing (passing `audience_id` is rejected). Each domain keeps its own contact pool with separate consent, and `segment_id` scopes a query to a segment within that domain.

## What’s changing?

We are moving to a **global contacts** model.

- **Before:** if a contact with the same email appeared in multiple audiences, it was counted as multiple contacts.
- **Now:** each email address is a single contact per sending domain, even when it appears in multiple segments. (The same address on two domains is two contact records with separate consent.)

The new model has three concepts:

**Concepts**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Contact` | per-domain entity | No | A single record keyed to an email address within a sending domain’s contact pool. |
| `Segment` | internal tool | No | An internal segmentation tool your team uses to organize who to send to. A contact can be in many segments; every domain carries an auto-created General segment matching all of its contacts. |
| `Topic` | user-facing tool | No | A subscription category your recipients see and manage — the user-facing way to handle email preferences. |

## How unsubscribing changes

Previously, when a contact clicked "unsubscribe," they were marked **unsubscribed only from the specific audience** used in that campaign.

Now, contacts land on a **preference page** where they can either unsubscribe from specific **topics** or unsubscribe from **everything** you send (which updates the global contact status).

## What you should do

If you have been using audiences for both segmentation **and** unsubscribes, switch your unsubscribe logic to **topics**:

1. **Create a topic per email type** — Add a [topic](https://www.mailblastr.com/docs/topics/overview) for each kind of email you send (e.g. product updates, newsletter, billing).
2. **Assign contacts to topics** — Subscribe the right contacts to each topic so recipients can manage them independently.
3. **Use segments for organization only** — Keep segments purely for internal organization of who you send to, not for opt-out state.

With this setup, when you send a [campaign](https://www.mailblastr.com/docs/campaigns/managing), recipients choose which topics to unsubscribe from — or opt out entirely — instead of silently dropping out of one audience.

## Reference

For the new API surface, see:

- [Contacts](https://www.mailblastr.com/docs/api/contacts-create) — create and manage contacts per sending domain (pass `domain` instead of an `audience_id`).
- [Topics](https://www.mailblastr.com/docs/topics/overview) — user-facing subscription preferences.
- [Segments](https://www.mailblastr.com/docs/api/segments-create) — reusable internal filters over your contacts.

> **Note:** Have a use case not covered here? Reach out to support and we’ll help make the transition smooth.