Overview
The Gmail integration allows Alysio to securely connect to a user’s Gmail account to search, retrieve, and manage email messages using natural language. Once connected, users can ask Alysio to locate emails, retrieve message details, view drafts, organize mailbox labels, count unread messages, and move emails to or from the trash. This allows users to quickly access and manage email information without navigating directly through the Gmail interface. All actions performed through the integration apply to the connected user’s Gmail mailbox, ensuring that users only access and manage their own email data. The integration provides read access to email content and limited mailbox management capabilities such as trashing or restoring messages.Supported Data and Capabilities
The Gmail integration provides access to several Gmail objects and mailbox operations.User Profile
Retrieve information about the authenticated Gmail user account. This information confirms the identity of the connected mailbox and can be used to verify the active Gmail integration.Messages
Users can search and retrieve email messages using Gmail’s native query syntax. Supported operations include: Searching emails by sender, subject, label, or unread statusRetrieving message details and metadata
Moving messages to trash
Restoring messages from trash Message details include: Message ID
Labels
Subject
Sender and recipient addresses
Snippet preview
Message date
Labels
Retrieve mailbox label information. Supported operations include: Listing all available labelsViewing label details
Viewing message and thread counts per label
Drafts
Retrieve draft messages stored in Gmail. Users can search drafts using Gmail’s query syntax or retrieve details for a specific draft. The current integration supports viewing draft content, but does not create or delete drafts.Message Counts
Retrieve message or thread counts for specific labels. This includes total message counts and unread message counts.Authentication
The Gmail integration uses OAuth 2.0 authentication through Google. Users connect their Gmail account through the Alysio Settings → Integrations panel. During authorization, Google prompts the user to grant Alysio access to Gmail data using OAuth. Once authorized, Alysio receives an OAuth access token that allows it to securely interact with the Gmail API on behalf of the user.Credential Handling
OAuth credentials are securely stored within Alysio and refreshed automatically according to Google’s token refresh policies. Each user maintains their own Gmail connection, ensuring that mailbox access remains isolated to the individual user. If the Gmail integration is disconnected or access is revoked through Google, Alysio will no longer be able to retrieve email data until the user reconnects the integration.Required Permissions and Scopes
The Gmail integration requests the following OAuth scopes.| Scope | Purpose |
|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Allows Alysio to search messages, retrieve drafts, list labels, and access mailbox metadata |
| https://www.googleapis.com/auth/gmail.modify | Allows Alysio to move messages to trash and restore them |
| https://www.googleapis.com/auth/gmail.labels | Allows Alysio to retrieve label information and message counts |
MCP Tools
The Gmail MCP exposes several tools that allow Alysio to retrieve and manage Gmail data using natural language.get_gmail_user_profile
Retrieves the Gmail profile associated with the connected account. Example prompts What Gmail account am I usingShow my Gmail profile
search_gmail_messages
Searches Gmail messages using Gmail’s query syntax. Example prompts Find emails from boss@company.comShow my unread emails Supported query operators include: from:
to:
subject:
is:unread
get_gmail_message_details
Retrieves detailed information for a specific email message. Example prompts Open this emailShow details for message 18abc123
trash_gmail_message
Moves a specific email message to the Gmail Trash folder. Example prompts Delete this emailMove this message to trash
untrash_gmail_message
Restores an email message from Trash back to the mailbox. Example prompts Restore this emailUntrash message 18abc123
list_gmail_labels
Lists all available Gmail labels associated with the mailbox. Example prompts Show my Gmail labelsList all labels in my inbox
get_gmail_label
Retrieves detailed information about a specific Gmail label. Example prompts Show the details for the INBOX labelGet label information
get_gmail_draft_details
Retrieves detailed information about a draft email. Example prompts Show this draftWhat is in draft r-123
search_gmail_drafts
Searches draft emails using Gmail query syntax. Example prompts Find drafts about the proposalSearch my drafts for this client
get_gmail_message_count
Retrieves message or thread counts for a label. Example prompts How many unread emails do I haveHow many messages are in my inbox By default, the tool returns the unread thread count for the INBOX label.
App Behavior
Alysio retrieves Gmail data on demand when users request email information or perform mailbox actions. There is no background synchronization between Alysio and Gmail. Instead, API requests are executed in real time when users search emails, retrieve message details, manage labels, or move messages to trash. All requests are executed using the user’s OAuth credential and are limited to the permissions granted during authorization.Example Workflow
User asks How many unread emails do I have Alysio routes the request to the Gmail MCP. The MCP calls get_gmail_message_count with the INBOX label and retrieves the unread thread count. The Gmail API returns the message count. Alysio displays the result directly in the conversation interface.Troubleshooting
Gmail Not Connected
The integration has not been authorized. SolutionNavigate to Settings → Integrations and connect Gmail through OAuth.
Authentication Error
The OAuth token may be expired or revoked. SolutionReconnect the Gmail integration through Settings → Integrations.
Insufficient Permissions
The integration may not have the required OAuth scopes. SolutionEnsure the Gmail integration is configured with the required Gmail scopes.
Search Returns No Results
The query may be too restrictive or use unsupported search syntax. SolutionUse standard Gmail search operators such as: from:
to:
subject:
is:unread
Message Count Confusion
The default message count returns unread threads, not individual messages. SolutionSpecify whether you want message-level counts or thread-level counts.