Sign in
API Reference

Recipient Groups

Organize recipients into named groups for bulk sends. Groups are org-scoped — any member of your organization can reference a group in an order.

GET /api/v1/recipient-groups

List recipient groups

Returns a paginated list of recipient groups in your organization.

Required scope

recipients.read

Query parameters

ParameterTypeRequiredDescription
pageintegerNoPage number (default 1)
pageSizeintegerNoResults per page, max 100 (default 20)
searchstringNoFilter by group name (partial match)
GET /api/v1/recipient-groups/{groupId}

Get recipient group

Returns the group object and its current member count.

Required scope

recipients.read

Path parameters

groupId
integer
Yes
The recipient group ID
POST /api/v1/recipient-groups

Create recipient group

Creates a new empty recipient group. Add members using the members endpoint.

Required scope

recipients.write

Request body

JSON
{
  "groupName": "US Sales Team"
}

Request body fields

Field
Type
Required
Description
groupName
string
Yes
Display name for the group. Must be unique within your organization.
PUT /api/v1/recipient-groups/{groupId}

Update recipient group

Renames the group. Does not affect members.

Required scope

recipients.write

Path parameters

groupId
integer
Yes
The recipient group ID

Request body

JSON
{
  "groupName": "APAC Sales Team"
}

Request body fields

Field
Type
Required
Description
groupName
string
Yes
New display name for the group
DELETE /api/v1/recipient-groups/{groupId}

Delete recipient group

Permanently deletes the group and removes all member associations. Recipients themselves are not deleted.

Caution: This action is irreversible. Any pending orders that reference this group by ID will not be affected, but new orders cannot reference a deleted group.

Required scope

recipients.write

Path parameters

groupId
integer
Yes
The recipient group ID
GET /api/v1/recipient-groups/{groupId}/members

List group members

Returns a paginated list of recipients that belong to this group.

Required scope

recipients.read

Path parameters

groupId
integer
Yes
The recipient group ID

Query parameters

ParameterTypeRequiredDescription
pageintegerNoPage number (default 1)
pageSizeintegerNoResults per page, max 100 (default 20)
POST /api/v1/recipient-groups/{groupId}/members

Add group members

Adds a recipient to the group by their ID. The recipient must belong to the same organization.

Required scope

recipients.write

Path parameters

groupId
integer
Yes
The recipient group ID

Request body

JSON
{
  "recipientId": "RE-A1B2C3D4"
}

Request body fields

Field
Type
Required
Description
recipientId
string
Yes
ID of the recipient to add. Must belong to the same organization.
DELETE /api/v1/recipient-groups/{groupId}/members/{recipientId}

Remove group member

Removes a single recipient from the group. The recipient record itself is not deleted.

Required scope

recipients.write

Path parameters

Parameter
Type
Required
Description
groupId
integer
Yes
The recipient group ID
recipientId
string
Yes
The recipient ID to remove