Definition:

The "List Gmail Labels" action retrieves a list of Gmail labels associated with a user's account. It provides key information about each label, including its name, visibility settings, and message/thread counts. This action allows administrators to manage and track labels within Google Workspace accounts, helping with organization, filtering, and categorization of emails. Key capabilities include filtering labels by user, excluding system default labels, and viewing message and thread counts for each label.

Example Use cases

1. Organizing Email Labels in Bulk
This action can be used to retrieve all the labels in a user's Gmail account, enabling bulk management or reporting of labels for large numbers of users within a Google Workspace domain.

2. Label Management for Users
Administrators can use this action to retrieve and review labels in order to perform cleanup tasks, such as identifying unused labels, removing or renaming them, or updating visibility settings for better organization.

3. Monitoring Unread Messages
By checking unread messages and threads associated with specific labels, administrators can monitor important labels for active communication, ensuring critical topics are being addressed or followed up.

4. Excluding System Labels for Customization
If an administrator wants to exclude Gmail's default system labels (such as Inbox, Sent, etc.), they can use the option to exclude system default labels. This helps focus on custom or user-created labels for organizational purposes.

5. Reporting on Label Utilization
This action can be used to generate reports on label usage, including the number of messages and threads associated with each label. This helps assess the importance or effectiveness of specific labels for users within a domain.

Inputs

1. Connection
This refers to the Google Workspace Administration connection that must be set up for accessing the Gmail data. To establish this connection, a service account with domain-wide delegation is required. Users must upload a credential JSON file for authentication. A guide for creating the necessary credentials can be found here.

2. User Email
This field requires the email address of the user whose Gmail labels you want to retrieve. The email address is necessary to identify the specific user's Gmail account in the Google Workspace domain.

3. Exclude System Default Labels
This is an optional field. When turned on (set to true), it excludes all system-generated Gmail labels such as "Inbox," "Sent," and "Trash" from the results. This is useful when you want to focus solely on custom labels created by the user or organization. If turned off (set to false or left blank), all labels, including system default ones, will be included in the results.

Outputs

This retrieves a list of labels, where each label includes details as described in the following sections.

1. Label Id
The immutable ID assigned to the label by Gmail. This ID is unique and cannot be changed, serving as a permanent reference for the label in the system.

2. Name
The display name of the label. This is the human-readable name that is shown in the Gmail web interface, allowing users to identify the label.

3. Type
The owner type for the label. This field specifies whether the label is applied to an individual user's account or is managed at the domain level (such as admin-managed labels for the organization).

4. Message List Visibility
Indicates the visibility of the label in the message list in the Gmail web interface. This field shows whether messages with the label are visible in the user’s message list. Possible values include "show" or "hide."

5. Label List Visibility
Indicates the visibility of the label in the label list in the Gmail web interface. This field controls whether the label appears in the left-side panel where all labels are listed. It can be set to "show" or "hide."

6. Messages Total
The total number of messages that are tagged with this label. This count includes all messages within the label, regardless of whether they are read or unread.

7. Messages Unread
The number of unread messages within this label. This count helps track how many unread emails are categorized under the given label.

8. Threads Total
The total number of threads (email conversations) that have this label applied to them. Threads group related messages in Gmail, and this field provides the total number of such threads under the label.

9. Threads Unread
The number of unread email threads under the specified label. This indicates how many conversations are still marked as unread within the label.

Example of using

Imagine you're an IT administrator managing a team in your organization. You want to monitor and track the various email labels that are used across your team’s Gmail accounts. You want to retrieve and review the labels applied to emails to ensure the correct organization and categorization of emails.

To set this up, you would use the "List Gmail Labels" action. Here's a step-by-step example:

1. Connection Setup: First, create a Google Workspace Administration connection by uploading the credentials JSON file for the service account. You can follow the guide to ensure that the connection is established with domain-wide delegation enabled.

2. User Email: Provide the email address of the user whose labels you want to retrieve. This can be any user in your domain, such as "[email protected]."

3. Exclude System Default Labels: If you want to exclude Gmail’s system default labels (like "Inbox," "Sent," or "Spam"), turn on this option. This will focus only on custom labels that your organization uses for categorization.

4. Retrieve Data: Once the action is set, it will retrieve a list of labels for the specified user, along with key data such as:

   • The label’s ID and name
   • Whether the label is visible in the message list or label list
   • The number of unread messages and threads under that label

By using this action, you can easily audit and manage Gmail labels across the organization, ensuring emails are categorized effectively and consistently.