> ## Documentation Index
> Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription groups

> Manage the email topics customers can join or leave on the email preferences page.

A subscription group is an email topic, such as Marketing, Newsletter, or VIP early access. Every marketing email is sent under one group, and customers join or leave each group on the email preferences page.

```ts theme={null}
import Segmentflow from "@segmentflow/segmentflow-typescript";

const client = new Segmentflow({ apiKey: process.env.SEGMENTFLOW_API_KEY });

const { data: groups } = await client.v1.subscriptionGroups.list();

const group = await client.v1.subscriptionGroups.create({
  name: "VIP early access",
  description: "Hear about new products before anyone else.",
});
```

## Opt-In and Opt-Out

`type` sets who counts as subscribed:

* `OptIn` is the default. Only people who joined get the group's emails, so a new group starts with nobody subscribed until they join through a form or the email preferences page.
* `OptOut` counts everyone as subscribed until they unsubscribe from the group, including every contact who never joined. Marketing email usually needs a clear yes first, so choose it deliberately.

## Default groups

`Marketing` and `Newsletter` are default groups, shown by `isDefault: true`. They keep their names and can't be deleted, because imports, Shopify consent sync and campaign drafts find them by name. Their descriptions can still change, and no other group can take their names.

`Transactional` is a send purpose, not a subscription group, so it can't be used as a group name.

## Retiring a group

Set `isActive` to `false` to hide a group from the email preferences page. A hidden group is paused for new sends: new Journeys, new Newsletters and AI drafts can't use it. People's choices are kept, and setting `isActive` back to `true` resumes it.

```ts theme={null}
await client.v1.subscriptionGroups.update(group.id, { isActive: false });
```

`subscriptionGroups.delete` is only for a group that nothing depends on. It returns `409` while a Scheduled, Running, Paused or Broadcast Journey uses the group, or while the group holds anyone's subscribe or unsubscribe choice, because deleting it would erase those choices. Hide the group instead.

## Required scopes

* `subscription-groups:read` - list and retrieve subscription groups.
* `subscription-groups:write` - create, update and delete subscription groups.

To read one person's subscriptions, use `profiles.getSubscriptions`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.