Using Google Workspace

Practical guide for working with Google Workspace (Gmail, Calendar, Drive, Sheets, Docs) through Fp Switchboard.

Quick Tips

• Calendar events must specify timezone (IANA format like America/Toronto)
• Never mix date and dateTime fields in calendar events
• Gmail thread IDs are user-specific — sender and recipient have different IDs
• Drive file IDs must be extracted from URLs, never guessed
• Sheets uses A1 notation (e.g., Sheet1!A1:D10)
• Drive search accepts natural language OR Drive API syntax for precision

Common Gotchas

Calendar Timezone Required Critical

All calendar events must specify timeZone. Omitting it causes events to appear at wrong times.

	Example
Wrong	{"start": {"dateTime": "2025-01-15T14:00:00"}}
Correct	{"start": {"dateTime": "2025-01-15T14:00:00-05:00"}, "timeZone": "America/Toronto"}

date vs dateTime Fields Critical

Use date for all-day events, dateTime for timed events. Never mix them in the same event.

	Example
Wrong	{"start": {"date": "2025-01-15", "dateTime": "2025-01-15T14:00:00"}}
Correct	{"start": {"dateTime": "2025-01-15T14:00:00-05:00"}}

Gmail Thread IDs are User-Specific Critical

The same email conversation has different thread IDs for sender vs recipient. Never share thread IDs across users. Always search for threads within the same user context.

Drive File ID Extraction Critical

Extract the 33-character alphanumeric File ID from URLs. Never guess or construct IDs.

URL: docs.google.com/document/d/{FILE_ID}/edit
Example: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

Sheets A1 Notation Important

Sheet names with spaces need single quotes in range references.

	Example
Wrong	range: "My Sheet!A1:D10"
Correct	range: "'My Sheet'!A1:D10"

Drive Search Syntax Important

drive_search accepts natural language (auto-converted) OR native Drive API syntax for precise control.

• Natural language: "budget report 2025" (simple, works most of the time)
• Precise: name contains 'budget' and mimeType = 'application/pdf'
• Combined: name contains 'Q1' and mimeType = 'application/pdf' and modifiedTime > '2025-01-01'

Multi-Step Patterns

Create Calendar Event with Attendees

1. Resolve attendee emails if only names provided
2. Create event with sendUpdates: "all" to notify attendees
3. Store returned eventId for future modifications

Find and Edit a Document

1. Use drive_search with the filename or descriptive terms
2. Extract the file ID from the response
3. Use docs/sheets/slides tools with that ID

Advanced Drive Search

1. Start with natural language: drive_search("quarterly report")
2. If too broad, add type filter: name contains 'quarterly' and mimeType = 'application/vnd.google-apps.spreadsheet'
3. For date filtering: modifiedTime > '2025-01-01'
4. Combine: name contains 'budget' and mimeType = 'application/pdf' and modifiedTime > '2025-01-01'

ID Format Reference

ID Type	Format	Example
File ID	33-char alphanumeric	1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
Thread ID	Hexadecimal string	17c5a9b8e3f2d1a0
Event ID	Base32-like string	ck4t8g9h5n8s3k2j1m0
Message ID	Hexadecimal string	18a5b2c3d4e5f6a7

Example Prompts

• “Create a meeting tomorrow at 2pm EST with john@company.com”
• “Search Drive for the Q4 budget spreadsheet”
• “Send an email to the team about the project update”
• “List my unread Gmail messages from this week”
• “Find all PDF files in Drive modified this month”

Rate Limits

Google Workspace APIs have per-service rate limits:

Service	Limit
Gmail	250 quota units/second
Calendar	500 requests/100 seconds
Drive	12,000 requests/minute
Sheets	300 requests/minute