Skip to main content
POST
Create subscription group

Authorizations

x-api-key
string
header
required

Unified API key for server-side SDK and API integrations

Body

application/json
name
string
required
description
string

Shown to customers on the email preferences page.

type
enum<string>
default:OptIn

Defaults to OptIn. OptIn: only people who joined get this group's emails. OptOut: everyone counts as subscribed until they unsubscribe, so marketing email usually needs a clear yes first.

Available options:
OptIn,
OptOut
channel
enum<string>
default:Email

Message delivery channel (Email only for MVP)

Available options:
Email

Response

Default Response

id
string<uuid>
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
name
string
required
description
string | null
required
type
enum<string>
required

OptIn: only people who joined get this group's emails. OptOut: everyone counts as subscribed until they unsubscribe, so marketing email usually needs a clear yes first.

Available options:
OptIn,
OptOut
channel
enum<string>
required

Message delivery channel (Email only for MVP)

Available options:
Email
isActive
boolean
required

Whether the group is visible on the email preferences page. A hidden group is paused for new sends: new Journeys, Newsletters and AI drafts can't use it.

isDefault
boolean
required

Default groups keep their name, because imports, Shopify consent sync and campaign drafts find them by name.

createdAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$