This is HTML content
" ``` ### Output ```json { "success": true, "messageId": "18d1234567890", "threadId": "18d1234567890", "to": "user@example.com", "subject": "Hello" } ``` ## gmail-search.js - Search Emails Search emails using Gmail's powerful query syntax. ### Basic Search ```bash node gmail-search.js --query "is:unread" --limit 10 ``` ### Search Operators ```bash # From specific sender node gmail-search.js --query "from:boss@company.com" # Emails with attachments node gmail-search.js --query "has:attachment" # Date range node gmail-search.js --query "after:2024/01/01 before:2024/12/31" # Subject search node gmail-search.js --query "subject:invoice" # Combine operators node gmail-search.js --query "from:client@example.com has:attachment is:unread" # Complex search node gmail-search.js --query "is:important OR is:starred" --limit 20 ``` ### Output ```json { "success": true, "count": 3, "total": 150, "query": "is:unread", "messages": [ { "id": "18d1234567890", "threadId": "18d1234567890", "from": "sender@example.com", "to": "you@gmail.com", "subject": "Project Update", "date": "Mon, 15 Jan 2024 10:30:00 -0800", "snippet": "The project is progressing well...", "labels": ["INBOX", "UNREAD"] } ] } ``` ## gmail-read.js - Read Messages Read full message content and thread details. ### Read Single Message ```bash node gmail-read.js --id "18d1234567890" ``` ### Read Message with Thread Context ```bash node gmail-read.js --id "18d1234567890" --thread ``` ### Output ```json { "success": true, "id": "18d1234567890", "threadId": "18d1234567890", "from": "sender@example.com", "to": "you@gmail.com", "subject": "Project Update", "date": "Mon, 15 Jan 2024 10:30:00 -0800", "labels": ["INBOX", "UNREAD"], "snippet": "The project is progressing well...", "body": "Full email body content here..." } ``` ## gmail-labels.js - Manage Labels List, create, add, and remove labels. ### List All Labels ```bash node gmail-labels.js --action list ``` ### Create New Label ```bash node gmail-labels.js --action create --name "Project Alpha" ``` ### Add Label to Message ```bash # Using label name node gmail-labels.js --action add --id "18d1234567890" --label "Important" # Using label ID node gmail-labels.js --action add --id "18d1234567890" --label "Label_123" ``` ### Remove Label from Message ```bash node gmail-labels.js --action remove --id "18d1234567890" --label "Important" ``` ### Output (list) ```json { "success": true, "action": "list", "count": 15, "labels": [ { "id": "INBOX", "name": "INBOX", "type": "system" }, { "id": "Label_123", "name": "Project Alpha", "type": "user" } ] } ``` ## gmail-drafts.js - Manage Drafts Create, update, send, and delete draft emails. ### List Drafts ```bash node gmail-drafts.js --action list --limit 10 ``` ### Create Draft ```bash node gmail-drafts.js \ --action create \ --to "user@example.com" \ --subject "Draft Subject" \ --body "Draft body text" ``` ### Update Draft ```bash node gmail-drafts.js \ --action update \ --id "r-1234567890" \ --to "user@example.com" \ --subject "Updated Subject" \ --body "Updated body text" ``` ### Send Draft ```bash node gmail-drafts.js --action send --id "r-1234567890" ``` ### Delete Draft ```bash node gmail-drafts.js --action delete --id "r-1234567890" ``` ### Output (create) ```json { "success": true, "action": "create", "draftId": "r-1234567890", "to": "user@example.com", "subject": "Draft Subject" } ``` ## Common Workflows ### 1. Find and Reply to Unread Emails ```bash # Search for unread emails node gmail-search.js --query "is:unread" --limit 5 > /tmp/unread.json # Read first message MESSAGE_ID=$(cat /tmp/unread.json | jq -r '.messages[0].id') node gmail-read.js --id "$MESSAGE_ID" > /tmp/message.json # Send reply SENDER=$(cat /tmp/message.json | jq -r '.from') SUBJECT=$(cat /tmp/message.json | jq -r '.subject') node gmail-send.js --to "$SENDER" --subject "Re: $SUBJECT" --body "Thanks for your message!" ``` ### 2. Organize Emails by Label ```bash # Search for project-related emails node gmail-search.js --query "subject:project alpha" > /tmp/results.json # Create label node gmail-labels.js --action create --name "Project Alpha" # Add label to each message cat /tmp/results.json | jq -r '.messages[].id' | while read id; do node gmail-labels.js --action add --id "$id" --label "Project Alpha" done ``` ### 3. Draft Review Workflow ```bash # Create draft node gmail-drafts.js --action create \ --to "client@example.com" \ --subject "Proposal" \ --body "Initial draft text" > /tmp/draft.json DRAFT_ID=$(cat /tmp/draft.json | jq -r '.draftId') # Update after review node gmail-drafts.js --action update \ --id "$DRAFT_ID" \ --to "client@example.com" \ --subject "Proposal - Final" \ --body "Revised draft text" # Send when ready node gmail-drafts.js --action send --id "$DRAFT_ID" ``` ## Gmail Search Operators Reference | Operator | Example | Description | |----------|---------|-------------| | `from:` | `from:user@example.com` | Emails from sender | | `to:` | `to:user@example.com` | Emails to recipient | | `subject:` | `subject:invoice` | Subject contains word | | `has:attachment` | `has:attachment` | Has any attachment | | `filename:` | `filename:pdf` | Attachment filename | | `is:unread` | `is:unread` | Unread emails | | `is:read` | `is:read` | Read emails | | `is:starred` | `is:starred` | Starred emails | | `is:important` | `is:important` | Important emails | | `label:` | `label:work` | Has specific label | | `after:` | `after:2024/01/01` | After date | | `before:` | `before:2024/12/31` | Before date | | `older_than:` | `older_than:7d` | Older than (d/m/y) | | `newer_than:` | `newer_than:2d` | Newer than (d/m/y) | ## Error Handling All scripts return JSON error objects: ```json { "success": false, "error": "Token not found. Run: npm run setup" } ``` Common errors: - **Token not found**: Run `npm run setup` to authenticate - **Invalid credentials**: Check `scripts/auth/credentials.json` - **Permission denied**: Ensure Gmail API scope is granted - **Message not found**: Invalid message/draft ID ## Tips for Claude 1. **Parse JSON efficiently**: Use `jq` for extracting specific fields 2. **Chain operations**: Save intermediate results to `/tmp/` files 3. **Validate IDs**: Check that message/draft IDs exist before operations 4. **User-friendly output**: Convert JSON to readable summaries for users 5. **Error handling**: Check `success` field and handle errors gracefully