Skip to main content
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.

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.
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.