Link Menu Expand (external link) Document Search Copy Copied
This website is for Zenphi public documentation.

List User's Gmail Messages

Definition

The List User’s Gmail Messages action allows you to retrieve a collection of email messages and their associated metadata from a specific user’s Gmail account within your Google Workspace organization.

Unlike standard Gmail actions that require the user to log in themselves, this action is designed for administrative tasks. It uses a service account with domain-wide authority, enabling you to search and list emails from any user’s mailbox without needing their direct credentials.

Key capabilities include:

  • Domain-Wide Search: Querying any managed user’s mailbox using standard Gmail search syntax (e.g., by sender, date, or keyword).
  • Compliance Filtering: Filtering results based on specific Label IDs or including content from Spam and Trash for complete visibility.
  • Detailed Metadata: Retrieving comprehensive message details, including headers, snippets, and attachment information.

This action is essential for automating compliance audits, archiving employee data during offboarding, and managing bulk email cleanup workflows.

Inputs

  1. Connection
    • Purpose: Establishes the link between Zenphi and your Google Workspace environment.
    • Requirement: You must select a connection that has Domain-Wide Delegation enabled. A standard user-level Gmail connection will not work here.
  2. User Email
    • Purpose: Specifies the target mailbox you wish to search.
    • Practical Guidance:
    • Static: Type the full email address (e.g., audit@company.com) for fixed workflows.
    • Dynamic: Use the token picker to select an email address from a previous step, such as a “Get User” action or a “Departing Employee” form trigger.
  3. Search Query
    • Purpose: Filters the messages returned based on specific criteria.
    • Practical Guidance: It supports standard Gmail search syntax.
    • Example: is:unread (Finds unread emails).
    • Example: from:client@domain.com has:attachment (Finds emails from a client with files).
    • Dynamic: You can build queries using tokens, e.g., "subject:" + [Project Name Token].
  4. Label IDs
    • Purpose: Filters the results to only include messages that possess all of the specified Label IDs.
    • Practical Guidance: Provide a comma-separated list of IDs (e.g., INBOX, SENT) or map a collection from a previous step. Leave empty to ignore labels.
  5. Include Spam and Trash Messages
    • Purpose: Determines whether the search scope includes the Spam and Trash folders.
    • Default: False (Excluded).
    • Use Case: Set to True during forensic audits to ensure no relevant emails are missed, even if the user deleted them.
  6. Max Results
    • Purpose: Limits the number of messages returned in a single execution.
    • Range: Enter a number between 1 and 500.
    • Recommendation: Set this to 100 to process emails in manageable batches.
  7. Next Page Token
    • Purpose: Used for pagination to retrieve the next set of results.
    • Practical Guidance: Leave empty for the first run. To get subsequent pages, map the “Next Page Token” output from the previous execution of this action inside a loop.

How the “Search Query” Works

The Search Query input acts as a filter. Instead of retrieving every email in a user’s mailbox (which could be thousands), it only returns the specific messages that match your string.

It supports Boolean Logic (AND, OR, NOT) and Key:Value pairs.

1. The Basics (Who and What)

  • Sender: from:amy@acme.com
  • Recipient: to:finance@acme.com
  • Subject: subject:Invoice

  • Note: If your subject has spaces, wrap it in quotes: subject:"Weekly Report"

  • Anywhere: meeting (Searches subject, body, and sender for the word “meeting”).

2. Attributes (Status and Content)

  • Unread: is:unread
  • Starred: is:starred
  • Has Attachment: has:attachment
  • Specific File Type: filename:pdf or filename:xlsx
  • Example: has:attachment filename:pdf (Finds emails with PDF attachments).

3. Time-Based Filtering (Crucial for Automation)

This is the most important category for Zenphi flows. You usually want to process “emails from the last 24 hours” rather than the last 10 years.

  • After a date: after:2023/12/31
  • Before a date: before:2024/01/01
  • Relative Time: older_than:2d (Older than 2 days) or newer_than:1h (Newer than 1 hour).
  • d = day, m = month, y = year

4. Combining Logic (AND / OR / NOT)

  • AND (Space): Just typing a space acts as an “AND”.

  • from:amy is:unread (Must be from Amy AND be unread).

  • OR: Use OR in capital letters (or { }).

  • from:amy OR from:bob (From either Amy or Bob).

  • NOT (Minus sign): Use a - to exclude things.
  • from:amy -subject:lunch (From Amy, but ignore emails about “lunch”).

How to use this in Zenphi (Dynamic Queries)

The real power comes when you combine these text operators with Zenphi Tokens.

Scenario: You want to find all emails from a specific client (whose email you got from a Form) that contain the word “Contract”.

How to build the string in the Input Field: You would use the String Composition (concatenation) method in the expression editor, or simply type the static parts and insert the token.

Visual Representation: from: [Client Email Token] ` subject:Contract`

  • Step 1: Type from:
  • Step 2: Insert the token (e.g., ``)
  • Step 3: Type a space (for AND)
  • Step 4: Type subject:Contract

Result sent to Google: from:client@gmail.com subject:Contract

️ Common Pitfalls (Best Practices)

  1. Spaces in Labels/Subjects: If you search for a label with a space, like “Project Alpha”, you must use quotes.
    • Wrong: label:Project Alpha (Searches for label “Project” AND the word “Alpha”).
    • Correct: label:"Project Alpha".
  2. Date Formats: Google strictly uses YYYY/MM/DD. If you map a date token from a system that uses DD/MM/YYYY, the search will fail or return wrong results. You may need to format the date token first.
  3. Special Characters: Some symbols (/, &, ()) can confuse the search parser. If searching for exact strings with symbols, wrap them in quotes.

Outputs

  1. Messages A list of message objects. Each item contains metadata about a specific email:
    • Message Id / Thread Id: Unique identifiers.
    • Snippet: A short text preview of the message body.
    • Internal Date: The timestamp of the message.
    • Label IDs: List of tags applied to this message.
    • Headers: (From, To, Cc, Bcc, Subject, Date, Reply-To).
    • Size Estimate: Approximate size in bytes.
    • Attachments: A nested list of attachment details (Filename, MIME Type, Size, Attachment ID).
    • Note: This action returns metadata. To download the actual file content or read the full HTML body, you must pass the Message Id to a “Get User’s Gmail Message” action.
  2. Next Page Token
    • A string token used to retrieve the next page of results. If empty/null, there are no more messages to list.
  3. Items Count
    • The total number of messages returned in the current batch. Useful for “If” conditions (e.g., If Items Count > 0).

Example Use Cases

  1. Automate Employee Offboarding: Retrieve all emails from a departing employee’s account to archive critical correspondence or transfer ownership of ongoing threads.
  2. Conduct Compliance Audits: Search across specific user mailboxes for emails containing sensitive keywords, financial terms, or internal labels.
  3. Manage Storage: Identify emails older than a specific date or exceeding a certain size to trigger automated cleanup workflows.
  4. Monitor Vendor Communication: List messages sent to or received from specific external domains to track contract negotiations.

Example Scenario: The Compliance Audit

Goal: An HR manager submits a “Offboarding Request” for a departing employee. To ensure compliance, the Legal team needs a report of all external communications regarding “Contracts” sent by this employee in the last 30 days.

Steps to Implement:

  1. Trigger: Google Form - New Response (captures the Employee Email).
  2. Action: List User’s Gmail Messages.
    • Connection: Workspace Admin (Domain-Wide).
    • User Email: Map the Employee Email from the form.
    • Search Query: subject:Contract after:2023/12/01 (Finds emails with “Contract” in the subject sent after a specific date).
    • Include Spam/Trash: True (To catch deleted items).
  3. Action: For Each Item (Loop).
    • Iterate through the list of found messages.
  4. Action (Inside Loop): Google Sheets - Add Row.
    • Log the Subject, Date, Sender, and Snippet into a “Compliance Audit Log” spreadsheet.

Outcome: The flow automatically generates a comprehensive audit trail of all contract-related communications, allowing the Legal team to review activity without manually searching the user’s mailbox.

Best Practices

  1. Optimize Search Queries: Use precise Gmail search syntax (e.g., after:2024/01/01 or has:attachment) in the Search Query field. Filtering at the source is much faster than filtering inside your flow.
  2. Implement Pagination: If you expect more than 500 emails, wrap this action in a loop and use the Next Page Token to fetch subsequent batches. Relying on a single run may result in missing data.
  3. Verify Connection Scopes: Ensure your connection has Domain-Wide Delegation. Without this, the action will fail with “Unauthorized” errors when trying to access another user’s mailbox.