Gmail Trigger

Gmail Triggers (Beta)

Polls the user's Gmail inbox on a cron and escalates to the assistant only when a new message arrives — an empty poll spends zero LLM tokens. Installing it means creating a script-mode schedule that runs the schedule's own copy of the shipped poll script. Schedule mechanics (script mode, the schedules/<id>/ convention, waking the agent loop) are documented in the included schedule skill.

Why this instead of a watcher

A watcher could only be configured through its prompt and its cadence. This one is a script that belongs to the schedule, so the assistant can change anything about how it behaves by simply editing the script. And because it runs as a schedule, its runs, errors, and cost all show up on the Schedules page in the app.

Setup

1. Ensure Google is connected

The trigger reads Gmail through the user's Google OAuth connection with Gmail read access. Check with:

assistant oauth status google

If no connection is found, load the vellum-oauth-integrations skill — it evaluates whether managed or your-own mode is appropriate and guides the user through connecting. Managed (proxy) and your-own OAuth both work — poll.ts calls Gmail via assistant oauth request, which resolves either automatically.

2. Choose the accounts to watch

If oauth status shows more than one active Google connection, ask the user which inboxes to watch and pass one --account <email> flag per chosen inbox. With a single connection the flag can be omitted. One schedule watches all chosen accounts and delivers one combined digest.

3. Collect the action prompt

Ask the user what should happen when new email arrives — e.g. "notify me only about emails needing a reply" or "summarize newsletters, flag anything from my boss". If the user doesn't care, omit the flag and the default applies: summarize what's new and flag anything urgent.

4. Ask about the first sync

By default the trigger starts from now and never escalates pre-existing email. Ask the user whether the first sync should instead include recent mail; if yes, append --lookback <duration> (90m/4h/2d/1w).

5. Create the schedule

Create a recurring script-mode schedule (default cadence every 15 minutes unless the user asks for a different one) whose command runs the schedule's own copy of the poll script with the flags chosen above:

bun "$VELLUM_WORKSPACE_DIR/schedules/$__SCHEDULE_ID/poll.ts" --account you@example.com --action-prompt 'Summarize new email; flag anything urgent'

Pass timeout_ms: 900000 — the poll's runtime includes the woken assistant turn. Single-quote the action prompt (the command runs through sh). All configuration lives in this command string, so it is visible in the schedule and editable later with assistant schedules update <id> --script "...".

6. Copy the poll script into the schedule's directory

Read the schedule id from the create result, then:

mkdir -p "$VELLUM_WORKSPACE_DIR/schedules/<id>"
cp "$VELLUM_WORKSPACE_DIR/skills/gmail-trigger/scripts/poll.ts" "$VELLUM_WORKSPACE_DIR/schedules/<id>/poll.ts"

The schedule owns this copy — customizations made to it are never touched by skill upgrades. poll.ts self-provisions its state on first run; create nothing else.

7. Verify

assistant schedules execute <id>
assistant schedules runs <id> --limit 1

The first run records {"ok":true,"new":0,"accounts":[{"account":"you@example.com","baselined":true,...}]}; later empty polls record "new":0 without baselined.