Skip to content
Nappai Documentation

Gmail Webhook

The Gmail Webhook component acts as the entry point for your automation workflows when you need to react to activity in your Gmail account. Instead of manually checking for emails, this component sits quietly and waits for signals from Google. When a specific event occurs—such as receiving a new message, deleting an email, or changing a label—it captures that data and transforms it into a structured format that other parts of your Nappai automation can understand and use.

Think of this component as a “smart listener.” You tell it which types of emails or labels to pay attention to, and it notifies your workflow whenever those conditions are met.

How it Works

This component integrates directly with the Google Gmail API. It does not send emails; instead, it receives information about changes in your mailbox.

  1. Listening: The component is configured to “listen” for specific triggers based on the settings you choose (see below).
  2. Detection: When you receive an email, move it to a folder, or delete it, Gmail’s system sends a signal to the Nappai platform.
  3. Processing: The component takes this raw signal and extracts useful details, such as the sender’s name, the subject line, the date, and any labels applied (like “Inbox” or “Starred”).
  4. Output: It packages this information into a clean data structure. You can then send this data to AI models (LLMs) to draft replies, save it to a database, or trigger other automated tasks.

Connection & Credentials

This component requires a valid connection to your Google Account to access email data securely.

This component requires configuring a credential in the Nappai panel before interacting with the external service:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential of the type Google Gmail and fill in the required fields (Select Project, Client Id, Client Secret, and Google drive access). You can find these details in the Google Cloud Console.
  3. In your workflow, select the saved credential in the Credential input field of this node.

Inputs

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

  • Events: Specifies which Gmail history events to listen for. Defaults to Message Added if none selected.
    • Visible in: [All Operations]
  • Label Filters: Gmail labels to monitor. Defaults to INBOX if none selected.
    • Visible in: [All Operations]

Outputs

The component produces structured data about the Gmail activity it detected. This output is essential for downstream steps in your workflow, such as generating an AI response or updating a spreadsheet.

Output Data Example (JSON)

Below is an example of the structured data produced when a new email is received (Message Added). You can use the fields listed here in subsequent nodes: json { “text”: “[messageAdded] Re: Project Update from alice@example.com”, “data”: { “id”: “183920192810293”, “threadId”: “15f23948574857”, “from”: “alice@example.com”, “to”: [“bob@yourcompany.com”], “subject”: “Re: Project Update”, “date”: “2023-10-27T14:30:00Z”, “snippet”: “Hi Bob, I have reviewed the attached files…”, “labelIds”: [“INBOX”, “UNREAD”, “IMPORTANT”], “eventType”: “messageAdded” } }

  • text: A human-readable summary of the event (e.g., “New email from Alice”).
  • data: A detailed dictionary containing the specific metadata of the email (Sender, Subject, ID, Date, Labels, etc.).

Connectivity

This component is typically placed at the start of a workflow as a trigger or input node.

  • Connects to: AI Assistant / LLM Nodes: Send the email data to an AI to analyze sentiment, draft a reply, or summarize the content.
  • Connects to: Database / Spreadsheet Nodes: Save the sender, subject, and date to a CRM or log.
  • Connects to: Filter / Logic Nodes: Use the “Label Filters” or “Events” data to decide if a specific action should be taken (e.g., only process emails marked as “Important”).

Usage Example

Scenario: Automatically draft replies to important emails received in your Inbox.

  1. Configure the Gmail Webhook component:
    • Events: Select Message Added.
    • Label Filters: Select INBOX and IMPORTANT.
  2. Connect the Output of this component to an AI Prompt node.
  3. In the AI Prompt, instruct the AI: “Use the email content from the input to draft a polite acknowledgment reply.”
  4. Connect the AI output to a Send Email component (if available) or save it for review.

Now, every time an email arrives in your Inbox that is marked as Important, the system will automatically generate a draft reply for you.

Tips and Best Practices

  • Be Specific with Labels: If you monitor too many labels (e.g., “All Mail”), your workflow might trigger for irrelevant data. It is best practice to only monitor INBOX, STARRED, or custom labels you create specifically for automation.
  • Use “Message Added” for New Emails: This is the most common event. Use it when you want to react to incoming mail.
  • Understanding “Message Deleted”: This event only triggers when a message is permanently deleted from the Trash. Simply moving an email to the Trash does not trigger this; it triggers a “Label Removed” event.
  • Label Changes vs. Deletion: Moving an email to Trash or Starring it changes its labels. These are captured as Label Added or Label Removed, not as Message Deleted.

Security Considerations

  • Credential Security: Never share your Client Id or Client Secret directly in workflow text or public templates. Always use the Nappai Credential system to manage these secrets securely.
  • Data Privacy: Be aware that this component gives access to the raw content of emails and metadata. Ensure your workflow complies with your organization’s data privacy policies when handling sender information and email bodies.