gmail-skill_skill

Overview

This skill provides read, search, draft, send and contact lookup capabilities for Gmail accounts. It supports multiple authenticated accounts and outputs machine-friendly JSON for integration. Explicit user confirmation is always required before any email is actually sent.

How this skill works

The skill uses Google OAuth to access Gmail and People APIs; a one-time OAuth client setup is required. Commands let you search messages with advanced Gmail query syntax, read or list messages, create drafts, send messages (after confirmation), manage labels, and search or list contacts. Tokens are stored locally per account so you can switch between accounts using an --account flag.

When to use it

• Check inboxes or list recent messages across multiple accounts
• Search for messages with advanced Gmail queries (from:, subject:, has:attachment, is:unread, date filters)
• Read a specific email or mark messages read/unread, starred, archived, or unarchived
• Create drafts or send emails (send requires explicit confirmation)
• Lookup or search Google Contacts to find email addresses and phone numbers

Best practices

• Complete the one-time OAuth setup to enable read and send scopes before first use
• Always review the full email preview (from, to, cc/bcc, subject, body) when asked to send and confirm explicitly
• Use Gmail query syntax for precise searches (e.g., from:alice subject:report after:2026/01/01)
• Prefer creating drafts with --reply-to-id when replying to preserve threading
• Limit --max-results for list/search to keep outputs small when integrating with scripts

Example use cases

• Find unread messages from this week: search 'is:unread after:2026/01/01'
• Read a specific message by its ID to display full content for follow-up
• Create a draft reply referencing an existing message ID to maintain threading
• Send a quick email after reviewing the preview and confirming 'yes'
• Search contacts for 'Jane Doe' to get email and phone for outreach