@nexionsoftware/pi-gmail

Gmail extension for pi — read, search, compose, and send emails via Gmail API

Packages

Package details

extension

Install @nexionsoftware/pi-gmail from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@nexionsoftware/pi-gmail
Package
@nexionsoftware/pi-gmail
Version
0.6.3
Published
Oct 3, 2026
Downloads
655/mo · 69/wk
Author
javier.alejandro.castro
License
MIT
Types
extension
Size
104.1 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@nexionsoftware/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, and send plain-text or HTML email immediately, with optional file attachments
  • Manage — archive, trash, label, mark read/unread
  • Attachments — attach files from the home directory when composing, and download inbound 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"
  }
}

Set clientId and clientSecret directly in settings.json; env:VAR_NAME substitution is not supported.

3. Authenticate

Start pi-webserver with /web, then run /gmail-auth. Pi requests the default browser and also prints a clickable, copyable local authentication URL in the conversation as a fallback. The running webserver handles the OAuth callback and Gmail stores the resulting 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 plain-text or HTML draft to, subject, body and/or html_body, cc, bcc, attachments
reply Reply to a thread in plain text or HTML thread_id, body and/or html_body, reply_all, attachments
send Compose and send immediately in plain text or HTML to, subject, body and/or html_body, attachments
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 selected from read id, exactly one of filename / attachment_index (preferred) or freshly validated deprecated attachment_id; optional save_path

Use list/search -> read -> download_attachment: compact listings are discovery-only and do not expose attachment selectors.

attachments accepts relative or absolute paths (array or comma-separated string), including ~/.... Resolved paths must stay inside the home directory; inbound download_attachment writes only inside the working directory or the system temp directory (default: .pi/gmail-attachments/<filename>). Messages under ~5MB use the JSON Gmail endpoint; larger messages use media upload up to the 35MB API limit.

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:@nexionsoftware/pi-gmail

License

MIT