💡 New script: calendar-label-automator (custom label-driven event routing with the Calendar Labels API)

[github-actions[bot]]

Summary

A new automation script that leverages the Calendar custom labels/colors API (GA July 7, 2026) to let users define event routing rules based on custom label colors. Users color-code their calendar events by project or priority, and the automator routes them to different actions — e.g., red-labeled events generate Chat notifications, green-labeled events auto-append to a briefing doc, blue-labeled events sync to a specific Sheet tab.

Market Signal

Google Calendar custom labels API went GA on July 7, 2026, introducing up to 200 custom labels per calendar with hex color support via the new labelProperties resource. No open-source GAS tool or existing Discussion in this repo addresses this capability. Competitors like Zapier/Make support basic calendar triggers but cannot filter or route by custom label color. The API requires the eventLabelVersion=1 query parameter — a nuance that a purpose-built script handles transparently.

Sources:

• Google Calendar API release notes — July 7, 2026 GA announcement
• Custom event colors in Google Calendar — Workspace blog
• Calendar Labels API guide

User Signal

The project already has two calendar scripts (calendar-to-sheets, calendar-to-briefing-doc), demonstrating strong user demand for calendar automation. The calendar-to-briefing-doc PRD explicitly mentions filtering and routing calendar events. Users who color-code events by project/context want their automations to respect those visual signals — today they can't.

Technical Opportunity

The existing calendar script architecture (code.gs → src/index.js with CalendarApp injected) directly supports this pattern. The new labelProperties API is accessible via UrlFetchApp with the Calendar Advanced Service. The config.gs pattern already supports multi-rule configurations (proven in gmail-retention-policy's tag-based rules). The deploy page's config UI can render label-to-action mappings as dropdown rows.

Key implementation detail: The API requires eventLabelVersion=1 to return custom label data instead of legacy colorId indexes. Each label has an id, backgroundColor (hex), and optional name. Up to 200 labels per calendar are supported.

Assessment

Dimension	Score	Rationale
Feasibility	high	API is GA, follows standard REST patterns, project has 2 existing calendar scripts as reference implementations
Impact	high	Unlocks a new automation dimension (visual → programmatic); first-mover in the GAS ecosystem
Urgency	high	API is newly GA — window to establish the pattern before competitors build on it

Adversarial Review

Strongest objection: Users might not color-code their calendars consistently enough for rule-based automation to be reliable. Another calendar script also adds maintenance burden.

Rebuttal: The reliability objection is actually a feature: the script teaches users to use labels consistently by rewarding the behavior with automation. This is the same insight that made gmail-retention-policy successful — explicit taxonomy tags enable deterministic automation. The project's shared architecture (test infrastructure, gas-utils.js, deploy page config UI) makes new scripts low-cost to maintain.

Suggested Next Step

Prototype a minimal script that reads events from a calendar using CalendarApp + Advanced Calendar Service with eventLabelVersion=1, groups them by custom label color, and writes a label-grouped summary to a Google Doc. Start with read-only to validate the API integration pattern before adding routing rules.