@e9n/pi-gmail

Full Gmail integration for pi — read, search, compose, reply, and manage emails via the Gmail API.

Features

• Read & search — search with Gmail query syntax, read individual emails or full threads
• Compose & reply — create drafts, reply to threads, send immediately
• Manage — archive, trash, label, mark read/unread
• Attachments — download attachments to disk
• Notifications — optional background polling with TUI alerts for new mail
• Web UI — OAuth flow and auth status page via pi-webserver

Setup

1. Create Google OAuth credentials

1. Go to Google Cloud Console
2. Create a project (or use an existing one)
3. Enable the Gmail API
4. Create OAuth 2.0 Client ID credentials (Desktop or Web application)
5. Add http://localhost:<port>/gmail/callback as an authorized redirect URI

2. Configure pi settings

Add to ~/.pi/agent/settings.json:

{
  "pi-gmail": {
    "clientId": "your-client-id.apps.googleusercontent.com",
    "clientSecret": "your-client-secret"
  }
}

Values can use env:VAR_NAME syntax to read from environment variables.

3. Authenticate

Run /gmail-auth in pi to start the OAuth flow — opens a browser for Google sign-in and stores tokens locally.

Settings

| Key | Type | Default | Description | |-----|------|---------|-------------| | clientId | string | — | Google OAuth client ID (required) | | clientSecret | string | — | Google OAuth client secret (required) | | notifications.enabled | boolean | false | Enable background polling for new mail | | notifications.intervalMinutes | number | 5 | Polling interval in minutes | | notifications.query | string | "is:unread" | Gmail search query for notifications |

Tool: gmail

All actions are accessed through a single gmail tool with an action parameter.

Actions

| Action | Description | Key params | |--------|-------------|------------| | search | Search emails with Gmail query syntax | query, max_results | | read | Read a single email by ID | id | | read_thread | Read a full conversation thread | thread_id | | list_inbox | List recent inbox messages | max_results | | list_unread | List unread messages | max_results | | list_labels | List all Gmail labels | — | | compose | Create a draft email | to, subject, body, cc, bcc | | reply | Reply to a thread | thread_id, body, reply_all | | send | Compose and send immediately | to, subject, body | | send_draft | Send an existing draft | draft_id | | list_drafts | List all drafts | — | | delete_draft | Delete a draft | draft_id | | archive | Archive messages (remove from inbox) | id or ids | | trash | Move messages to trash | id or ids | | label | Add or remove labels | id, add_labels, remove_labels | | mark_read | Mark messages as read | id or ids | | mark_unread | Mark messages as unread | id or ids | | download_attachment | Save an attachment to disk | id, attachment_id, save_path |

Commands

| Command | Description | |---------|-------------| | /gmail-auth | Start OAuth authentication flow | | /gmail-logout | Disconnect Gmail account | | /gmail-status | Show current authentication status |

Web UI

When pi-webserver is running, the extension mounts:

• /gmail — Auth status page with connect/disconnect
• /gmail/auth — OAuth redirect to Google
• /gmail/callback — OAuth callback handler
• /api/gmail/status — JSON auth status endpoint

Install

pi install npm:@e9n/pi-gmail

License

MIT