Integrations
Google & Gmail
Calendar and inbox ingestion. OAuth scopes, sync schedule, what we read and what we don't.
Mayva connects to Google Calendar (read) and Gmail (read metadata) to give the morning brief actual schedule and inbox context.
Calendar
pnpm google:auth
pnpm google:backfill
Scope: read-only on calendar events. We don’t write to your calendar from the sync worker. (The dashboard has an opt-in “push tasks to Google Cal” feature that uses a separate write scope.)
google-sync runs every 15 minutes and pulls today + next 7 days of events into calendar_events:
| Column | Source |
|---|---|
id | Google event id |
calendar_id | The calendar this came from |
start_at, end_at | UTC timestamps |
title, location | Plain text |
is_all_day, is_self_organized | Booleans |
payload | Raw event JSON, for the rare worker that needs more |
Gmail
pnpm gmail:auth
pnpm gmail:backfill
Scope: gmail.metadata — sender, subject, labels, internalDate. We do not read message bodies. Bodies are big, noisy, and not what the morning brief needs.
gmail-sync pulls the inbox-label metadata into email_signals:
| Column | Source |
|---|---|
id | Gmail message id |
from_addr | Header From |
subject | Header Subject |
labels | Gmail labels (Inbox, Starred, etc) |
received_at | internalDate |
The morning brief uses this to say “you have 12 unreads from 3 senders that aren’t newsletters” — that’s all it needs.
Why metadata-only
Two reasons:
- Privacy gradient. Email bodies are exactly the kind of thing we said we wouldn’t upload by default. The metadata scope means the agent literally cannot see bodies even if you asked it to.
- Cost gradient. Body ingestion would 10× the storage and token costs without proportionally improving the agent’s decisions.
If you want body-aware behavior (e.g. “summarize the long PR review thread Alex sent me”), that’s an opt-in workflow that asks for the broader scope at the moment you trigger it. Not on by default.
Push tasks to Calendar (opt-in)
Until full two-way sync lands, there are two ways to surface Mayva tasks on your calendar:
Read-only ICS
pnpm tasks:ics
Writes the next 30 days of scheduled tasks to data/tasks.ics. Subscribe to it in macOS Calendar (Calendar → File → New Calendar Subscription). The 📌 prefix on each entry tells you the source is Mayva.
This is read-only — editing the .ics calendar in macOS doesn’t propagate back to Mayva. The source of truth stays in Mayva.
Direct push (Indie/Team only, opt-in)
A dashboard toggle that, with your consent, asks for calendar.events scope and pushes tasks as events on a “Mayva” calendar you can hide/show.
Disabling
echo "GOOGLE_ENABLED=false" >> .env
echo "GMAIL_ENABLED=false" >> .env
The morning brief will skip the calendar and inbox sections. No worker errors, no STALE indicators — they just don’t appear in the brief.