omp packages

@nexionsoftware/pi-gmail0.6.3

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

javier.alejandro.castro Published 16 days ago MIT ~817 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

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