Managing Groups with the REST API

Overview

Three endpoints let you work with groups programmatically: you can list the groups of your customer account, check whether a group is currently locked by a running operation, and delete groups.

Endpoint	Purpose
GET /group/find	Returns a paginated list of groups with filtering and sorting.
GET /group/getLockStatus	Returns the lock status of a single group.
POST /group/delete	Deletes one or more groups by ID.

All three endpoints require API version v19 or later. The version is part of the base URL, for example https://email.yourdomain.com/api/rest/v19. For authentication and base URL, see Getting Started with Engage API.

All date and time values returned by these endpoints are Unix timestamps in milliseconds.

Finding Groups

GET /group/find returns a page of groups. Unbounded listing is not supported, so paging always applies. With no parameters, the endpoint returns the first 25 groups sorted by name in ascending order.

Query Parameters

All parameters are optional.

Parameter	Type	Description
nameFilter	String	Returns groups whose name or email address contains this text. The match is case-insensitive.
groupCategoryId	Long	Returns only groups assigned to this group category.
status	String	`active` or `archived`. Omit the parameter to return both.
groupType	String	`regular` or `super`. Omit the parameter to return both.
sortBy	String	Field to sort by: `name`, `email`, `creationDate`, `memberCount`, `messageCount`, `groupCategory` or `id`. Default is `name`. Sorting by `groupCategory` sorts by the category label, not by its ID.
sortOrder	String	`asc` or `desc`. Default is `asc`.
page	Integer	Page to return, counted from 1. Default is 1.
limit	Integer	Number of groups per page. Default is 25, the maximum is 500.

Filters are combined with AND. An invalid value for status, groupType, sortBy or sortOrder, a page below 1, or a limit outside the permitted range returns HTTP 400.

Response

The response contains the list of groups in groups, together with page and limit as they were applied, and totalCount, the number of groups matching the filters across all pages.

Each entry in groups contains the following fields:

Field	Type	Description
id	Long	Unique ID of the group.
name	String	Display name of the group.
email	String	Sender email address of the group.
description	String	Description stored with the group.
groupCategoryId	Long	ID of the group category assigned to the group.
groupCategoryLabel	String	Display name of that group category.
archived	Boolean	True when the group is archived.
isSuperGroup	Boolean	True when the group is a SuperGroup.
creationDate	Long	When the group was created, as a Unix timestamp in milliseconds.
memberCount	Long	Number of members in the group. Can be `null`, see the note below.
messageCount	Long	Number of messages sent to the group. Can be `null`, see the note below.
ownerId	Long	ID of the system user who owns the group.
isoCountryCode	String	Country code configured for the group.
isoLanguageCode	String	Language code configured for the group.
messageCategoryId	Long	ID of the message category assigned to the group.

Member statistics can be switched off. When member statistics are skipped for your customer account, memberCount and messageCount are returned as null. Treat both fields as nullable in your integration.

What the Endpoint Returns

Deleted groups are never returned.
Results depend on the permissions of the API user. A user without the permission to view all groups sees only the groups they own or moderate. Groups of other customer accounts are never returned.
The endpoint returns a summary per group, not the full configuration. To read all settings of a single group, use GET /group/get. To read group attributes, use GET /group/getAttributes.

Checking Whether a Group Is Locked

GET /group/getLockStatus takes a single required parameter, groupId, and returns the current lock status of that group.

Mapp Engage locks a group while an operation writes to it or reads from it, so that conflicting processes cannot run at the same time. For the two lock types and what they block, see Group Locks.

Response

Field	Type	Description
groupId	Long	ID of the group you asked about.
locked	Boolean	True while an operation holds a lock on the group.
lockType	String	`EXCLUSIVE` or `SHARED`.
lockedBy	String	Identifier of the operation that holds the lock.
lockReason	String	Why the group is locked. See the table below.
since	Long	When the lock was created, as a Unix timestamp in milliseconds.
lastAccessed	Long	When the lock was last accessed, as a Unix timestamp in milliseconds.

When the group is not locked, locked is false and all other fields except groupId are null.

Lock Reasons

Value	Meaning
`TRANSFER_SELECTION`	A segment transfer is writing contacts to the group.
`IMPORT`	A contact import is running on the group.
`SENDOUT`	A sendout is using the group.
`DELETE_GROUP`	The group is being deleted.
`BLACKLIST`	A blacklist operation is running on the group.
`OTHER`	Another operation holds the lock.

Using the Lock Status

A group stays locked until the operation that locked it has finished. A response with locked: true is therefore a reliable signal that an operation is still running. During a segment transfer, for example, the endpoint returns locked: true, lockType: EXCLUSIVE and lockReason: TRANSFER_SELECTION.

The endpoint tells you whether an operation is running, not how far it has progressed. For progress, poll GET /process/getDetails with the process ID that the transfer endpoint returned.

An invalid group ID returns HTTP 400. A group that does not exist or does not belong to your customer account returns HTTP 404.

Deleting Groups

POST /group/delete takes a non-empty list of group IDs in the request body and deletes them immediately. Scheduled deletion is not supported.

The endpoint follows the same batch pattern as POST /group/archive and POST /group/activate: you receive one result per ID, and a failure for one group does not stop the others from being processed. An empty or missing list returns HTTP 400.

Results

Each result contains entityKey with the group ID, a code, and a message with further details.

Code	Meaning
`OK`	The group was deleted.
`NO_SUCH_OBJECT`	No group with this ID exists, or it does not belong to your customer account.
`PERMISSION_DENIED`	The API user is not permitted to delete this group.
`GROUP_LOCKED`	An operation currently holds a lock on the group. The group was not deleted.
`HAS_ACTIVE_REFERENCES`	An active scheduled message task still references the group. The group was not deleted.
`INVALID_PARAMETER`	The value is not a valid group ID.
`UNEXPECTED_ERROR`	The deletion failed for another reason. See `message` for details.

Evaluate the result for every ID you sent. A group that returns HAS_ACTIVE_REFERENCES or GROUP_LOCKED still exists.

What Deletion Affects

Deleting a group does more than remove the group itself. References that do not block the deletion are adjusted: scheduled tasks, event rules and whiteboards that use the group are deactivated, and prepared messages that use it are deleted. For the complete behaviour, see References to the Group.

A campaign can be deleted with the group. A campaign that belongs to the group is deleted together with it, including its statistics, unless the campaign has been marked beforehand. The Group endpoints do not return the associated campaign or its state, so an API client cannot check this in advance. Do not delete a group whose campaigns, prepared messages or statistics you still need.

Typical Sequence

A common use case is cleaning up groups that a programmatic segment transfer created on the fly.

Call GET /group/find to locate the groups, for example with nameFilter and groupCategoryId.
Call GET /group/getLockStatus for each group you intend to delete. A group that a transfer is still writing to cannot be deleted.
Send the IDs of the unlocked groups to POST /group/delete.
Evaluate every result. Retry the groups that returned GROUP_LOCKED once their operation has finished.