> ## Documentation Index > Fetch the complete documentation index at: https://docs.alysio.ai/llms.txt > Use this file to discover all available pages before exploring further. # Gmail > Connect Alysio to Gmail using OAuth 2.0 ## 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 status\ Retrieving 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 labels\ Viewing 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](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](https://www.googleapis.com/auth/gmail.modify) | Allows Alysio to move messages to trash and restore them | | [https://www.googleapis.com/auth/gmail.labels](https://www.googleapis.com/auth/gmail.labels) | Allows Alysio to retrieve label information and message counts | These permissions allow Alysio to retrieve email data and perform limited mailbox management operations. *** ## 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 using\ Show my Gmail profile *** ### search\_gmail\_messages Searches Gmail messages using Gmail’s query syntax. Example prompts Find emails from [boss@company.com](mailto:boss@company.com)\ Show 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 email\ Show details for message 18abc123 *** ### trash\_gmail\_message Moves a specific email message to the Gmail Trash folder. Example prompts Delete this email\ Move this message to trash *** ### untrash\_gmail\_message Restores an email message from Trash back to the mailbox. Example prompts Restore this email\ Untrash message 18abc123 *** ### list\_gmail\_labels Lists all available Gmail labels associated with the mailbox. Example prompts Show my Gmail labels\ List all labels in my inbox *** ### get\_gmail\_label Retrieves detailed information about a specific Gmail label. Example prompts Show the details for the INBOX label\ Get label information *** ### get\_gmail\_draft\_details Retrieves detailed information about a draft email. Example prompts Show this draft\ What is in draft r-123 *** ### search\_gmail\_drafts Searches draft emails using Gmail query syntax. Example prompts Find drafts about the proposal\ Search 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 have\ How 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. Solution\ Navigate to Settings → Integrations and connect Gmail through OAuth. *** ### Authentication Error The OAuth token may be expired or revoked. Solution\ Reconnect the Gmail integration through Settings → Integrations. *** ### Insufficient Permissions The integration may not have the required OAuth scopes. Solution\ Ensure 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. Solution\ Use standard Gmail search operators such as: from:\ to:\ subject:\ is:unread *** ### Message Count Confusion The default message count returns unread threads, not individual messages. Solution\ Specify whether you want message-level counts or thread-level counts. *** ## Support For assistance configuring or troubleshooting the Gmail integration, contact [support@alysio.ai](mailto:support@alysio.ai) Your Alysio onboarding or account team can also assist with integration setup and best practices.