Gmail Auto-Labeling Workflow

https://www.loom.com/share/11c40099ac0d42eab6e5e23c79dca40bwww.loom.com

1. Use Case Description

Problem: Email inbox chaos - hundreds of emails piling up without organization, making it difficult to find important messages and reducing productivity.

Solution: An AI-powered workflow that automatically categorizes emails by:

Reading email content
Analyzing with AI (GPT-4o-mini)
Automatically applying the appropriate Gmail label

Source: This workflow was ported from N8N to AgenticFlow.

N8N Template: Basic Automatic Gmail Email Labelling with OpenAI and Gmail API

2. Goal

✅ Automatically categorize emails based on content
✅ Use AI to determine the most appropriate label
✅ Apply existing Gmail labels
✅ Keep inbox clean and organized

3. Use Cases & Triggers

When to Use?

Use Case

Description

Manual

Run manually when you want to label a specific email

Batch

Label multiple emails at once

Auto (Webhook)

Automatically trigger when new email arrives (requires Pub/Sub setup)

Trigger Options

Option 1: Manual Run

Open workflow → Enter email subject → Click Run

Option 2: Webhook + Gmail Push (Auto)

Gmail receives new email → Pub/Sub → Webhook → Workflow runs automatically
See Webhook setup instructions below

4. Workflow Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                        Gmail Auto-Labeling Agent                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Input: email_subject                                                       │
│           │                                                                 │
│           ▼                                                                 │
│  ┌─────────────────────────────────────┐                                   │
│  │ Step 1: Get All Gmail Labels        │                                   │
│  │ Action: gmail-list-labels           │                                   │
│  └─────────────────────────────────────┘                                   │
│           │                                                                 │
│           ▼                                                                 │
│  ┌─────────────────────────────────────┐                                   │
│  │ Step 2: Search & Get Email          │                                   │
│  │ Action: gmail-search-emails         │                                   │
│  └─────────────────────────────────────┘                                   │
│           │                                                                 │
│           ▼                                                                 │
│  ┌─────────────────────────────────────┐                                   │
│  │ Step 3: AI Decides Label            │                                   │
│  │ Model: GPT-4o-mini                  │                                   │
│  └─────────────────────────────────────┘                                   │
│           │                                                                 │
│           ▼                                                                 │
│  ┌─────────────────────────────────────┐                                   │
│  │ Step 4: Apply Label to Email        │                                   │
│  │ Action: gmail-add-label-to-email    │                                   │
│  └─────────────────────────────────────┘                                   │
│           │                                                                 │
│           ▼                                                                 │
│  Output: status, applied_label, result                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

5. Workflow Link

AgenticFlow Workflow: 👉 https://agenticflow.ai/app/workspaces/30f2b04d-294f-4110-bf7e-4d405f2bea0c/workflows/6e17510a-16e5-4d43-9595-7b703620d38b/run

6. How to Use

Step 1: Open Workflow

Access the workflow link above

Step 2: Enter Email Subject

Open Gmail → Find the email you want to label
Copy the subject of that email
Paste into the "Email Subject" field in the workflow

Example:

[Agenticflow] Your CX Agent is Ready! Let's Bring It to Life 🚀

Step 3: Run Workflow

Click the "Run" button

Step 4: Check Results

View workflow output
Open Gmail → Verify the email has been labeled

7. N8N Workflow JSON (Source)

Link: https://n8n.io/workflows/2740-basic-automatic-gmail-email-labelling-with-openai-and-gmail-api/

{
  "nodes": [
    {
      "id": "2a41e2da-19f7-4c31-ab93-3a534db3179e",
      "name": "Gmail Trigger",
      "type": "n8n-nodes-base.gmailTrigger",
      "position": [-360, -260],
      "parameters": {
        "filters": {},
        "pollTimes": {
          "item": [
            {
              "mode": "everyX",
              "unit": "minutes",
              "value": 5
            }
          ]
        }
      },
      "typeVersion": 1.2
    },
    {
      "id": "a25e0e42-8eab-49c5-a553-797da40eb623",
      "name": "OpenAI Chat Model1",
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "position": [-220, -60],
      "parameters": {
        "options": {
          "maxTokens": 4096
        }
      },
      "typeVersion": 1
    },
    {
      "id": "cf437748-a0df-42a2-b1ca-f93162d85bfe",
      "name": "Gmail - read labels",
      "type": "n8n-nodes-base.gmailTool",
      "position": [80, -40],
      "parameters": {
        "resource": "label",
        "returnAll": true,
        "descriptionType": "manual",
        "toolDescription": "Tool to read all existing gmail labels"
      },
      "typeVersion": 2.1
    },
    {
      "id": "152f1970-7a1f-4977-9c21-64b69242d3a9",
      "name": "Gmail - get message",
      "type": "n8n-nodes-base.gmailTool",
      "position": [260, -40],
      "parameters": {
        "messageId": "={{ $fromAI('gmail_message_id', 'id of the gmail message', 'string') }}",
        "operation": "get",
        "descriptionType": "manual",
        "toolDescription": "Tool to read a specific message based on the message ID"
      },
      "typeVersion": 2.1
    },
    {
      "id": "ae09cedc-9675-4080-bcdc-3d6c4e4bc490",
      "name": "Gmail - add label to message",
      "type": "n8n-nodes-base.gmailTool",
      "position": [460, -40],
      "parameters": {
        "labelIds": "={{ $fromAI('gmail_categories', 'array of label ids') }}",
        "messageId": "={{ $fromAI('gmail_message_id') }}",
        "operation": "addLabels",
        "descriptionType": "manual",
        "toolDescription": "Tool to add label to message"
      },
      "typeVersion": 2.1
    },
    {
      "id": "be4a92ab-d3ab-451b-8655-172851f68628",
      "name": "Gmail - create label",
      "type": "n8n-nodes-base.gmailTool",
      "position": [640, -40],
      "parameters": {
        "name": "={{ $fromAI('new_label_name', 'new label name', 'string') }}",
        "resource": "label",
        "operation": "create",
        "descriptionType": "manual",
        "toolDescription": "Tool to create a new label, only use if label does not already exist"
      },
      "typeVersion": 2.1
    },
    {
      "id": "a40466d2-2fe3-4a97-98fe-b14cc38cc141",
      "name": "Gmail labelling agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "position": [-60, -260],
      "parameters": {
        "text": "=Label the email based on the details below:\n{{ JSON.stringify($json) }}",
        "options": {
          "maxIterations": 5,
          "systemMessage": "Objective: Automatically categorize incoming emails based on existing Gmail labels or create a new label if none match..."
        },
        "promptType": "define"
      },
      "typeVersion": 1.7
    }
  ],
  "connections": {
    "Gmail Trigger": {
      "main": [[{"node": "Wait", "type": "main", "index": 0}]]
    },
    "OpenAI Chat Model1": {
      "ai_languageModel": [[{"node": "Gmail labelling agent", "type": "ai_languageModel", "index": 0}]]
    },
    "Gmail - get message": {
      "ai_tool": [[{"node": "Gmail labelling agent", "type": "ai_tool", "index": 0}]]
    },
    "Gmail - read labels": {
      "ai_tool": [[{"node": "Gmail labelling agent", "type": "ai_tool", "index": 0}]]
    },
    "Gmail - create label": {
      "ai_tool": [[{"node": "Gmail labelling agent", "type": "ai_tool", "index": 0}]]
    },
    "Gmail - add label to message": {
      "ai_tool": [[{"node": "Gmail labelling agent", "type": "ai_tool", "index": 0}]]
    }
  }
}

8. Node Mapping: N8N → AgenticFlow

N8N Node

AgenticFlow Equivalent

Gmail Trigger

Webhook Trigger + Pub/Sub (or Manual)

Gmail - read labels

MCP: gmail-list-labels

Gmail - get message

MCP: gmail-search-emails

OpenAI Chat Model

Ask AI (llm) node - GPT-4o-mini

Gmail - add label to message

MCP: gmail-add-label-to-email

Gmail - create label

(Not implemented)

9. Debugging Guide

Error 1: "Authentication failed: OAuth token expired"

Cause: Gmail MCP connection has expired

Solution:

Go to AgenticFlow → Connections
Find your Gmail connection
Click "Reconnect" or "Re-authorize"
Sign in again with your Google account

Error 2: "Invalid id value" or "Thread ID invalid"

Cause: Using wrong type of ID

Solution:

Use Email Subject instead of Message ID
Workflow has been updated to use gmail-search-emails with subject

Error 3: "Error parsing arguments: instruction required"

Cause: MCP action missing instruction field

Solution:

Ensure each MCP action has instruction field in input_params
Example:

{
  "action": "gmail-list-labels",
  "input_params": {
    "instruction": "List all my Gmail labels with their IDs"
  }
}

Error 4: Email not labeled

Possible causes:

Subject doesn't match exactly
Label ID doesn't exist

Solution:

Check Step 2 output - was the email found?
Check Step 3 output - what label_id did AI return?
Verify label_id exists in Step 1 output

Error 5: Workflow doesn't auto-trigger

Cause: Webhook + Gmail Push not configured

Solution: See "Auto Trigger Setup" section below

10. Auto Trigger Setup (Optional)

To make the workflow run automatically when new emails arrive:

Step 1: Create Google Cloud Project

Go to console.cloud.google.com
Create a new project
Enable Gmail API and Pub/Sub API

Step 2: Create Pub/Sub Topic

Go to Pub/Sub → Create Topic: gmail-notifications
Add permission for [email protected] with role Pub/Sub Publisher

Step 3: Create Webhook Trigger in AgenticFlow

Open workflow → "Triggers" tab
Create Trigger → Webhook
Copy the Webhook URL

Step 4: Create Push Subscription

Go to Pub/Sub → Create Subscription
Select topic gmail-notifications
Delivery type: Push
Endpoint URL: Paste AgenticFlow Webhook URL

Step 5: Activate Gmail Watch

Go to OAuth Playground
Authorize Gmail API scope: https://mail.google.com/
Send POST request:

URL: https://gmail.googleapis.com/gmail/v1/users/me/watch
Body:
{
  "topicName": "projects/YOUR_PROJECT_ID/topics/gmail-notifications",
  "labelIds": ["INBOX"]
}

⚠️ Note: Gmail Watch expires after 7 days and needs periodic renewal.

11. Output Schema

{
  "status": "completed",
  "applied_label": "CATEGORY_UPDATES",
  "email_found": "{ email content... }",
  "labels_available": "{ list of labels... }",
  "result": "{ apply label result... }"
}

12. Summary

Item

Value

Workflow Name

Gmail Auto-Labeling Agent

Source

N8N Template #2740

AI Model

GPT-4o-mini

Input

Email Subject

Output

Label applied to email

MCP Connection

Gmail ()

Setup Time

~5 min (manual) / ~30 min (auto trigger)

13. Links

Resource

URL

AgenticFlow Workflow

Open Workflow

N8N Template

N8N #2740

Gmail API Docs

developers.google.com/gmail/api

AgenticFlow Docs

docs.agenticflow.ai

PreviousPersonal Productivity NextWorkforce

Last updated 13 days ago

hashtag1. Use Case Description

hashtag2. Goal

hashtag3. Use Cases & Triggers

hashtagWhen to Use?

hashtagTrigger Options

hashtag4. Workflow Architecture

hashtag5. Workflow Link

hashtag6. How to Use

hashtagStep 1: Open Workflow

hashtagStep 2: Enter Email Subject

hashtagStep 3: Run Workflow

hashtagStep 4: Check Results

hashtag7. N8N Workflow JSON (Source)

hashtag8. Node Mapping: N8N → AgenticFlow

hashtag9. Debugging Guide

hashtagError 1: "Authentication failed: OAuth token expired"

hashtagError 2: "Invalid id value" or "Thread ID invalid"

hashtagError 3: "Error parsing arguments: instruction required"

hashtagError 4: Email not labeled

hashtagError 5: Workflow doesn't auto-trigger

hashtag10. Auto Trigger Setup (Optional)

hashtagStep 1: Create Google Cloud Project

hashtagStep 2: Create Pub/Sub Topic

hashtagStep 3: Create Webhook Trigger in AgenticFlow

hashtagStep 4: Create Push Subscription

hashtagStep 5: Activate Gmail Watch

hashtag11. Output Schema

hashtag12. Summary

hashtag13. Links

1. Use Case Description

2. Goal

3. Use Cases & Triggers

When to Use?

Trigger Options

4. Workflow Architecture

5. Workflow Link

6. How to Use

Step 1: Open Workflow

Step 2: Enter Email Subject

Step 3: Run Workflow

Step 4: Check Results

7. N8N Workflow JSON (Source)

8. Node Mapping: N8N → AgenticFlow

9. Debugging Guide

Error 1: "Authentication failed: OAuth token expired"

Error 2: "Invalid id value" or "Thread ID invalid"

Error 3: "Error parsing arguments: instruction required"

Error 4: Email not labeled

Error 5: Workflow doesn't auto-trigger

10. Auto Trigger Setup (Optional)

Step 1: Create Google Cloud Project

Step 2: Create Pub/Sub Topic

Step 3: Create Webhook Trigger in AgenticFlow

Step 4: Create Push Subscription

Step 5: Activate Gmail Watch

11. Output Schema

12. Summary

13. Links