name: email-inbox description: Manage user's email inbox via Gmail IMAP and send emails via SMTP. Use when the user asks to check email, search emails, read messages, organize inbox, manage labels, delete emails, work with email threads/conversations, or send/compose/reply to emails. Requires GMAIL_APP_PASSWORD environment variable.

Email Management

Manage emails via Gmail IMAP (github.com/emersion/go-imap v1) and send emails via SMTP (github.com/emersion/go-smtp).

When to Use This Skill

Use when the user asks to:

• Check or read their email/inbox
• Search for emails (by sender, subject, date, unread, etc.)
• List recent emails or conversations
• Read a specific email thread
• Organize emails with labels
• Delete emails or threads
• Find emails with attachments
• Check unread count
• Send an email (new, reply, with attachments)
• Compose or draft an email
• Reply to an email thread

Prerequisites

Gmail App Password: Requires GMAIL_APP_PASSWORD environment variable.

• User must enable 2FA on Google account
• Generate app password at https://myaccount.google.com/apppasswords

Gmail Address: Requires GMAIL_ADDRESS environment variable for sending.

Reference Documentation

• Gmail Mailbox Structure - Understanding Gmail's IMAP folder structure and when to use each mailbox
• Gmail IMAP Extensions and Behavior - Gmail-specific additions to normal IMAP, including X-GM-RAW, X-GM-MSGID, X-GM-THRID, X-GM-LABELS, special-use mailboxes, and search caveats
• Common Email Queries - Practical examples for frequently requested operations (starred, unread, date ranges, pagination, etc.)
• Thread Operations - Complete code examples for Gmail thread management
• Replying in an Existing Gmail Thread - End-to-end guidance for finding a Gmail conversation via IMAP and sending a properly threaded SMTP reply
• Sending Email - Complete code examples for sending emails via SMTP

Operations

Reading Email (IMAP)

See references/operations.md for complete code examples.

• List Threads - Recent conversations with subjects, senders, dates
• Get Thread - All messages in a conversation by thread ID
• Search - Find emails using Gmail search syntax

Organizing Email (IMAP)

• Add Label - Apply label to a thread
• Remove Label - Remove label from a thread

Deleting Email (IMAP)

• Delete Thread - Move thread to Trash

Sending Email (SMTP)

See references/sending.md for complete code examples.

• Send Text Email - Plain text email
• Send HTML Email - Email with HTML content
• Send to Multiple - To, CC, BCC recipients
• Send with Attachment - Email with file attachments
• Reply to Email - Reply with In-Reply-To header

Gmail Search Syntax (X-GM-RAW)

Combine queries: is:unread from:github has:attachment

Gmail SMTP Settings

Sending Limits:

• Free Gmail: 500 emails/day
• Google Workspace: 2,000 emails/day

Technical Notes

IMAP (Reading):

• Uses github.com/emersion/go-imap v1.2.1 (not v2)
• Gmail supports normal IMAP operations plus Gmail-specific extensions advertised by X-GM-EXT-1
• Key Gmail extensions: X-GM-RAW (search), X-GM-MSGID (stable message ID), X-GM-THRID (stable thread ID), X-GM-LABELS (labels)
• Prefer special-use mailboxes and [Gmail]/All Mail for comprehensive searches and thread work
• For narrow X-GM-RAW queries that unexpectedly return zero, retry with a broader sender/date query and filter locally

SMTP (Sending):

• Uses github.com/emersion/go-smtp + github.com/emersion/go-sasl
• Uses TLS on port 465 (direct SSL connection)
• Build RFC 5322 compliant messages manually
• For replies, find the target message via IMAP first, then set both In-Reply-To and an appended References chain