gmail-multi-inbox

Files (4)

• SKILL.md
• .gitignore · assets/
• .gitkeep · assets/
• gmail-multi-inbox-template.js · scripts/

SKILL.md (first lines)

# Gmail Multi-Inbox Setup & Maintenance

## Overview

Gmail's Multiple Inboxes displays up to 5 custom sections alongside the main inbox. Each section shows emails matching a search query. This skill uses a **label + filter** approach: label-based sections get Gmail filters that auto-label incoming mail by sender domain. The output is always a Google Apps Script the user pastes into script.google.com.

The generated script is idempotent — safe to re-run after adding or removing senders. When senders are removed from the lists, `setupAll()` automatically deletes the corresponding Gmail filters.

## Prerequisites

This skill requires a **Gmail MCP connector** (e.g. `search_gmail_messages`) to scan the user's inbox. Gmail does not have an official MCP server — the user must have a third-party Gmail connector configured. If no Gmail connector is available, the skill can still work in a limited way: skip the scanning steps and let the user provide sender domains manually, or import from an existing script.

## Configuration

The skill stores its current configuration in `assets/config.json` inside this skill's directory. This file tracks:
- The section definitions (name, query, label)
- The sender domains assigned to each label
- Timestamp of last scan

Always read `assets/config.json` before starting. If it exists, this is a returning user — go to Update Mode. If it doesn't exist, check if the user has an existing script (see Import Existing Script). Otherwise, this is a new user — go to Initial Setup.

## Import Existing Script

If the user already has a Gmail Multi-Inbox Apps Script (set up manually or from a previous run before config tracking existed), ask them to paste it. Parse the script to extract:

1. **Sender arrays** — find all `var xxxSenders = [...]` declarations, extract the domain lists and map each to its label name
2. **Labels** — find all `createLabelIfNeeded('...')` calls to identify the label names
3. **Section config** — find the `__MULTI_INBOX_CONFIG__` comment block or any section query/name comments

Build `assets/config.json` from the parsed data and confirm the reconstructed config with the user before proceeding to Update Mode.

## Initial Setup (New Users)

### Step 1: Scan Gmail

Search the user's Gmail history using `search_gmail_messages` to build a comprehensive picture of who emails them. Run multiple queries and merge the results — the goal is to discover **all** non-personal sender domains.

**Broad sweep (most important — do this first):**
- `newer_than:6m` — all emails from the last 6 months. Paginate through results to collect as many senders as possible.
- `newer_than:1m` — recent emails, captures current high-frequency senders

**Category-based (catches things the broad sweep may paginate past):**
- `category:promotions` — marketing, newsletters
- `category:updates` — notifications, shipping, orders
- `category:social` — social media notifications
- `category:forums` — mailing lists, digests

**Signal-based:**
- `unsubscribe` — anything with an unsubscribe link (broad, catches most automated mail)
- `from:noreply OR from:no-reply OR from:notifications OR from:info@` — automated senders

**Localized subject searches (adapt based on user's language):**
- `subject:order OR subject:invoice OR subject:receipt OR subject:shipping OR subject:confirmation`
- Czech: `subject:objednávka OR subject:faktura OR subject:potvrzení OR subject:doručení`

**Aggregate results:** collect all sender addresses, extract domains, group by domain, count frequency. Ignore generic providers (`gmail.com`, `outlook.com`, `yahoo.com`, `hotmail.com`, `icloud.com`, `seznam.cz`, etc.) — these are personal contacts, not automated senders.

### Step 2: Suggest Categories

Based on the scan results, propose up to 5 sections. Start with these defaults and adjust based on what the scan actually found:

| # | Name | Query | Label | Description |
|---|------|-------|-------|-------------|
| 1 | Important | `(is:starred OR is:important)` | *(none — query-based)* | Starred and important emails |
| 2 | Work | `label:work in:inbox` | `work` | Emails from the user's company domain |
| 3 | Newsletters | `label:newsletter in:inbox` | `newsletter` | Subscriptions, digests, marketing |
| 4 | Orders | `label:orders in:inbox` | `orders` | E-shops, shipping, travel, invoices |
| 5 | *(available)* | | | Suggest based on scan or leave empty |

Present the proposed sections with the discovered sender domains grouped under each category. Ask the user to:
- Confirm, rename, or remove sections
- Move misclassified domains between categories
- Add missing domains
- Name the work label after their actual company if applicable
- Choose label colors (suggest distinct, visually clear defaults). Only Gmail's predefined colors are allowed — see the list in Important Notes

For section 1 (Important): this is query-based, no label or filters needed.

### Step 3: Generate the Apps Script

Read the template from `scripts/gmail-multi-inbox-template.js` in this skill's directory.

Fill in the placeholders:
- `__SENDER_ARRAYS__` — one `var` array per label-based section with the confirmed sender domains
- `__LABEL_CONFIGS__` — `createLabelIfNeeded('labelname', { backgroundColor: '#hex', textColor: '#hex' })` calls for each label-based section. The color object is optional — if the section has a `color` in the config, pass it; otherwise omit the second argument. Only Gmail's predefined hex colors are allowed (see template comments).
- `__STALE_FILTER_CLEANUP__` — a `removeStaleFilters([...])` call listing all managed label/sender pairs. This lets the script detect and delete Gmail filters whose sender was removed from the lists. Example:
  ```
  removeStaleFilters([
    { senders: workSenders, label: 'work' },
    { senders: newsletterSenders, label: 'newsletter' }
  ]);
  ```
- `__FILTER_CREATION__` — for each label-based section: loop over its sender array calling `createFilterIfNeeded(sender, label)`. Do NOT include `retroLabel` calls here — those go in `__RETRO_LABEL__`.
- `__RETRO_LABEL__` — for each label-based section: call `retroLabel(senderArray, label)`. If the section has `matchToAndCc` in the config, pass it as `{ matchToAndCc: [...] }`. This is placed inside the separate `retroLabelAll()` function.
- `__MULTI_INBOX_CONFIG__` — comment block listing each section's query and name for the user to enter in Gmail Settings

Save the generated script as `assets/gmail-multi-inbox-setup.js` inside this skill's directory.

### Step 4: Save Configuration

Write `assets/config.json` with the full configuration:

```json
{
  "sections": [
    { "name": "Important", "query": "(is:starred OR is:important)", "label": null },
    { "name": "Work", "query": "label:work in:inbox", "label": "work", "senders": ["companydomain.com"], "matchToAndCc": ["companydomain.com"], "color": { "backgroundColor": "#4a86e8", "textColor": "#ffffff" } },
    { "name": "Newsletters", "query": "label:newsletter in:inbox", "label": "newsletter", "senders": ["substack.com", "beehiiv.com"], "color": { "backgroundColor": "#fad165", "textColor": "#000000" } },
    { "name": "Orders", "query": "label:orders in:inbox", "label": "orders", "senders": ["amazon.com", "ups.com"], "color": { "backgroundColor": "#16a766", "textColor": "#ffffff" } }
  ],
  "lastScan": "2026-02-18"
}
```

### Step 5: Provide Setup Instructions

Tell the user:

**Part A — Run the script:**

From apocohq/skills, MIT.

More from apocohq/skills