Automate Gmail Tasks with Standalone OAuth
Lightweight Gmail CLI automation via standalone OAuth - search, read, send, and label emails, no MCP server.
Why it matters
Streamline your Google Workspace email management by integrating Gmail directly into your command-line workflows. Automate searching, reading, sending, and organizing emails without relying on external servers.
Outcomes
What it gets done
Search and filter emails using Gmail's query syntax.
Read email content and metadata.
Send emails, including HTML and with CC/BCC.
Manage drafts and modify message labels (archive, star, mark as read/unread).
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-gmail-automation | bash Overview
Gmail
Provides lightweight Gmail integration via standalone OAuth scripts with no MCP server: searching, reading, sending, drafting, and label management on a Google Workspace account. Use it to search, read, or send Gmail messages from the command line, or automate inbox workflows, on a Google Workspace account without an MCP server.
What it does
Provides lightweight Gmail integration via standalone OAuth scripts, with no MCP server required - though it requires a Google Workspace account, since personal Gmail isn't supported. First-time setup authenticates via a browser OAuth flow (python scripts/auth.py login), with status and logout subcommands. All operations run through scripts/gmail.py, auto-authenticating on first use: searching with Gmail's own query syntax (from:, is:unread, has:attachment, newer_than:7d, combinable with AND, OR, or NOT), reading a message in full, metadata-only, or minimal-ID form, sending plain or HTML email with CC/BCC and alias --from support, creating and sending drafts, and modifying labels - mark read or unread, archive, star, mark important - including multiple label changes in one call.
python scripts/gmail.py search "from:someone@example.com is:unread"
When to use - and when NOT to
Use it to search, read, or send Gmail messages from the command line without an MCP server, or to automate inbox workflows for a Google Workspace account. Not usable with a personal, non-Workspace Gmail account.
Inputs and outputs
Input: a Gmail search query, a message or draft ID, or email content to send or draft. Output: matching messages, full or partial message content, a sent email or created draft, or an updated label state - plus a list of all system and user-created Gmail labels via list-labels.
Integrations
Stores OAuth tokens securely in the system keyring - macOS Keychain, Windows Credential Locker, or Linux Secret Service API - under the service name gmail-skill-oauth, with tokens automatically refreshed via Google's cloud function when expired.
Who it's for
Developers automating Gmail workflows from the command line on a Google Workspace account who want to avoid standing up an MCP server.
Query operators combine with AND (space-separated), OR, or a leading - for NOT, so a single search can express something like messages from a specific sender that are unread and newer than one day, or messages matching either of two subjects while excluding starred ones. Common label IDs (INBOX, SENT, DRAFT, SPAM, TRASH, STARRED, IMPORTANT, UNREAD) are used directly with the modify command's --add-label/--remove-label flags. Sending supports an alias --from address as long as it's already configured as a send-as alias in Gmail settings, and --html renders the body as HTML rather than plain text. Search results can also include spam and trash explicitly via --include-spam-trash, since these are excluded from Gmail's default search scope. A bare search with no query string returns recent messages instead of filtering by anything specific.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.