Skip to main content

​
Overview

What it does

Gmail integration connects AI tools directly to your Gmail account, enabling natural language interactions with emails, drafts, labels, and contacts.Key Features:
  • Send and receive emails
  • Create and manage drafts
  • Organize with labels
  • Search and filter messages
  • Manage conversation threads
  • Access contacts and profiles
  • Handle attachments
  • Reply to threads

Use Cases

Email Management:
  • Automatically respond to common inquiries
  • Organize inbox with smart labeling
  • Search for specific emails or threads
  • Archive or trash old messages
Communication Automation:
  • Draft personalized email responses
  • Send scheduled notifications
  • Create templated email campaigns
  • Reply to conversation threads
Workflow Integration:
  • Forward important emails to Slack
  • Extract data from email content
  • Create CRM entries from emails
  • Generate reports from email activity

​
Quick Start

1

Connect Your Google Account

NimbleBrain Studio uses OAuth2 to securely connect to your Gmail account.
  1. Navigate to Connections in the sidebar
  2. Click Browse Catalog
  3. Search for “Gmail”
  4. Click Install
  5. Click Connect and authorize with your Google account
  6. Grant the requested permissions for Gmail access
OAuth2 provides secure, token-based authentication. You’ll need to authorize access to your Gmail data.
2

Verify Connection

Once connected, test the integration:
"Show me my unread emails from today"
Other test prompts:
  • “List my recent email drafts”
  • “Show all labels in my Gmail”
  • “Get my Gmail profile information”

​
Available Tools

The Gmail connection provides 20+ tools organized into the following categories:

​
Email Management

Fetch, read, and manage email messages.
ToolDescription
GMAIL_FETCH_EMAILSRetrieve emails with filtering, pagination, and full content options
GMAIL_FETCH_MESSAGE_BY_MESSAGE_IDGet a specific email by ID (minimal, full, raw, or metadata format)
GMAIL_FETCH_MESSAGE_BY_THREAD_IDGet all messages from a conversation thread
GMAIL_DELETE_MESSAGEPermanently delete an email message
GMAIL_MOVE_TO_TRASHMove an email to trash (recoverable)
Example Usage:
"Show me all unread emails from the last 24 hours"
Use MOVE_TO_TRASH for recoverable deletion; DELETE_MESSAGE permanently removes emails.

​
Draft Operations

Create, list, and manage email drafts.
ToolDescription
GMAIL_CREATE_EMAIL_DRAFTCreate a draft with recipients, subject, body (plain/HTML), and attachments
GMAIL_LIST_DRAFTSList all drafts with optional detailed content
GMAIL_DELETE_DRAFTPermanently remove a draft
Example Usage:
"Create a draft email to [email protected] with subject 'Meeting Follow-up' and include our discussion points"
Drafts support HTML body content for rich formatting and can include attachments.

​
Thread Management

Manage email conversation threads.
ToolDescription
GMAIL_LIST_THREADSList conversation threads with filtering and pagination
GMAIL_MODIFY_THREAD_LABELSAdd or remove labels from entire threads
GMAIL_REPLY_TO_THREADSend a reply within an existing conversation
Example Usage:
"Reply to the thread about the Q4 budget with 'Approved, please proceed'"
Thread operations affect all messages in a conversation simultaneously.

​
Label Organization

Create and manage Gmail labels for organization.
ToolDescription
GMAIL_CREATE_LABELCreate custom labels with name, color, and visibility settings
GMAIL_LIST_LABELSList all system and user-created labels
GMAIL_MODIFY_EMAIL_LABELSApply or remove labels from individual messages
GMAIL_PATCH_LABELUpdate label properties (name, visibility, color)
GMAIL_REMOVE_LABELDelete user-created labels
Example Usage:
"Create a new label called 'Priority Clients' with red color"
System labels (INBOX, SENT, TRASH, etc.) cannot be deleted or renamed.

​
Contacts & Profile

Access contacts and profile information.
ToolDescription
GMAIL_GET_CONTACTSFetch contacts from Google account with pagination
GMAIL_GET_PEOPLEGet individual contact details or interaction history
GMAIL_GET_PROFILEGet account profile info (email, message count, history ID)
Example Usage:
"Show me my contact information for people at acme.com"

​
Attachments

Handle email attachments.
ToolDescription
GMAIL_GET_ATTACHMENTDownload attachments by attachment and message ID
Example Usage:
"Download the PDF attachment from the email about the contract"

​
Example Workflows

Scenario: Organize and prioritize your inboxPrompt:
"Find all unread emails from VIP clients, label them as 'Priority', and show me a summary"
What happens:
  • Searches for unread emails matching criteria
  • Applies the Priority label
  • Returns a summary of found emails

​
Authentication

OAuth2 Authentication: This connection uses OAuth2 for secure authentication.

​
How It Works

When you connect Gmail in NimbleBrain Studio:
  1. You’ll be redirected to Google’s authorization page
  2. Log in with your Google account
  3. Review and grant permissions
  4. You’re automatically redirected back to Studio

​
Required Scopes

The integration requests the following Gmail scopes: Email Scopes:
  • gmail.readonly - Read email messages and settings
  • gmail.modify - Read, send, delete, and manage labels
  • gmail.compose - Create and send new emails
  • gmail.send - Send email on your behalf
Contact Scopes:
  • contacts.readonly - Read contacts
  • contacts.other.readonly - Read “other contacts”
Profile Scopes:
  • userinfo.email - View email address
  • userinfo.profile - View basic profile info
You can manage connected apps in your Google Account under Security → Third-party apps with account access.

​
Rate Limits

Gmail API enforces quota limits:
Limit TypeRestriction
Daily sending500 emails/day (consumer), 2,000/day (Workspace)
Per-user rate250 quota units per user per second
Batch requests100 requests per batch
Quota Units by Operation:
  • messages.list - 5 units
  • messages.get - 5 units
  • messages.send - 100 units
  • drafts.create - 10 units
  • labels.list - 1 unit
Studio automatically handles rate limiting with exponential backoff for retries.

​
Troubleshooting

Issue: OAuth authorization didn’t completeSolutions:
  • Ensure you’re logged into the correct Google account
  • Try a different browser or incognito mode
  • Check popup blockers aren’t interfering
  • Verify your Google account is active
  • For Workspace accounts, check admin policies
Issue: Insufficient privileges errorSolutions:
  • Reconnect to grant additional scopes
  • For Workspace, ensure app is approved by admin
  • Check if Gmail API is enabled in Google Cloud Console
  • Verify account isn’t restricted
Issue: Cannot find specified emailSolutions:
  • Verify the message ID is correct
  • Email may have been deleted or moved
  • Check trash and spam folders
  • Try searching with different criteria
Issue: Cannot send emailSolutions:
  • Check daily sending quota hasn’t been exceeded
  • Verify recipient addresses are valid
  • Ensure compose scope is authorized
  • Check for attachment size limits (25MB)
Issue: Cannot create or modify labelsSolutions:
  • System labels cannot be modified
  • Label names must be unique
  • Check for special characters in label name
  • Verify modify scope is authorized
Issue: Too many requests errorSolutions:
  • Wait for rate limit to reset
  • Reduce frequency of requests
  • Batch operations when possible
  • Studio automatically handles retries

​
Best Practices

Email Organization

  • Use labels consistently
  • Create filters for auto-labeling
  • Archive instead of delete when possible
  • Use threads for related conversations
  • Keep inbox manageable

Security

  • Review connected apps regularly
  • Use specific scopes, not full access
  • Don’t store sensitive data in drafts
  • Monitor for unusual activity
  • Revoke access when not needed

Performance

  • Use filters to limit search results
  • Batch operations when possible
  • Cache frequently accessed data
  • Use pagination for large lists
  • Fetch only needed message parts

Communication

  • Use drafts for review before sending
  • Reply in threads for context
  • Include clear subject lines
  • Test templates before bulk use
  • Monitor delivery status

Gmail API Reference

Official Gmail API documentation

Gmail Help Center

Gmail support and troubleshooting

Google Cloud Console

Manage API quotas and credentials
Need help? Join the NimbleBrain Discord or email [email protected]