Managing contacts for notifications

Many Google Cloud services, such as Cloud Billing, send out notifications to share important information with Google Cloud users. By default, these notifications are sent to members with certain Identity and Access Management (IAM) roles. With Essential Contacts, you can customize who receives notifications by providing your own list of contacts.

Before you begin

Enable the Essential Contacts API.

Enable the API

Required permissions

The permissions that you need to use Essential Contacts vary depending on what you want to do.

Permissions to view contacts

To view contacts, you need a role that includes the following permissions:

  • essentialcontacts.contacts.get
  • essentialcontacts.contacts.list

To gain these permissions while following the principle of least privilege, ask your administrator to grant you the Essential Contacts Viewer role (roles/essentialcontacts.viewer).

Alternatively, your administrator can grant you a different role with the required permissions, such as a custom role or a more permissive predefined role.

Make sure to grant these roles on the project, folder, or organization where the contact is assigned.

Permissions to manage contacts

To edit, delete, and create contacts, you need a role that includes the following permissions:

  • essentialcontacts.contacts.get
  • essentialcontacts.contacts.list
  • essentialcontacts.contacts.create
  • essentialcontacts.contacts.delete
  • essentialcontacts.contacts.update

To gain these permissions while following the principle of least privilege, ask your administrator to grant you the Essential Contacts Admin role (roles/essentialcontacts.admin).

Alternatively, your administrator can grant you a different role with the required permissions, such as a custom role or a more permissive predefined role.

Make sure to grant these roles on the project, folder, or organization where the contact is assigned.

Notification categories

There are several different categories of notifications that you can assign contacts for. If you don't add a contact for a category, notifications in that category go to the default contact, which is selected based on your members' IAM roles. We recommend adding custom contacts, and not relying on default contacts, to help ensure that the correct people receive notifications for your project, folder, or organization.

You can add both individuals and Google groups as contacts. To reduce the impact of personnel changes, we recommend adding Google groups as contacts, then managing the membership of those groups to determine who receives notifications. This practice helps ensure that notifications always go to active employees.

Review the following table to learn about the categories of notifications, the default contact, and the recommended contact. Use this information to select appropriate contacts for each category.

Category Description Default contact Recommended contact
All All notifications related to the resource None People or automated systems that are responsible for routing or logging notifications
Billing Billing and payments notifications, price updates, errors, credits Billing Account Administrator (roles/billing.admin) Finance department staff and people who manage your financial relationship with Google, including people who manage budgets, planning, and accounts related to Google Cloud usage
Legal Enforcement actions, regulatory compliance, government notices Billing Account Administrator (roles/billing.admin) Legal counsel, compliance managers, government relations specialists, and other related professionals
Product updates New versions, product terms updates, deprecations Project Owner (roles/owner) Product managers, architects, and engineers who can benefit from timely information about changes to Google products and services
Security Security/privacy issues, notifications, and vulnerabilities Organization Administrator (roles/resourcemanager.organizationAdmin) IT security, operations security, and other people whose job it is to safeguard your company and customer data and ensure business continuity
Suspension Notifications related to immediate account suspension Project Owner (roles/owner) People immediately responsible for keeping your IT infrastructure and business applications up and running
Technical Outages, errors, bugs, and other technical issues Project Owner (roles/owner) IT professionals, reliability engineers, admins, on-call lists, and other people who need to know of current and upcoming technical issues and events that may cause your IT assets to work incorrectly

Supported languages

In Essential Contacts, each contact has preferred language setting. Notification creators can reference this setting when sending notifications.

When you add a contact in the Cloud Console, the Cloud Console automatically configures the contact's preferred language based on the contact creator's preferred language settings. When you add a contact using the API, you manually configure the contact's preferred language using a language code. This language code can refer to any of the languages that Essential Contacts supports.

Deciding where to assign contacts

You can assign contacts at the project, folder, or organization level.

Contacts are inherited through the Google Cloud resource hierarchy. As a result, if you add a contact at the organization level, they receive notifications for the organization and for all folders and projects in the organization. Similarly, if you add a contact at the folder level, they receive notifications for the folder and for all folders and projects in the folder.

Where you decide to assign contacts depends on the structure of your organization. However, we generally recommend assigning contacts at the following levels, based on their notification category:

Recommended level Notification category
Organization level
  • Billing
  • Legal
  • Security1
Folder/project level
  • All
  • Product updates
  • Security1
  • Suspension
  • Technical

1 The level at which you should assign security contacts depends on your organization's specific security practices. For example, if individual project owners are in charge of security for their own projects, you would assign your security contacts at the project level. However, if an organization-wide group manages security for all projects, you would assign your security contacts at the organization level.

Listing contacts

To list all contacts in your project, folder, or organization, do the following:

Console

  1. In the Cloud Console, go to the Essential contacts page.

    Go to the Essential contacts page

  2. Make sure the name of your project, folder, or organization appears in the project selector at the top of the page. The project selector tells you what project, folder, or organization you are currently managing contacts for.

  3. To list the contacts by category, select Category. To list the contacts alphabetically, select Contacts.

REST

Listing contacts

To view the contacts that have been set on a specific project, folder, or organization, use the Essential Contacts API's contacts.list method.

Before using any of the request data below, make the following replacements:

  • RESOURCE_TYPE: The resource type that you want to list contacts for. Use the value projects, folders, or organizations.
  • RESOURCE_ID: Your Google Cloud project, organization, or folder ID.
  • PAGE_SIZE: Optional. The number of contacts to include in the response. The default value is 50, and the maximum value is 100. If the number of contacts is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
  • NEXT_PAGE_TOKEN: Optional. The pagination token returned in an earlier response from this method. If specified, the list of contacts starts where the previous response ended.

Request:

GET essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "contacts": [
    {
      "name": "projects/my-projects/contacts/1",
      "email": "my-contact-1@my-domain.com",
      "notificationCategorySubscriptions": [
        "ALL"
      ],
      "languageTag": "en-US"
    },
    {
      "name": "projects/my-projects/contacts/2",
      "email": "my-contact-2@my-domain.com",
      "notificationCategorySubscriptions": [
        "BILLING"
      ],
      "languageTag": "en-US"
    }
  ]
}

Listing contacts and inherited contacts

Child resources (folders and projects) inherit contacts from their ancestors (organizations and other folders). If you want to list all contacts and inherited contacts for a resource, use the Essential Contacts API's contacts.compute method.

Before using any of the request data below, make the following replacements:

  • RESOURCE_TYPE: The resource type that you want to compute contacts for. Use the value projects, folders, or organizations.
  • RESOURCE_ID: Your Google Cloud project, organization, or folder ID.
  • NOTIFICATION_CATEGORY: The categories of notifications that you want to compute contacts for. You can repeat this field to list contacts for multiple notification categories. The NOTIFICATION_CATEGORY can be any of the following values: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL, and NOTIFICATION_CATEGORY_UNSPECIFIED. Choosing a value of ALL lists contacts for all categories.
  • PAGE_SIZE: Optional. The number of contacts to include in the response. The default value is 50, and the maximum value is 100. If the number of contacts is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
  • NEXT_PAGE_TOKEN: Optional. The pagination token returned in an earlier response from this method. If specified, the list of contacts starts where the previous response ended.

Request:

GET essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts:compute?notificationCategories=NOTIFICATION_CATEGORY&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

To send your request, expand one of these options:

The response lists all contacts and inherited contacts for the resource:

{
  "contacts": [
    {
      "name": "projects/my-projects/contacts/1",
      "email": "my-project-contact-1@my-domain.com",
      "notificationCategorySubscriptions": [
        "ALL"
      ],
      "languageTag": "en-US"
    },
    {
      "name": "projects/my-projects/contacts/2",
      "email": "my-project-contact-2@my-domain.com",
      "notificationCategorySubscriptions": [
        "BILLING"
      ],
      "languageTag": "en-US"
    },
    {
      "name": "organizations/my-organization/contacts/1",
      "email": "my-organization-contact@my-domain.com",
      "notificationCategorySubscriptions": [
        "ALL"
      ],
      "languageTag": "en-US"
    }
  ]
}

Managing individual contacts

You can manage individual contacts on the Essential contacts page in the Cloud Console, or by using the REST API.

Adding a contact

To add a contact, do the following:

Console

  1. In the Cloud Console, go to the Essential contacts page.

    Go to the Essential contacts page

  2. Make sure the name of your project, folder, or organization appears in the project selector at the top of the page. The project selector tells you what project, folder, or organization you are currently managing contacts for.

  3. Click Add contact.

  4. In the Email and Confirm email fields, enter the email address of the contact.

  5. From the Notification categories drop-down menu, select the notification categories that you want the contact to receive communications for. For a list of notification categories and recommended contacts, see Identifying contacts on this page.

  6. Click Save.

REST

To add a new contact, use the Essential Contacts API's contacts.create method.

Before using any of the request data below, make the following replacements:

  • RESOURCE_TYPE: The resource type that you want to list contacts for. Use the value projects, folders, or organizations.
  • RESOURCE_ID: Your Google Cloud project, organization, or folder ID.
  • EMAIL: The email address of your contact. You cannot change this field after you create your contact.
  • NOTIFICATION_CATEGORY_1 and NOTIFICATION_CATEGORY_2: The notification categories that you want the contact to receive communications for. This value can be any of the following: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL.

    For a list of recommended contacts for each category, see Identifying contacts on this page.

  • LANGUAGE: The language code for your contact's preferred notification language. You can include the language code of any of the supported languages.

Request:

POST essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts

Request body:

{
  "email": "EMAIL",
  "notificationCategorySubscriptions": [
    "NOTIFICATION_CATEGORY_1",
    "NOTIFICATION_CATEGORY_2"
  ],
  "languageTag": "LANGUAGE"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/my-project/contacts/3",
  "email": "my-new-contact@my-domain.com",
  "notificationCategorySubscriptions": [
    "SUSPENSION",
    "TECHNICAL"
  ],
  "languageTag": "en"
}

Changing a contact

To change which categories a contact is assigned to, do the following:

Console

  1. In the Cloud Console, go to the Essential contacts page.

    Go to the Essential contacts page

  2. Make sure the name of your project, folder, or organization appears in the project selector at the top of the page. The project selector tells you what project, folder, or organization you are currently managing contacts for.

  3. Next to View by, select Contact.

  4. Click next to the contact whose category you want to change.

  5. Select the notification categories you want from the Notification categories drop-down menu and click Save.

REST

To change the notification subscriptions or preferred language of an existing contact, use the Essential Contacts API's contacts.patch method.

Before using any of the request data below, make the following replacements:

  • RESOURCE_TYPE: The resource type that you want to list contacts for. Use the value projects, folders, or organizations.
  • RESOURCE_ID: Your Google Cloud project, organization, or folder ID.
  • CONTACT_ID: The numeric ID of your contact. To see the IDs of all contacts in your project, folder, or organization, list your contacts.
  • UPDATE_MASK: Optional. A mask describing which fields of the contact you've changed. The format for the mask is a comma-separated list of fully qualified names of fields, for example: notificationCategorySubscriptions,languageTag.
  • EMAIL: The email address of your contact. This field must match the email address associated with the CONTACT_ID that you include in the request.
  • NOTIFICATION_CATEGORY_1 and NOTIFICATION_CATEGORY_2: Optional. The updated notification categories that you want the contact to receive communications for. This value can be any of the following: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL.

    For a list of recommended contacts for each category, see Identifying contacts on this page.

  • LANGUAGE: The language code for the contact's preferred notification language. You can include the language code of any of the supported languages.

Request:

PATCH essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_ID?updateMask="UPDATE_MASK"

Request body:

{
  "name": "RESOURCE_TYPE/RESOURCE_ID/contact/CONTACT_ID",
  "email": "EMAIL",
  "notificationCategorySubscriptions": [
    "NOTIFICATION_CATEGORY_1",
    "NOTIFICATION_CATEGORY_2"
  ],
  "languageTag": "LANGUAGE"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/my-project/contacts/2",
  "email": "my-new-contact@my-domain.com",
  "notificationCategorySubscriptions": [
    "ALL"
  ],
  "languageTag": "en"
}

Deleting a contact

To delete a contact, do the following:

Console

  1. In the Cloud Console, go to the Essential contacts page.

    Go to the Essential contacts page

  2. Make sure the name of your project, folder, or organization appears in the project selector at the top of the page. The project selector tells you what project, folder, or organization you are currently managing contacts for.

  3. Next to View by, select Contact.

  4. Click next to that email address of the contact you want to delete. The, in the dialog, confirm that you want to delete the contact.

REST

To delete a contact, use the Essential Contacts API's contacts.delete method.

Before using any of the request data below, make the following replacements:

  • RESOURCE_TYPE: The resource type that you want to list contacts for. Use the value projects, folders, or organizations.
  • RESOURCE_ID: Your Google Cloud project, organization, or folder ID.
  • CONTACT_ID: The numeric ID of your contact. To see the IDs of all contacts in your project, folder, or organization, list your contacts.

Request:

DELETE essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_ID

To send your request, expand one of these options:

If the request is successful, the response body will be empty.

Managing contacts by category

In the Cloud Console, you can also manage contacts by category by going to the Category tab on the Essential contacts page.

To add, change, or delete the contacts assigned to a single category, do the following:

  1. In the Cloud Console, go to the Essential contacts page.

    Go to the Essential contacts page

  2. Make sure the name of your project, folder, or organization appears in the project selector at the top of the page. The project selector tells you what project, folder, or organization you are currently managing contacts for.

  3. Next to View by, select Category.

  4. Click in the same row as the category whose contacts you want to manage.

  5. Manage the contacts assigned to the category:

    • To add a new contact, click Add contact, then follow the steps to add a contact described on this page.
    • To change which category a contact is assigned to, click next to the contact whose category you want to change. Then, select the notification categories you want from the Notification categories drop-down menu and click Save.

    • To delete a contact, click next to that contact's email address.

What's next