Skip to main content

​
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.
1

Configure Google OAuth credentials

In the Admin Portal, navigate to Integrations → Google Workspace. Enter your Google OAuth client ID and client secret. These are created in the Google Cloud Console for your project. The platform stores them securely in HashiCorp Vault.
2

Users authorize access

When a user first uses a Google tool, they’re redirected to Google’s OAuth consent screen. They authorize MagOneAI to access their calendar and email on their behalf.
3

Platform manages token storage and refresh

After authorization, MagOneAI stores the access token and refresh token in Vault. The platform automatically refreshes tokens before they expire — users never see credential errors.
4

Agents can now access Google services

Once authorized, agents can call Google Calendar and Gmail tools on behalf of the user. Credentials are injected at runtime when tools execute.
OAuth tokens are stored securely in HashiCorp Vault. The platform handles token refresh automatically — users authenticate once and agents have ongoing 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 [email protected] 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 [email protected] 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 [email protected] 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:[email protected] 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’.”
Gmail search queries support powerful operators like from:, to:, subject:, has:attachment, is:unread, and date ranges like after:2024/01/01. Learn more in Gmail search operators documentation.

​
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 [email protected] and [email protected]
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: 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

Symptoms: OAuth redirect fails or user sees error during authorization.Solutions:
  • Verify OAuth client ID and secret are correct in Admin Portal
  • Check that authorized redirect URIs are configured in Google Cloud Console
  • Ensure the OAuth consent screen is published (not in testing mode) for production use
Symptoms: Agent says events were created but they don’t appear in Google Calendar.Solutions:
  • Verify the agent is using the correct calendar_id (defaults to primary)
  • Check that the user’s OAuth token has calendar scope
  • Confirm timezone handling — ensure times are in ISO 8601 format with timezone
Symptoms: Send email tool returns success but email doesn’t arrive.Solutions:
  • Check recipient email addresses are valid
  • Verify the user’s OAuth token has gmail.send scope
  • Look for emails in the user’s Sent folder to confirm they were sent
  • Check recipient spam folders
Symptoms: Tools fail with “quota exceeded” or rate limit errors.Solutions:
  • Google Calendar and Gmail have rate limits per user per day
  • Reduce the frequency of tool calls if hitting limits
  • Consider caching calendar data instead of repeated queries
  • Request higher quotas from Google if needed for your use case

​
Next steps

Microsoft tools

Set up Outlook Calendar and Email integration

Custom MCP tools

Build your own tool integrations

Workflow builder

Design workflows that use Google tools

Agent configuration

Learn how to attach tools to agents