gmail-trigger

Polls Gmail inboxes on a schedule and escalates new mail to the assistant.

1.2k|166|Updated Feb 7, 2026
One-click install
npx skills add https://github.com/vellum-ai/vellum-assistant --skill gmail-trigger
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: gmail-trigger
Source: https://github.com/vellum-ai/vellum-assistant/tree/main/skills/gmail-trigger
Command: npx skills add https://github.com/vellum-ai/vellum-assistant --skill gmail-trigger

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Manually checking Gmail for important messages is constant context-switching, and naive inbox watchers waste tokens on empty polls. This Skill monitors one or more Gmail accounts on a cron schedule and only wakes the assistant when new mail actually arrives, applying your standing instruction (urgent-only pings, newsletter digests, invoice forwarding) automatically.

Core Features & Use Cases

  • Token-efficient polling: A deterministic TypeScript script syncs via the Gmail History API; empty polls spend zero LLM tokens and only new messages trigger an assistant turn.
  • Multi-account monitoring: Watch several Google OAuth connections with one schedule, each with independent per-mailbox state, watermark tracking, and failure isolation in SQLite.
  • At-most-once delivery: Watermarks and a reported-message ledger commit before escalation, so retries never deliver duplicate digests, and expired history IDs trigger automatic re-baselining.
  • Use Case: Tell the assistant "watch my work and personal Gmail, ping me only about emails needing a reply" — it creates a 15-minute script-mode schedule that summarizes new mail and flags anything urgent.

Quick Start

Ask the assistant to set up Gmail Triggers to watch your inbox and notify you only when urgent email arrives.

Frequently Asked Questions about gmail-trigger

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I get notified only about urgent Gmail messages?

Install this trigger with an action prompt like "notify me only about emails needing a reply". A scheduled poll script checks for new mail and wakes the assistant with a digest only when messages arrive, applying your instruction.

How to monitor multiple Gmail accounts with one automation?

Pass one --account flag per email address when creating the schedule. A single poll script watches all chosen inboxes, keeps independent per-mailbox state in SQLite, and delivers one combined digest.

Does Gmail polling require handling OAuth tokens in the script?

No. The poll script calls Gmail through the assistant oauth request command, which resolves managed or your-own OAuth connections automatically. No raw access token ever touches the script.

Why did my Gmail trigger stop delivering notifications?

Most failures are expired Google authorization, shown as HTTP 401 or 403 errors in the schedule run. Run assistant oauth ping google to refresh the token, or reconnect Google via the vellum-oauth-integrations skill.

Can the same email be escalated twice after a retry?

No. Each account's historyId watermark and reported-message ledger commit to SQLite before the digest is escalated, so retried or restarted runs never deliver the same message twice.