# Gmail Auto-Labeling Workflow ### 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: 1. Reading email content 2. Analyzing with AI (GPT-4o-mini) 3. 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](https://n8n.io/workflows/2740-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:** 👉 *** ### 6. How to Use #### Step 1: Open Workflow Access the workflow link above #### Step 2: Enter Email Subject 1. Open Gmail → Find the email you want to label 2. **Copy the subject** of that email 3. 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:** ``` { "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:** 1. Go to AgenticFlow → Connections 2. Find your Gmail connection 3. Click **"Reconnect"** or **"Re-authorize"** 4. 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:** 1. Check Step 2 output - was the email found? 2. Check Step 3 output - what label\_id did AI return? 3. 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 1. Go to [console.cloud.google.com](https://console.cloud.google.com/) 2. Create a new project 3. Enable **Gmail API** and **Pub/Sub API** #### Step 2: Create Pub/Sub Topic 1. Go to Pub/Sub → Create Topic: `gmail-notifications` 2. Add permission for `gmail-api-push@system.gserviceaccount.com` with role `Pub/Sub Publisher` #### Step 3: Create Webhook Trigger in AgenticFlow 1. Open workflow → "Triggers" tab 2. Create Trigger → Webhook 3. Copy the Webhook URL #### Step 4: Create Push Subscription 1. Go to Pub/Sub → Create Subscription 2. Select topic `gmail-notifications` 3. Delivery type: **Push** 4. Endpoint URL: Paste AgenticFlow Webhook URL #### Step 5: Activate Gmail Watch 1. Go to [OAuth Playground](https://developers.google.com/oauthplayground/) 2. Authorize Gmail API scope: `https://mail.google.com/` 3. 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](https://agenticflow.ai/app/workspaces/30f2b04d-294f-4110-bf7e-4d405f2bea0c/workflows/6e17510a-16e5-4d43-9595-7b703620d38b/run) | | **N8N Template** | [N8N #2740](https://n8n.io/workflows/2740-basic-automatic-gmail-email-labelling-with-openai-and-gmail-api/) | | **Gmail API Docs** | [developers.google.com/gmail/api](https://developers.google.com/gmail/api) | | **AgenticFlow Docs** | [docs.agenticflow.ai](https://docs.agenticflow.ai/) | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.agenticflow.ai/use-cases/workflow/personal-productivity/gmail-auto-labeling-agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.