Directory API: Groups

Create a group Update a group Add a group alias Retrieve a group Retrieve all groups for a domain or 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. A group can be created for any domain associated with the account. For the query strings, request, and response properties, see the API Reference:

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

JSON request

The following JSON request shows a sample request body that creates a group. The group's email address is [e-mail]:

{
   "email": "[e-mail]",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

A successful response returns an HTTP 201 status code. Along with the status code, the response returns the properties for the new group.

Note: A newly created group does not have any members. You must call the Add a member to a group to add members to a new group. In addition, your client must wait a minute before adding a member or sending a message to a newly created 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 API Reference:

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 since the email address is subject to change.

JSON request

In the example below, the unique groupKey is 'nnn' and the group's name has been changed to APAC Sales Group:

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

{
    "email": "[e-mail]",
    "name": "APAC Sales Group"
}

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

Note:The API also supports the patch semantics.

JSON response

A successful response returns an HTTP 201 status code. Along with the status code, the response returns the properties for the new group.

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "[e-mail]",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "[e-mail]"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "[e-mail]"
     }
    ]
}

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 API Reference:

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 since the email address is subject to change.

JSON request

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": "[e-mail]"
}

JSON response

A successful response returns an HTTP 201 status code. Along with the status code, the response returns 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 API Reference:

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 since the email address is subject to change.

In the example below, the unique groupKey ID is 'nnnn':

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

JSON response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the group's settings:

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "[e-mail]",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "[e-mail]"
     }
    ],
    "nonEditableAliases: [
     {
        "alias": "[e-mail]"
     }
    ]
}

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 API Reference. 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 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 are 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 domain and customer arguments — The API returns all the groups for the domain.
• Not using the domain and customer arguments — The API returns all the groups for the account associated with my_customer. This is the account customerId of the administrator making the API request.

In this 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 this 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

JSON response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the groups in the alphabetical order of the group email and is case insensitive:

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "[e-mail]",
      "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": "[e-mail]",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "[e-mail]"
       }
      ],
      "nonEditableAliases: [
       {
         "alias": "[e-mail]"
       }
      ]
     },
  "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.

For the request and response properties, see the API Reference.

JSON response

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 does not include the outside group's aliases.

{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "[e-mail]",
      "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 API Reference:

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

Note: These are editable group aliases in the account's primary domain or subdomains. For group aliases outside of the account, see the group's nonEditableAliases property.

A successful response returns an HTTP 201 status code. Along with the status code, the response returns 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 API Reference:

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:

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