Skip to main content
The Gmail integration allows GAIA to read, compose, send, and organize emails in your Gmail account. With AI-powered email management, you can automate email workflows and handle inbox tasks naturally.

​
Features

  • Read and Search Emails: Find emails by sender, subject, date, or content
  • Compose and Send: Write and send emails with AI assistance
  • Label Management: Organize emails with labels and folders
  • Draft Management: Create, edit, and manage email drafts
  • Attachment Handling: Work with email attachments
  • Email Automation: Set up automated email workflows

​
Setup

1

Open Integrations

Navigate to Settings > Integrations in GAIA
2

Find Gmail

Search for “Gmail” or find it in the Communication category
3

Click Connect

Click the Connect button to start OAuth flow
4

Authorize Access

Sign in with your Google account and grant permissions
5

Complete Setup

You’ll be redirected back to GAIA once authorization is complete
Gmail requires specific OAuth scopes. Make sure you grant all requested permissions for full functionality.

​
OAuth Configuration

The Gmail integration uses the following OAuth scopes:
  • https://www.googleapis.com/auth/gmail.modify - Read, compose, and send emails

​
Provider Details

  • Provider: Composio
  • Toolkit: GMAIL
  • Auth Type: OAuth 2.0
  • Managed By: Composio platform

​
Usage Examples

​
Reading Emails

You: Show me unread emails from today

GAIA: I found 5 unread emails from today:
1. John Doe - "Project Update" (9:30 AM)
2. Sarah Smith - "Meeting Tomorrow" (10:15 AM)
...

​
Composing Emails

You: Send an email to [email protected] thanking him for the project update

GAIA: I'll compose and send that email for you.

✓ Email sent to [email protected]
Subject: Thank you for the update

​
Organizing Inbox

You: Label all emails from [email protected] as "Newsletters"

GAIA: I'll add the "Newsletters" label to those emails.

✓ Labeled 12 emails from [email protected]

​
Searching Emails

You: Find emails about "quarterly report" from last month

GAIA: I found 3 emails matching your search:
1. From: [email protected] - Q4 Report Draft
2. From: [email protected] - Quarterly Financial Summary
3. From: [email protected] - Report Review Meeting

​
Available Actions

The Gmail agent can perform the following actions:
  • Get user profile information
  • List and search emails
  • Read email content
  • Compose and send emails
  • Create and manage drafts
  • Add and remove labels
  • Mark emails as read/unread
  • Archive and delete emails
  • Handle attachments
  • Manage filters
  • Search with advanced queries

​
Workflows & Triggers

The Gmail integration supports automated workflows through triggers:

​
New Gmail Message Trigger

Trigger: When a new email arrives in your inbox Auto-Activated: Yes (monitors INBOX by default) Use Cases:
  • Auto-respond to certain emails
  • Forward important emails to Slack
  • Create tasks from emails
  • Log emails to a database
Example Workflow: 
trigger: gmail_new_message
config:
  labelIds: INBOX
  userId: me
actions:
  - if: subject contains "urgent"
    then: send_slack_message
    channel: "#urgent-emails"

​
AI Agent Details

Gmail uses a specialized subagent for intelligent email management:
  • Agent Name: gmail_agent
  • Domain: Email management and communication
  • Capabilities:
    • Composing professional emails
    • Understanding email context
    • Organizing inbox intelligently
    • Managing labels and filters
    • Handling attachments
    • Email workflow automation

​
Agent System Prompt

The Gmail agent is designed to:
  • Compose professional, context-aware emails
  • Understand natural language email requests
  • Maintain proper email etiquette
  • Suggest labels and organizational structures
  • Automate repetitive email tasks

​
API Reference

The Gmail integration exposes these tools to the AI:
ToolDescription
GMAIL_GET_PROFILEGet user’s Gmail profile information
GMAIL_LIST_MESSAGESList emails with filters
GMAIL_GET_MESSAGEGet full email content
GMAIL_SEND_MESSAGESend a new email
GMAIL_CREATE_DRAFTCreate email draft
GMAIL_MODIFY_MESSAGEUpdate email labels/status
GMAIL_TRASH_MESSAGEMove email to trash
GMAIL_SEARCHSearch emails with query
For complete API documentation, see Gmail Tools Reference.

​
Metadata Extraction

GAIA automatically extracts and stores your Gmail email address when you connect: 
{
  "email": "[email protected]"
}
This is used for:
  • Personalizing email composition
  • Filtering your own sent emails
  • Identifying your email address in conversations

​
Troubleshooting

​
Connection Issues

Make sure you’re signing in with the correct Google account and accepting all permission requests.
Verify that you granted the gmail.modify scope during authorization. You may need to reconnect the integration.
Gmail has API rate limits. GAIA automatically handles rate limiting, but extremely high volume may cause delays.

​
Common Questions

Yes. GAIA uses OAuth for secure authentication and never stores your Gmail password. Your credentials are encrypted and only used to make API calls on your behalf.
Yes, but only when you explicitly ask it to. The AI agent will always confirm before sending important emails.
GAIA only accesses emails when you specifically ask it to. It doesn’t continuously monitor your inbox unless you set up a workflow trigger.

​
Best Practices

Use specific search criteria to help GAIA find emails faster. Instead of “show me emails”, try “show me unread emails from John about the project”.
Create labels for automated organization. For example: “Label all emails from newsletter@* as Newsletters”.
Be careful with bulk actions like “delete all emails from X”. GAIA will usually ask for confirmation, but it’s good to double-check.
  • Google Calendar - Schedule meetings mentioned in emails
  • Slack - Forward important emails to Slack channels
  • Notion - Save email content to Notion pages
  • Linear - Create Linear issues from emails

​
Next Steps

Build Email Workflows

Automate email handling with workflows

Custom Email Rules

Set up custom triggers for incoming emails

Build docs developers (and LLMs) love

Get started for freeTalk to us