Gmail Labels Sync

A Google Sheet that syncs your Gmail labels and provides cascading/dependent dropdowns for organizing email categorization.

Overview

This sheet creates a separate spreadsheet from the Gmail Inbox Sorter with two main tabs:

1. Labels (Reference/Master Sheet)

   • Contains all Gmail label combinations: Type, Category, Originator, and Full Gmail Label Path
   • Populated automatically from your Gmail labels via Apps Script
   • Source of truth for cascading dropdown options

2. Working (Data Entry Sheet)

   • Where you enter email addresses and use cascading dropdowns
   • Columns: Email Address, Type, Category, Originator, Notes
   • Dropdowns auto-filter:
     • Select Type → Category dropdown shows only categories under that Type
     • Select Type + Category → Originator dropdown shows only originators under that combo

How It Works

Cascading Dropdowns

Google Sheets natively supports dropdowns via data validation, but they can't filter dynamically. This sheet uses Apps Script to simulate cascading dropdowns:

1. When you change the Type dropdown in a row, the script recalculates valid categories
2. When you change the Category, the script recalculates valid originators
3. Only values that actually exist in your Gmail labels appear in the dropdowns

Label Format Requirement

Your Gmail labels must follow a three-level hierarchy:

Type/Category/Originator

Examples:

• Newsletters/Clothes/H&M
• Newsletters/Clothes/UNIQLO
• Notifications/Travel/Uber
• Promotions/Tech/Amazon

The script will ignore:

• System labels (INBOX, SENT, DRAFT, SPAM, etc.)
• Labels starting with [
• Labels with fewer than 3 levels

Setup

1. Create the Spreadsheet

cd /home/chromium/workspace/google/gmail-labels-sync
node scripts/create-sheet.js

This will:

• Create a new Google Sheet called "Gmail Labels Sync"
• Set up two tabs: Labels and Working
• Output the Spreadsheet ID

2. Save the Spreadsheet ID

Copy the output ID and save it:

# Option A: Set as environment variable
export LABELS_SYNC_SPREADSHEET_ID=your_id_here

# Option B: Update config.js directly
# Edit config.js and replace the empty string with your ID

3. Run the Setup Script

LABELS_SYNC_SPREADSHEET_ID=your_id_here node scripts/setup-labels-sync.js

This will:

• Add headers to both sheets
• Format headers (bold, centered, frozen)
• Write the Apps Script code to a file (Code.gs)

4. Deploy Apps Script

In your new Google Sheet:

1. Go to Extensions > Apps Script
2. In the Apps Script editor, replace all code with the contents of Code.gs
3. Click Save
4. Grant the required permissions when prompted (Gmail & Spreadsheet access)

Alternatively, if you have the Apps Script API set up, you could automate this deployment—let me know if you'd like that.

5. Sync Your Labels

In the Google Sheet:

1. Click the "Gmail Labels" menu (should appear after reload)
2. Select "Sync Gmail Labels"
3. The script will pull your Gmail labels and populate the Labels sheet

6. Start Using It

In the Working sheet:

1. Add email addresses in column A
2. Click on column B (Type) and select from the dropdown
3. Column C (Category) will auto-filter to show only options for that Type
4. Column D (Originator) will auto-filter to show only options for that Type + Category

Available Menu Functions

Sync Gmail Labels

• Pulls all 3-level labels from Gmail
• Populates the Labels sheet with Type/Category/Originator combos
• Automatically updates all dropdowns after sync

Update Dropdowns

• Manually recalculate cascading dropdowns for all rows
• Use if you add new rows or want to re-sync without pulling from Gmail

Clear All Data

• Clears all data from the Working sheet (keeps headers)
• Asks for confirmation

Files

• config.js — Project configuration (IDs, headers, column counts)
• scripts/create-sheet.js — Creates a new spreadsheet via the Sheets API
• scripts/setup-labels-sync.js — Sets up headers, formatting, and Apps Script
• Code.gs — Generated Apps Script code (don't edit by hand)
• README.md — This file

Formatting

Matches the Gmail Inbox Sorter standards:

• Headers: Bold, centered, frozen at row 1
• Columns: A-E (maximum width)
• Data rows: Minimum 20 rows (keeps space for new entries)
• Font: Default (inherited)

Troubleshooting

"No connections found" when creating sheet

You need to authorize Google first:

1. Go to your local Nango instance (http://localhost:3004 or configured URL)
2. Add a new connection for Google
3. Complete the OAuth flow
4. Then re-run create-sheet.js

Dropdowns not filtering

• Check that your Gmail labels follow the Type/Category/Originator format
• Run "Sync Gmail Labels" again from the menu
• Manually run "Update Dropdowns" to recalculate

Apps Script won't deploy

• Make sure you pasted all the code (check line count matches Code.gs)
• Grant permissions when prompted
• Try the inline deployment via menu instead of manual copy-paste

Integration with Gmail Inbox Sorter

This is a separate sheet from the Gmail Inbox Sorter. You can:

• Use both sheets side-by-side
• Reference the same Gmail label hierarchy
• Keep different types of data in each:
  • Inbox Sorter: Email senders and their sort rules
  • Labels Sync: Generic label mapping and cascading UI

They don't interfere with each other—both use the same Google OAuth connection via Nango.

Next Steps

After setup:

1. Go to your Gmail and organize labels into 3-level hierarchy (if not already)
2. Sync the labels into the sheet
3. Start using the Working sheet to categorize emails
4. Optionally: integrate with Gmail filter creation (for future enhancement)

---

Created with: Google Sheets API, Apps Script, and Nango proxy