mail

name	mail
description	Manage Gmail using gog gmail command-line tool. Search emails, read messages, compose and send emails, manage labels, and perform common email operations. Use when the user needs to check their email, send messages, or work with Gmail.

Gmail Manager

This skill provides Gmail management capabilities using the gog gmail command-line tool.

Prerequisites

Before using this skill, ensure gog is installed and authenticated:

go install github.com/stephenafamo/gog@latest
gog gmail init

The first time you run gog gmail, it will authenticate with your Google account.

User Configuration

• Default account: set via GOOGLE_ACCOUNT in ~/.claude/.env
• All gog gmail commands should use --account $GOOGLE_ACCOUNT flag
• Important emails: When user asks for "important" mail, NEVER use is:important filter. Instead, search for unread emails, read their content, and intelligently prioritize based on context (e.g., customer messages, time-sensitive requests, personal communications vs newsletters/promotions)
• Label for action items: Use !2do label to mark emails requiring action

Core Capabilities

1. List/Search Emails

To list or search emails:

# List recent emails
gog gmail search --account $GOOGLE_ACCOUNT ""

# Search for specific emails
gog gmail search --account $GOOGLE_ACCOUNT "query"

# Search with specific criteria
gog gmail search --account $GOOGLE_ACCOUNT "is:unread"

# Search inbox
gog gmail search --account $GOOGLE_ACCOUNT "in:inbox"

2. Read Email

To read a specific email:

# Read thread by ID (preferred - shows full content)
gog gmail thread get --account="$GOOGLE_ACCOUNT" <threadId>

# Search messages (returns message IDs)
gog gmail messages search --account="$GOOGLE_ACCOUNT" "from:[e-mail]"

3. Send Email

To send a new email:

# Send email
gog gmail send --account $GOOGLE_ACCOUNT --to "[e-mail]" --subject "Subject" --body "Message body"

# Send with attachment (--attach flag, repeatable for multiple files)
gog gmail send --account $GOOGLE_ACCOUNT --to "[e-mail]" --subject "Subject" --body "Message body" --attach "/path/to/file.pdf"

# Send with multiple attachments
gog gmail send --account $GOOGLE_ACCOUNT --to "[e-mail]" --subject "Subject" --body "Message body" --attach "/path/to/cv.pdf" --attach "/path/to/cover.pdf"

# Send with CC/BCC
gog gmail send --account $GOOGLE_ACCOUNT --to "[e-mail]" --cc "[e-mail]" --bcc "[e-mail]" --subject "Subject" --body "Message"

# Reply to an email (keeps it in the same thread)
gog gmail send --account $GOOGLE_ACCOUNT --reply-to-message-id "<message-id>" --reply-all --body "Reply message"

# Reply within a thread (uses latest message for headers)
gog gmail send --account $GOOGLE_ACCOUNT --thread-id "<thread-id>" --reply-all --body "Reply message"

IMPORTANT: When replying to emails, always use --reply-to-message-id or --thread-id to keep the conversation threaded. Use --reply-all to automatically populate recipients from the original message.

4. Manage Labels

To manage email labels:

# List all labels
gog gmail labels list --account $GOOGLE_ACCOUNT

# Get label details
gog gmail labels get --account $GOOGLE_ACCOUNT <labelIdOrName>

# Create a new label
gog gmail labels create --account $GOOGLE_ACCOUNT <name>

# Add/remove labels from threads (can operate on multiple threads at once)
gog gmail labels modify --account="$GOOGLE_ACCOUNT" --add=<label1>,<label2> --remove=<label3> <threadId> ...

# Mark emails as read (remove UNREAD label)
gog gmail labels modify --account="$GOOGLE_ACCOUNT" --remove=UNREAD <threadId>

# Mark emails as unread (add UNREAD label)
gog gmail labels modify --account="$GOOGLE_ACCOUNT" --add=UNREAD <threadId>

Note: Use thread IDs (not message IDs) for label operations. Thread IDs are returned by gog gmail search commands.

IMPORTANT - --account flag quirk: When --account is followed by another flag (not the thread ID), use --account="$GOOGLE_ACCOUNT" with = syntax, and put threadId(s) at the end. Otherwise the parser treats the next flag as the account value.

5. Trash/Delete Emails

To trash or delete emails:

# Move to trash
gog gmail trash <message-id>

# Permanently delete
gog gmail delete <message-id>

Usage Instructions

When the user requests email operations:

1. For viewing emails: Use gog gmail list or gog gmail search to find messages
2. For reading emails: Use gog gmail read with the message ID
3. For sending new emails: Use gog gmail send with appropriate flags
4. For replying to emails: Use gog gmail send with --reply-to-message-id or --thread-id and --reply-all to keep the conversation threaded
5. For managing labels: Use gog gmail labels and gog gmail label commands

Common Patterns

Check inbox

gog gmail search --account $GOOGLE_ACCOUNT "in:inbox"

Search for emails from a specific sender

gog gmail search --account $GOOGLE_ACCOUNT "from:[e-mail]"

Send a quick email

gog gmail send --account $GOOGLE_ACCOUNT --to "[e-mail]" --subject "Quick update" --body "Here's the update..."

Reply to an email thread

# Get the message ID from search/list results first
gog gmail search --account $GOOGLE_ACCOUNT "from:[e-mail]"

# Reply to keep it in the same thread
gog gmail send --account $GOOGLE_ACCOUNT --reply-to-message-id "19be12f187273072" --reply-all --body "Thanks for your email..."

Error Handling

If gog is not installed:

go install github.com/stephenafamo/gog@latest

If authentication fails:

gog gmail init

Job Application Emails

When applying to jobs via email (e.g. [e-mail]):

1. Read answers.md and position.md from the lead folder for context.
2. Compose using the cover letter from answers.md as the email body.
3. Attach cv.pdf using --attach /path/to/cv.pdf.
4. IMPORTANT: gog gmail has no draft mode - send sends immediately. Always show the user the full email text and ask for confirmation before sending.
5. After sending, update the sheet status to Applied.

Example:

gog gmail send --account $GOOGLE_ACCOUNT \
  --to "[e-mail]" \
  --subject "Product Manager - Your Name" \
  --body "..." \
  --attach "/path/to/leads/024-company/cv.pdf"

Tips

• Use natural language queries for searching emails
• Message IDs can be obtained from list/search results
• Labels are case-sensitive
• The tool supports Gmail's search operators (from:, to:, subject:, etc.)
• Always use --reply-to-message-id or --thread-id when replying to emails to keep conversations properly threaded in Gmail
• Use --reply-all to automatically include all original recipients (To, CC) in your reply
• Attachments: use --attach /absolute/path/to/file flag (repeatable for multiple files)