platform/seed/skills/google-mail-api/FILE-GUIDE.md

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! 📧