376 lines
9.6 KiB
Markdown
376 lines
9.6 KiB
Markdown
# Google Mail API Skill - File Guide
|
|
|
|
Complete navigation guide for all files in the Google Mail API skill.
|
|
|
|
## Quick Start
|
|
|
|
**New to this skill?**
|
|
1. Read **README.md** first (5 min) - Decide Python vs Node.js
|
|
2. Read the relevant **SKILL.md** file (20 min) - Learn the concepts
|
|
3. Check **example-nodejs.ts** or Python example (5 min) - See working code
|
|
|
|
**Want to know what changed?**
|
|
→ Read **IMPROVEMENTS.md** and **GAPS-FILLED.md**
|
|
|
|
---
|
|
|
|
## File Reference
|
|
|
|
### 📚 Documentation Files
|
|
|
|
#### **README.md** (5.6 KB)
|
|
**What:** High-level overview and decision guide
|
|
|
|
**Contains:**
|
|
- Python vs Node.js comparison table
|
|
- When to use each language
|
|
- Feature parity overview
|
|
- Quick start instructions
|
|
- Tips & tricks
|
|
- Resources
|
|
|
|
**Read if:** You're deciding between Python and Node.js or want a quick reference
|
|
|
|
**Time:** 5 minutes
|
|
|
|
---
|
|
|
|
#### **SKILL.md** (16 KB)
|
|
**What:** Complete Python implementation guide
|
|
|
|
**Contains:**
|
|
- Python-specific installation
|
|
- OAuth 2.0 setup (Python)
|
|
- All Core API methods documented
|
|
- 16 practical recipes with Python code
|
|
- Message/Label/Thread/Draft structure docs
|
|
- Error handling patterns
|
|
- Query syntax reference
|
|
|
|
**Read if:** You're using Python
|
|
|
|
**Time:** 30 minutes (skim as needed)
|
|
|
|
---
|
|
|
|
#### **SKILL-nodejs.md** (35 KB)
|
|
**What:** Complete Node.js/TypeScript implementation guide
|
|
|
|
**Contains:**
|
|
- Node.js/TypeScript installation
|
|
- OAuth 2.0 setup (Node.js/TypeScript)
|
|
- All Core API methods documented
|
|
- 19 practical recipes with TypeScript code
|
|
- **NEW:** Advanced email handling recipes
|
|
- Send with multiple attachments
|
|
- Extract attachments from emails
|
|
- Parse full email structure
|
|
- Message/Label/Thread/Draft structure docs
|
|
- Error handling patterns with async/await
|
|
- Complete GmailHelper class
|
|
- Query syntax reference
|
|
|
|
**Read if:** You're using Node.js/TypeScript
|
|
|
|
**Time:** 40 minutes (skim as needed)
|
|
|
|
---
|
|
|
|
#### **IMPROVEMENTS.md** (6.4 KB)
|
|
**What:** Summary of all changes and enhancements
|
|
|
|
**Contains:**
|
|
- What was added to the skill
|
|
- File structure overview
|
|
- Feature parity table
|
|
- Python vs Node.js differences
|
|
- Technical improvements
|
|
- Recommendations for users
|
|
- Future enhancements
|
|
- Testing notes
|
|
|
|
**Read if:** You want to understand what's new
|
|
|
|
**Time:** 10 minutes
|
|
|
|
---
|
|
|
|
#### **GAPS-FILLED.md** (9.4 KB)
|
|
**What:** Detailed analysis of gaps that were filled
|
|
|
|
**Contains:**
|
|
- Original gaps found in Node.js
|
|
- What was added (3 new recipes)
|
|
- Updated feature parity table
|
|
- Real-world use case examples
|
|
- Email forwarding bot
|
|
- Document processing pipeline
|
|
- Email archive tool
|
|
- Code quality improvements
|
|
- How to test new features
|
|
- Complete summary
|
|
|
|
**Read if:** You want to understand the Node.js enhancements
|
|
|
|
**Time:** 15 minutes
|
|
|
|
---
|
|
|
|
#### **FILE-GUIDE.md** (This file)
|
|
**What:** Navigation guide for all skill files
|
|
|
|
**Contains:**
|
|
- Quick start path
|
|
- File descriptions
|
|
- Reading recommendations
|
|
- Time estimates
|
|
|
|
---
|
|
|
|
### 💻 Code Examples
|
|
|
|
#### **example-nodejs.ts** (10 KB)
|
|
**What:** Complete, runnable Node.js/TypeScript example
|
|
|
|
**Contains:**
|
|
- Full authentication flow
|
|
- 10+ working examples
|
|
- Get user profile
|
|
- List labels
|
|
- List messages
|
|
- Search messages
|
|
- Get full message
|
|
- Send message
|
|
- Create draft
|
|
- Apply labels
|
|
- List threads
|
|
- Move to trash
|
|
- Emoji-based progress indicators
|
|
- Error handling
|
|
- Can run immediately: `npx ts-node example-nodejs.ts`
|
|
|
|
**Run if:** You want to see working code
|
|
|
|
**Time:** 5 minutes to review, 1 minute to run
|
|
|
|
---
|
|
|
|
### ⚙️ Configuration Templates
|
|
|
|
#### **package.json.template** (570 B)
|
|
**What:** npm configuration template
|
|
|
|
**Contains:**
|
|
- Dependencies (googleapis, google-auth-library)
|
|
- DevDependencies (TypeScript, ts-node)
|
|
- Scripts (dev, example, build, start)
|
|
- Node.js version requirement (16+)
|
|
|
|
**Use if:** Setting up a new Node.js project
|
|
|
|
**Action:** Copy to `package.json` and run `npm install`
|
|
|
|
---
|
|
|
|
#### **tsconfig.json.template** (424 B)
|
|
**What:** TypeScript configuration template
|
|
|
|
**Contains:**
|
|
- ES2020 target
|
|
- ESM modules
|
|
- Strict type checking
|
|
- Proper module resolution
|
|
|
|
**Use if:** Setting up TypeScript in a Node.js project
|
|
|
|
**Action:** Copy to `tsconfig.json` in your project root
|
|
|
|
---
|
|
|
|
## Reading Paths
|
|
|
|
### Path 1: Just Deciding (5-10 minutes)
|
|
1. README.md - Decision guide section
|
|
2. → Choose Python or Node.js
|
|
|
|
### Path 2: Learning Python (30 minutes)
|
|
1. README.md - Overview
|
|
2. SKILL.md - Full guide
|
|
3. Check specific recipes as needed
|
|
|
|
### Path 3: Learning Node.js/TypeScript (35 minutes)
|
|
1. README.md - Overview
|
|
2. SKILL-nodejs.md - Full guide
|
|
3. example-nodejs.ts - See it in action
|
|
4. Check specific recipes as needed
|
|
|
|
### Path 4: Understanding the Enhancements (20 minutes)
|
|
1. IMPROVEMENTS.md - What changed
|
|
2. GAPS-FILLED.md - What was added
|
|
3. SKILL-nodejs.md - Advanced recipes section
|
|
|
|
### Path 5: Building a Project (1 hour)
|
|
1. README.md - Decision guide
|
|
2. Choose SKILL.md or SKILL-nodejs.md
|
|
3. example-nodejs.ts or Python example
|
|
4. Copy package.json.template (Node.js) or requirements.txt (Python)
|
|
5. Follow specific recipe sections
|
|
6. Adapt for your use case
|
|
|
|
---
|
|
|
|
## File Structure Overview
|
|
|
|
```
|
|
google-mail-api/
|
|
│
|
|
├─ Documentation (Read first)
|
|
│ ├─ README.md ..................... Quick reference & decision guide
|
|
│ ├─ IMPROVEMENTS.md ............... Overview of changes
|
|
│ ├─ GAPS-FILLED.md ................ Details of enhancements
|
|
│ └─ FILE-GUIDE.md ................. This file
|
|
│
|
|
├─ Implementation Guides (Core)
|
|
│ ├─ SKILL.md ...................... Python complete guide (16 KB)
|
|
│ └─ SKILL-nodejs.md ............... Node.js/TS complete guide (35 KB)
|
|
│
|
|
├─ Working Examples
|
|
│ └─ example-nodejs.ts ............. Running Node.js example (10 KB)
|
|
│
|
|
└─ Configuration (Project Setup)
|
|
├─ package.json.template ......... npm dependencies
|
|
└─ tsconfig.json.template ....... TypeScript config
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### OAuth 2.0 Setup
|
|
- Python: SKILL.md → "OAuth 2.0 Setup (Python)"
|
|
- Node.js: SKILL-nodejs.md → "OAuth 2.0 Setup (Node.js/TypeScript)"
|
|
|
|
### Common Recipes
|
|
- Both: "Common Recipes" section in respective SKILL files
|
|
- List Labels, Send Email, Extract Attachments, etc.
|
|
|
|
### Error Handling
|
|
- Python: SKILL.md → "Error Handling"
|
|
- Node.js: SKILL-nodejs.md → "Error Handling"
|
|
|
|
### API Reference
|
|
- Core Methods: SKILL.md or SKILL-nodejs.md → "Core API Methods"
|
|
- Message Structure: "Message Resource Structure" in both
|
|
- Query Syntax: "Query String Format" in both
|
|
|
|
### Advanced Examples
|
|
- Email Parsing: GAPS-FILLED.md → "Real-World Use Cases"
|
|
- Multiple Attachments: SKILL-nodejs.md → New recipes
|
|
- Helper Class: SKILL-nodejs.md → "Complete Example: Gmail Helper Class"
|
|
|
|
---
|
|
|
|
## New Content (Since You Asked)
|
|
|
|
What was added in response to your questions:
|
|
|
|
1. **SKILL-nodejs.md enhancements:**
|
|
- `sendMessageWithMultipleAttachments()` - Send 2+ files easily
|
|
- `extractAttachments()` - Download attachments from emails
|
|
- `parseFullEmail()` - Get complete email data
|
|
- `getMimeType()` - Helper for file type detection
|
|
- `decodeBase64Url()` - Proper email body decoding
|
|
|
|
2. **GmailHelper class enhancements:**
|
|
- `parseFullEmail()` method added
|
|
- Better type safety
|
|
- Easier to use in projects
|
|
|
|
3. **Documentation:**
|
|
- IMPROVEMENTS.md - Overview
|
|
- GAPS-FILLED.md - Detailed analysis
|
|
- FILE-GUIDE.md - This navigation guide
|
|
|
|
---
|
|
|
|
## Estimated Reading Time
|
|
|
|
| File | Time | Type | Essential? |
|
|
|------|------|------|-----------|
|
|
| README.md | 5 min | Ref | ✅ Yes |
|
|
| SKILL.md | 30 min | Guide | ✅ If using Python |
|
|
| SKILL-nodejs.md | 40 min | Guide | ✅ If using Node.js |
|
|
| example-nodejs.ts | 5 min | Example | ✅ If using Node.js |
|
|
| IMPROVEMENTS.md | 10 min | Summary | ⚠️ Recommended |
|
|
| GAPS-FILLED.md | 15 min | Detail | ⚠️ For context |
|
|
| FILE-GUIDE.md | 10 min | Nav | ⚠️ For navigation |
|
|
| package.json.template | 1 min | Config | ✅ If Node.js |
|
|
| tsconfig.json.template | 1 min | Config | ✅ If TypeScript |
|
|
|
|
**Total:** 30-80 minutes depending on path chosen
|
|
|
|
---
|
|
|
|
## Common Questions & Where to Find Answers
|
|
|
|
**Q: Should I use Python or Node.js?**
|
|
→ README.md → "Which Should I Use?"
|
|
|
|
**Q: How do I set up OAuth 2.0?**
|
|
→ SKILL.md or SKILL-nodejs.md → "OAuth 2.0 Setup"
|
|
|
|
**Q: How do I send an email with multiple files?**
|
|
→ SKILL-nodejs.md → "Send Email with Multiple Attachments"
|
|
|
|
**Q: How do I parse/read an email I received?**
|
|
→ SKILL-nodejs.md → "Parse and Decode Full Email Body"
|
|
|
|
**Q: How do I extract attachments from emails?**
|
|
→ SKILL-nodejs.md → "Extract Attachments from Received Email"
|
|
|
|
**Q: What changed from the original skill?**
|
|
→ IMPROVEMENTS.md and GAPS-FILLED.md
|
|
|
|
**Q: Is there working example code I can run?**
|
|
→ example-nodejs.ts
|
|
|
|
**Q: How do I set up a new project?**
|
|
→ package.json.template and tsconfig.json.template
|
|
|
|
**Q: What's the GmailHelper class?**
|
|
→ SKILL-nodejs.md → "Complete Example: Gmail Helper Class"
|
|
|
|
---
|
|
|
|
## Tips
|
|
|
|
- 📌 Pin README.md for quick reference
|
|
- 📌 Keep SKILL.md or SKILL-nodejs.md open while coding
|
|
- 🚀 Use example-nodejs.ts as a starting template
|
|
- 🔍 Use browser search (Ctrl+F) in SKILL files to find recipes
|
|
- 💡 Check "Common Recipes" section first for your use case
|
|
- 📚 Bookmark GAPS-FILLED.md for advanced techniques
|
|
|
|
---
|
|
|
|
## Updates & Versioning
|
|
|
|
**Last Updated:** February 24, 2026
|
|
|
|
**Current Status:**
|
|
- ✅ Python version: Complete and stable
|
|
- ✅ Node.js version: Enhanced with advanced recipes
|
|
- ✅ Feature parity: Achieved between Python and Node.js
|
|
|
|
**Recent Additions:**
|
|
- Advanced email handling (multiple attachments, parsing)
|
|
- Email extraction and attachment handling
|
|
- Complete GmailHelper class with new methods
|
|
- Enhanced documentation and examples
|
|
|
|
---
|
|
|
|
**Happy coding! 🎉**
|
|
|
|
Choose your language, pick a recipe, and start automating your Gmail! 📧
|