Skip to main content
POST
curl

Authorizations

Authorization
string
header
required

A key generated from Settings → Developers, sent as Authorization: Bearer dr_live_<12 hex chars>_<64 hex chars>. Keys carry explicit scopes — each endpoint states the one it requires. The full key is shown exactly once at generation time and cannot be retrieved again; only the keyId prefix is shown afterward. A revoked key fails auth on its very next request.

Headers

Idempotency-Key
string
required

A unique client-generated string (≤ 255 characters) identifying this create attempt. See "Idempotency" above.

Maximum string length: 255

Body

application/json
name
string
required

The group name. It is trimmed and Unicode-normalized (NFC), then must be 1-100 characters and must not contain a NUL character. Names are not unique.

Required string length: 1 - 100
Example:

"Newsletter readers, still active"

filter
object
required

The rule that decides who is in a group. A contact is in the group when it matches conditions (joined by operator), matches every condition in requiredConditions, and matches none of excludeConditions. Each list holds at most 20 conditions, and at least one condition is needed across the three lists (otherwise 422 EMPTY_FILTER). Unsubscribed contacts are never members. See Group conditions.

Response

The group was created. memberCount is the live count at creation.

A group with its rule and its live member count. Never any member data.

id
string<uuid>
required

The group id.

name
string
required

The group name.

filter
object
required

A saved rule exactly as it is stored, which is what GET /api/preview/segments/{id} returns. Unlike GroupFilter (what you may send) it has no limit on the length of a list, and its conditions can be of any type (StoredGroupCondition), because a saved group is not held to the API's rules. A group stored without a rule comes back as {}.

memberCount
integer
required

The live number of contacts in the group now (never unsubscribed contacts). A count only; the contacts themselves are never returned.

Required range: x >= 0
createdAt
string<date-time>
required

When the group was created, RFC 3339 in UTC.