Google Calendar and Gmail

Overview

Connect your agents to Google Calendar and Gmail for intelligent scheduling and email automation. Agents can check availability, schedule meetings, send emails, and manage your Google Workspace on your behalf.

This integration uses OAuth 2.0 for secure authentication. Users authorize access once, and MagOneAI handles token management and refresh automatically. All credentials are stored in HashiCorp Vault.

OAuth setup for Google Workspace

Before agents can access Google services, you need to configure OAuth and users need to authorize access.

Google Calendar tools

Give your agents access to calendar management capabilities. Agents can read availability, create meetings, and manage events.

List events

Retrieve calendar events for a specific date range.

Parameters:

• calendar_id (optional) — defaults to user's primary calendar
• start_time — ISO 8601 datetime for range start
• end_time — ISO 8601 datetime for range end
• max_results (optional) — maximum number of events to return

Returns: List of events with title, start time, end time, attendees, and location.

Example use case: "Show me all meetings this week so I can prepare for them."

Create event

Create a new calendar event with title, time, attendees, and optional details.

Parameters:

• calendar_id (optional) — defaults to user's primary calendar
• summary — event title
• start_time — ISO 8601 datetime for event start
• end_time — ISO 8601 datetime for event end
• attendees (optional) — list of email addresses
• description (optional) — event description
• location (optional) — meeting location or video conference link

Returns: Created event details including event ID.

Example use case: "Schedule a 30-minute meeting with john@example.com tomorrow at 2pm to discuss the quarterly report."

Update event

Modify an existing calendar event.

Parameters:

• calendar_id (optional) — defaults to user's primary calendar
• event_id — ID of the event to update
• summary (optional) — new event title
• start_time (optional) — new start time
• end_time (optional) — new end time
• attendees (optional) — updated attendee list
• description (optional) — new description
• location (optional) — new location

Returns: Updated event details.

Example use case: "Move my 3pm meeting to 4pm and add sarah@example.com as an attendee."

Delete event

Remove a calendar event.

Parameters:

• calendar_id (optional) — defaults to user's primary calendar
• event_id — ID of the event to delete

Returns: Confirmation of deletion.

Example use case: "Cancel my meeting with the client tomorrow."

Check availability

Find free and busy times for one or more attendees.

Parameters:

• attendees — list of email addresses to check
• start_time — ISO 8601 datetime for range start
• end_time — ISO 8601 datetime for range end

Returns: Free/busy information for each attendee, showing occupied time slots.

Example use case: "When are John and Sarah both free next week for a 1-hour meeting?"

Gmail tools

Enable agents to send, read, search, and manage emails on behalf of users.

Send email

Compose and send an email with subject, body, recipients, and optional attachments.

Parameters:

• to — list of recipient email addresses
• subject — email subject line
• body — email body content (plain text or HTML)
• cc (optional) — list of CC recipients
• bcc (optional) — list of BCC recipients
• attachments (optional) — list of file paths or URLs to attach

Returns: Sent message details including message ID.

Example use case: "Send an email to the team with subject 'Weekly Update' and the report I just generated."

Read email

Retrieve the content of a specific email by message ID.

Parameters:

• message_id — Gmail message ID
• format (optional) — response format (full, metadata, minimal)

Returns: Email content including sender, recipients, subject, body, and attachments.

Example use case: "Read the email from john@example.com that I received this morning."

Search emails

Find emails matching specific search criteria using Gmail's search syntax.

Parameters:

• query — Gmail search query (e.g., "from:john@example.com subject:invoice")
• max_results (optional) — maximum number of results to return

Returns: List of matching emails with metadata.

Example use case: "Find all emails from Sarah in the last week mentioning 'budget'."

List emails

Retrieve recent emails from inbox or specific labels.

Parameters:

• label_ids (optional) — list of label IDs (defaults to INBOX)
• max_results (optional) — maximum number of emails to return
• include_spam_trash (optional) — whether to include spam and trash

Returns: List of email messages with metadata.

Example use case: "Show me the 10 most recent unread emails in my inbox."

Reply to email

Send a reply to an existing email thread.

Parameters:

• message_id — ID of the message to reply to
• body — reply body content
• reply_all (optional) — whether to reply to all recipients (defaults to false)

Returns: Sent reply details.

Example use case: "Reply to that email from John saying we'll have the report ready by Friday."

Usage in workflows

Google tools can be used in both Agent nodes (for intelligent, flexible execution) and Tool nodes (for deterministic execution).

Agent node example

System prompt:

You are a scheduling assistant. When asked to schedule meetings:
1. Check the availability of all attendees using the calendar tool
2. Find a time slot that works for everyone
3. Create the calendar event with appropriate details
4. Send confirmation emails to all attendees

Be proactive about suggesting alternative times if conflicts exist.

User message:

Schedule a 1-hour meeting with john@example.com and sarah@example.com
sometime next week to discuss Q1 planning.

The agent will:

1. Use check_availability to find when John and Sarah are both free
2. Select an appropriate time slot
3. Use create_event to schedule the meeting
4. Use send_email to notify attendees with meeting details

Tool node example

For deterministic email sending, use a Tool node:

Tool: Send email Parameters:

• to: ["john@example.com"]
• subject: "Weekly Report - {{date}}"
• body: {{report_content}}

The tool executes with exactly these parameters every time, using variable values from the workflow context.

Security and permissions

OAuth scopes

The Google Workspace integration requests these OAuth scopes:

• https://www.googleapis.com/auth/calendar — full calendar access
• https://www.googleapis.com/auth/gmail.send — send emails on user's behalf
• https://www.googleapis.com/auth/gmail.readonly — read emails
• https://www.googleapis.com/auth/gmail.modify — modify emails (labels, read status)

Users see these permissions when they authorize access.

Credential storage

All OAuth tokens are stored in HashiCorp Vault with:

• Encryption at rest using AES-256
• User-scoped access controls
• Automatic key rotation
• Audit logging for all access

Token refresh

Access tokens expire after 1 hour. MagOneAI automatically:

1. Detects when a token is about to expire
2. Uses the refresh token to obtain a new access token
3. Updates the stored token in Vault
4. Retries the failed tool call with the new token

Users never see "token expired" errors.

Troubleshooting

Next steps