Manage groups

This page is about how to manage Google Groups with the Directory API:

  • Create a group
  • Update a group
  • Add a group alias
  • Retrieve a group
  • Retrieve all groups for a domain or the account
  • Retrieve all groups for a member
  • Retrieve all group aliases
  • Delete a group alias
  • Delete a group

Create a group

To create a group, use the following POST request and include the authorization described in Authorize requests. You can create a group for any domain associated with the account. For the query strings, request, and response properties, see the groups.insert method. 

POST https://admin.googleapis.com/admin/directory/v1/groups

The following JSON request shows a sample request body that creates a group. The group's email address is sales_group@example.com: 

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

A successful response returns an HTTP 201 status code and the properties for the new group.

Update a group

To update a group's settings, use the following PUT request and include the authorization described in Authorize requests. The groupKey is the group's email address, any of the group alias's email address, or the group's unique id. For the query strings, request, and response properties, see the groups.update method. 

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey

In general, Google recommends to not use the group's email address as a key for persistent data because the email address is subject to change.

In the following example, the unique groupKey is nnn and the group's name is APAC Sales Group: 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

For an update request, you only need to submit the updated information in your request. You don't need to enter all of the group's properties in the request.

A successful response returns an HTTP 201 status code and the properties for the new group: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

Add a group alias

To add a group alias, use the following POST request and include the authorization described in Authorize requests. The groupKey is the group's email address, any of the group alias' email address, or the group's unique id. For the query strings, request, and response properties, see the groups resource. 

POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

In general, Google recommends to not use the group's email address as a key for persistent data because the email address is subject to change.

The following JSON request shows a sample request to create a group's alias. The groupKey is group's unique id represented by NNNN

POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases

{
    "alias": "best_sales_group@example.com"
}

A successful response returns an HTTP 201 status code and the properties for the new group alias.

Retrieve a group

To retrieve a group, use the following GET request and include the authorization described in Authorize requests. The groupKey is the group's email address, any of the group alias' email address, or the group's unique id. For the query strings, request, and response properties, see the groups.get method. 
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

In general, Google recommends to not use the group's email address as a key for persistent data because the email address is subject to change.

In the following example, the unique groupKey ID is nnnn: 

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

A successful response returns an HTTP 200 status code and the group's settings: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "liz@test.com"
     }
    ]
}

Retrieve all groups for a domain or the account

To retrieve all groups for a specific domain or the account, use the following GET request and include the authorization described in Authorize requests. For the query strings, request, and response properties, see the groups.list method. For readability, this example uses line returns: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

When retrieving all groups for a domain or the account, consider the following:

  • All groups for a sub-domain: Use the domain argument with the domain's name.
  • All groups for the account: Use the customer argument with either my_customer or the account's customerId value. As an account administrator, use the string my_customer to represent your account's customerId. If you're a reseller accessing a resold customer's account, use the resold account's customerId. For the customerId value use the account's primary domain name in the Retrieve all users in a domain operation's request. The resulting response has the customerId value.
  • Using both the domain and customer arguments: The Directory API returns all the groups for the domain.
  • Not using the domain and customer arguments: The Directory API returns all the groups for the account associated with my_customer. This is the account customerId of the administrator making the request.
  • Using both the customer and userKey arguments: The Directory API returns an error. You must make two separate requests with these arguments.

In the following example, an account administrator uses my_customer to request a list all of an account's groups:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2

In the following example, a reseller administrator's request returns all groups for the resold account with the customerId C03az79cb. The maximum results returned per response page is 2. There is a nextPageToken for the follow-on list of users in this response: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2

A successful response returns an HTTP 200 status code and the groups in the alphabetical order of the group email: 

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support@sales.com",
      "name": "Sales support",
      "directMembersCount": "6",
      "description": "The sales support group",
      "adminCreated": true
     },
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "travel@sales.com",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "best_sales_group@example.com"
       }
      ],
      "nonEditableAliases: [
       {
         "alias": "liz@test.com"
       }
      ]
     },
  "nextPageToken": "NNNN"
  }

Retrieve all groups for a member

To retrieve all groups for which a member has a subscription, use the following GET request and include the authorization described in Authorize requests. For readability, this example uses line returns: 

GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key
?pageToken=pagination token
&maxResults=maximum results per response page
  • A member can either be a user or a group.
  • The userKey can be the user's primary email address, the user's alias email address, a group's primary email address, a group's email alias, or the user's unique id which can be found using the Retrieve a user operation.
  • The user or group specified in the userKey must belong to your domain.
  • Use the pageToken query string for responses with large number of groups. In the case of pagination, the response returns the nextPageToken property which gives a token for the next page of response results. Your next request uses this token as the pageToken query string value.
  • Using both the customer and userKey arguments: The Directory API returns an error. You must make two separate requests with these arguments.

For the request and response properties, see the groups.list method.

A successful response returns an HTTP 200 status code and the list of member information:

  • All groups for which a member has a subscription, including groups from outside of the user's domain, are returned.
  • The groups are returned in the alphabetical order of each group's email address.
  • In the body of the response, the id is the group's unique ID.
  • In the response, the listing of a group from outside of the user's domain doesn't include the outside group's aliases. 
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "sales_group@example.com",
      "name": "sale group",
      "directMembersCount": "5",
      "description": "Sales group"
     },
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support_group.com",
      "name": "support group",
      "directMembersCount": "5",
      "description": "Support group"
     }
  ],
   "nextPakeToken": "NNNNN"
}

Retrieve all group aliases

To retrieve all of a group's aliases, use the following GET request and include the authorization described in Authorize requests. The groupKey can be the group's primary email address, the group's unique id, or any of the group aliases' emails. For the request and response properties, see the groups resource. 

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

A successful response returns an HTTP 201 status code and a list of the group's aliases.

Delete a group alias

To delete a group's alias, use the following DELETE request and include the authorization described in Authorize requests. The groupKey can be the group's primary email address, the group's unique id, or any of the group aliases' emails. The aliasId is the alias being deleted. For the request and response properties, see the groups resource: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId

A successful response returns an HTTP 201 status code.

Delete a group

To delete a group, use the following DELETE request and include the authorization described in Authorize requests. The groupKey is the group's unique id: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
For example, this DELETE request deletes the group which has the nnnn group id: 
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

A successful response returns an HTTP 200 status code.

When a group is deleted, the following happens:

  • All members of the group are deleted. The member's user accounts aren't deleted.
  • The group archive is deleted.
  • Messages sent to the deleted group's address aren't delivered. Instead, the sender receives a bounce message.