Gmail

Prerequisites

Create a Google OAuth client for a project with Gmail access and choose the Google accounts that may authorize it. The connected account supplies the mailbox used by every Gmail tool. Use the Gmail API guides, OAuth consent guide, and Google Cloud credentials console.

Self-hosted setup

1. Create or select a Google Cloud project and enable Gmail API. For MCP-first execution, also join the Workspace Developer Preview and enable Gmail MCP API.
2. Configure the OAuth consent screen, audience, test users, and the scopes below.
3. Create a Web application OAuth client and register https://<your-authlane-host>/api/v1/oauth/gmail/callback as an authorized redirect URI.
4. Copy the generated Client ID and Client Secret.

Configure authentication

Open Dashboard → Services → Gmail → OAuth Configuration, enter the Client ID and Client Secret, save, and enable Gmail. Use an exact HTTPS callback; Google treats a different scheme, host, port, or path as a redirect mismatch.

Scopes

Read-only tools requests only https://www.googleapis.com/auth/gmail.readonly. Full tool set requests the scopes below and exposes the matching mutations. Changing the policy requires users to reconnect.

• https://www.googleapis.com/auth/gmail.send permits sending mail.
• https://www.googleapis.com/auth/gmail.readonly permits reading messages, threads, labels, and drafts exposed by the adapter.
• https://www.googleapis.com/auth/gmail.compose enables gmail_create_draft.
• https://www.googleapis.com/auth/gmail.labels enables gmail_create_label.
• https://www.googleapis.com/auth/gmail.modify enables label changes through gmail_modify_email and moving messages to trash through gmail_trash_email.

Permanent deletion is deliberately not exposed: Gmail requires the restricted https://mail.google.com/ scope for that operation. Authlane provides gmail_trash_email instead, so the default self-hosted setup does not request full mailbox access.

Execution path

Prefer Google's official Gmail MCP server at https://gmailmcp.googleapis.com/mcp/v1; follow the official Gmail MCP guide. It is currently a Developer Preview, so keep the direct Gmail API adapter as a documented fallback for unavailable MCP tools and non-preview deployments.

Available tools

Read and search mail

• gmail_read_emails
• gmail_search_emails
• gmail_get_email
• gmail_get_thread

Send and draft

• gmail_send_email
• gmail_list_drafts
• gmail_create_draft

Organize and remove

• gmail_list_labels
• gmail_create_label
• gmail_modify_email
• gmail_trash_email

Install @authlane/integration-gmail in the SaaS runtime. Each callback gets a fresh Authlane credential lease and calls Gmail directly from that runtime; message content and Google responses do not pass through Authlane.

Connection lifecycle

Successful Google consent produces an encrypted connected connection. When Google returns an expiry and refresh token, Authlane schedules refresh before expiry. Reconnect when refresh is rejected or the connection becomes expired or error. Disconnect through a newly minted hosted session after recent user reauthentication.

Troubleshooting

• A read or send failure often means the connected Google account is outside the OAuth client's allowed users or the requested Gmail scope was not approved.
• Draft, label, and trash failures must be checked against their distinct compose, labels, and modify scopes.
• Use Gmail message and thread IDs returned by the read tools; email subjects are not IDs.