Google Gmail Thread

Google Gmail Thread is a component that lets you work with Gmail conversations (threads) directly from your Nappai dashboard.
You can read threads, add or remove labels, delete them, or move them to trash—all without leaving the platform.

How it Works

When you use this component, Nappai talks to the Google Gmail API.
It sends the request you configure (e.g., “Get Thread” or “Modify Label in Thread”) and receives the data back.
If you enable Mapping Mode, the component can handle many records at once, so you can process a whole batch of threads in one go.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

Modify Label in Thread: Add or remove labels on a specific thread.
Delete Thread: Permanently delete a thread from your Gmail account.
Get Thread: Retrieve information about one or more threads.
Trash Thread: Move a thread to the Trash folder.

To use the component, first select the operation you need in the Operation field.

Inputs

Mapping Mode

This component has a special mode called Mapping Mode. When you enable this mode using the toggle switch, an additional input called Mapping Data is activated, and each input field offers you three different ways to provide data:

Fixed: You type the value directly into the field.
Mapped: You connect the output of another component to use its result as the value.
Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Credential

Before you can use the component, you must set up a GMail credential in the Nappai Credentials section.
After that, select the credential you created in the Credential field of this component.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

Operation: Select the operation you want to perform.
- Visible in: Modify Label in Thread, Delete Thread, Get Thread, Trash Thread
Labels: Labels to filter emails. You can use multiple labels.
- Visible in: Modify Label in Thread, Get Thread
Select Action (Modify Label in Thread): Select the action that you want to perform to the label of the thread.
- Visible in: Modify Label in Thread
Mapping Mode: Enable mapping mode to process multiple data records in batch.
- Visible in: Modify Label in Thread, Delete Thread, Get Thread, Trash Thread
Number of Emails to read: Number of emails to read. If left empty, it will read 10 threads by default.
- Visible in: Get Thread
Query: Query to filter emails. With this query you can filter the emails that you want to read if the message contains the query.
- Visible in: Get Thread
Thread Id: Id of the thread. If not provided in get threads, it will return all the threads.
- Visible in: Modify Label in Thread, Delete Thread, Get Thread, Trash Thread
Select Action (Trash Thread): Select the action that you want to perform to the thread.
- Visible in: Trash Thread
Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
- Visible in: Modify Label in Thread, Delete Thread, Get Thread, Trash Thread
Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
- Visible in: Modify Label in Thread, Delete Thread, Get Thread, Trash Thread
Tools arguments metadata: Defines the arguments metadata for the tools.
- Visible in: Modify Label in Thread, Delete Thread, Get Thread, Trash Thread

Outputs

Data: The raw data returned from the Gmail API (e.g., thread details).
Tool: A tool representation that can be used by Nappai agents to perform the selected operation.

Usage Example

Scenario: You want to read the latest 5 threads that contain the word “Invoice” and add the label “Finance” to each of them.

Drag the Google Gmail Thread component onto the canvas.
Set Operation to Get Thread.
In Query, type Invoice.
Set Number of Emails to read to 5.
Connect the output Data to a Loop component that iterates over each thread.
Inside the loop, add another Google Gmail Thread component.
- Set Operation to Modify Label in Thread.
- Map Thread Id to the current thread’s ID from the loop.
- In Labels, add Finance.
- In Select Action, choose Add.
Run the workflow. The component will fetch the threads and add the label to each one.

Google Gmail Message Component – Works with individual emails instead of threads.
Google Gmail Label Component – Manage Gmail labels (create, delete, list).
Google Gmail Search Component – Search for emails using advanced Gmail search syntax.

Tips and Best Practices

Use Mapping Mode when you need to process many threads at once; it saves time and reduces API calls.
Keep your credentials secure: Never share the Client ID or Client Secret.
Test with a small number of threads first to ensure your filters and actions work as expected.
Use descriptive Tool Names so agents can easily understand what each tool does.
Check Gmail API quotas if you plan to run the component frequently; you might hit limits.

Security Considerations

The component uses a GMail credential that contains OAuth tokens. Store these tokens securely in Nappai’s credential store.
Only users with permission to the Gmail account can configure or run this component.
Avoid exposing the Credential field in public dashboards.
When using Mapping Mode, ensure that the data you map does not contain sensitive information that could be logged or exposed.