Gmail Integration¶

Automate email responses with your AI assistant connected to Gmail.

Requirements at a Glance

Gmail account (Google Workspace or personal)
Permission to authorize third-party apps
Configured assistant in Functional AI

What You Get¶

Email Automation¶

Your AI assistant automatically responds to incoming emails.

Intelligent Filtering¶

Set rules for which emails trigger automated responses.

Unified Inbox¶

All email conversations appear in your Functional AI dashboard.

Requirements¶

Requirement	Details
Gmail account	Google Workspace or personal Gmail
Account access	Permission to authorize third-party apps
Functional AI	Active account with configured assistant

Setting Up the Integration¶

Step 1: Connect Gmail¶

Go to Integrations or Social in your dashboard
Find Gmail integration
Click Connect

Step 2: Authorize with Google¶

You'll be redirected to Google's OAuth authorization flow. This secure process lets you grant Functional AI limited access to your Gmail account for email automation.

Understanding the Permissions¶

Permission	Scope	Why We Need It	What We Can Do	What We Can't Do
gmail.modify	Read & modify emails	To read incoming emails and mark them as read	Read messages, modify labels, mark as read	Delete emails or access Trash
gmail.send	Send emails	To send AI-generated replies	Send emails on your behalf	Send to arbitrary recipients
userinfo.email	Profile info	To identify your account	See your email address	Access personal Google data

Why these scopes and what we don't access

Why These Scopes: - gmail.modify: Read incoming emails and update their status (mark as read) - gmail.send: Send AI responses via your Gmail account - userinfo.email: Identify and associate your Gmail with your Functional AI account

We Never Access: - Google Drive files - Google Calendar or Contacts - Other Google services - Emails sent before connection - Deleted or archived emails

Authorization Steps¶

You'll be redirected to Google's authorization screen
Select your Gmail account
Review the permissions requested
Click Allow to grant permissions
You'll be redirected back to Functional AI

What happens behind the scenes

sequenceDiagram
    participant User
    participant FunctionalAI
    participant Google
    participant Gmail
    participant PubSub

    User->>FunctionalAI: Click "Connect Gmail"
    FunctionalAI->>Google: Redirect to OAuth with scopes
    Google->>User: Show permission screen
    User->>Google: Approve permissions
    Google->>FunctionalAI: Return authorization code
    FunctionalAI->>Google: Exchange code for access & refresh tokens
    Google->>FunctionalAI: Return tokens
    FunctionalAI->>Gmail: Subscribe to Pub/Sub notifications
    Gmail->>PubSub: Configure watch
    PubSub->>FunctionalAI: Confirm subscription
    FunctionalAI->>User: Connection successful

Token Management: - Access Token: Short-lived (1 hour) - Refresh Token: Long-lived, auto-refreshed - Encrypted storage (Fernet) - Revokable anytime in Google Account settings

Step 3: Configure Settings¶

After connecting:

Select which assistant handles emails
Configure filtering rules
Set up auto-reply options
Save settings

Configuration Options¶

Basic Settings¶

Setting	Description
Enable auto-reply	Toggle automated responses
Assistant	Select responding assistant
Reply delay	Time before sending response

Filtering Rules¶

Control which emails receive automated responses:

Subject Filters¶

Filter	Example
Contains	"support", "help", "question"
Starts with	"RE:", "FW:"
Doesn't contain	"noreply", "newsletter"

Sender Filters¶

Filter	Type
Include	Specific addresses or domains
Exclude	Known automated senders

Example Filter Configuration¶

Auto-reply when:
- Subject contains: "support", "help", "order"
- Subject doesn't contain: "unsubscribe"

Don't auto-reply when:
- From: *@noreply.*, newsletter@*
- Already replied in thread

Best Practices¶

Assistant Instructions¶

Optimize for email communication:

You are the email support assistant for [Company].

Email style:
- Professional but friendly
- Include proper greeting and sign-off
- Structure with clear paragraphs
- Address all questions in the email

Format:
- Start with "Hello [Name]" or "Hi [Name]"
- End with "Best regards, [Company] Support"
- Keep responses focused and helpful

You can help with:
- Product inquiries
- Order status
- General questions
- Basic troubleshooting

For complex issues:
- Acknowledge receipt
- Say a team member will follow up
- Provide timeframe when possible

Email Formatting¶

Good responses include: - Clear subject line (if applicable) - Professional greeting - Direct answer to question(s) - Next steps if needed - Professional sign-off

Example:

Subject: RE: Question about shipping

Hi Sarah,

Thank you for reaching out about your order #12345.

Your package shipped yesterday and is expected to arrive
by Friday, March 15th. You can track it here: [link]

If you have any other questions, please don't hesitate
to ask.

Best regards,
[Company] Support Team

Filtering Best Practices¶

Emails to Auto-Reply¶

Customer support inquiries
Product questions
Order status requests
General information requests

Emails to Exclude¶

Type	Why
Automated emails	Avoid reply loops
Marketing	Not customer inquiries
Internal	Handle separately
Spam	Obvious reasons

Reply Loop Prevention¶

The integration should automatically prevent: - Replying to your own emails - Replying to noreply addresses - Continuous back-and-forth loops

Managing Email Conversations¶

Viewing Emails¶

Go to Conversations
Filter by Gmail channel
View email threads

Manual Follow-up¶

For emails needing human attention:

Review the AI response
Add additional information if needed
Send follow-up manually if required

Thread Management¶

Email threads are grouped together
AI has context from previous messages
You can continue the thread manually

Email Flow¶

Email arrives in Gmail
        ↓
Functional AI receives notification
        ↓
Filters applied (subject, sender)
        ↓
If passes filters: AI processes email
        ↓
Response composed
        ↓
Reply sent from your Gmail
        ↓
Logged in dashboard

Attachments¶

Receiving Attachments¶

When customers email you with attachments, we automatically:

Download and store all attachments securely in our cloud
Display them in your Conversations dashboard
Keep them available permanently (they won't expire)

Supported: All file types that Gmail supports (up to 25MB per email)

Sending Attachments¶

When you reply manually from the Conversations dashboard:

Click the attachment icon to upload files
All standard file types are supported
Attachments are sent as normal email attachments

AI and Attachments¶

Currently, the AI assistant can see that attachments were included but cannot analyze their contents. For emails with attachments, consider:

Training your assistant to acknowledge attachments
Having the AI offer to connect with a human for attachment-related queries

Limitations¶

Platform Constraints¶

Daily limits: Gmail has sending limits
Threading: AI continues existing threads
Formatting: HTML formatting may be limited

Recommended Use Cases¶

Initial response to inquiries
Simple question answering
Triage and acknowledgment
After-hours support

Not Recommended For¶

Legally sensitive communications
Complex negotiations
Highly personalized outreach
Time-critical urgent matters

Gmail Uses Pub/Sub, Not Webhooks

Gmail uses Google Cloud Pub/Sub for more reliable, guaranteed message delivery with automatic retries.

Understanding Gmail Pub/Sub notifications

Unlike Instagram and Messenger which use webhooks, Gmail uses Google Cloud Pub/Sub for real-time notifications.

Pub/Sub vs Webhooks: - Guaranteed delivery with retries - Message queuing if service down - 7-day watch mechanism (auto-renewed) - More secure (Google Cloud authentication)

How It Works: 1. Gmail detects new email 2. Publishes to Pub/Sub topic 3. We receive notification (not full email) 4. We fetch actual email via Gmail API 5. Check filter rules 6. If passes: AI processes and responds

Watch Mechanism: Gmail watch expires after 7 days but we automatically renew before expiration.

Troubleshooting¶

Quick Diagnostics¶

Problem	Check	Fix
Can't connect	Workspace policies? Popup blocked?	Check with IT admin, enable popups
No emails processed	Filters too restrictive? Watch expired?	Broaden filters, reconnect
Responses not sending	Daily limit hit? Assistant public?	Check quotas, make assistant public

Gmail Sending Limits

Personal Gmail: 500 emails/day. Google Workspace: 2,000 emails/day.

Detailed connection troubleshooting

Can't Connect:

Using Google/Gmail account
No 2FA blocks
No organizational policies blocking third-party apps
Popup blockers disabled

Steps: 1. Check if Workspace admin has blocked third-party apps 2. Clear previous authorizations: Google Account > Security > Third-party apps 3. Try incognito/private mode 4. Contact IT admin if using enterprise/educational account

Why Connections Drop: - Token revoked manually - 7-day watch expired (we auto-renew) - Password changed - Policy changes

Emails not processing

Send test email (should be processed within 30 seconds)
Check watch status (we auto-renew every 7 days)
Review filter rules (filters too restrictive?)
Check Google Workspace status

Common Filter Mistakes: - Empty subject filter matches all emails - Typos in exclusion patterns - Overly specific inclusion rules

Responses not sending

Check Sending Limits: - Personal Gmail: 500 emails/day - Google Workspace: 2,000 emails/day - Quota resets at Pacific Time midnight

Common Issues: - Private assistant → Make assistant public - Auto-reply disabled → Enable in integration settings - Filter doesn't match → Review filter rules - Refresh token expired → Reconnect Gmail - Test manually in dashboard to isolate issue

Watch expiration issues

Symptoms: Emails stopped processing, no errors, connection active

Fix: 1. Reconnect Gmail (creates fresh 7-day watch) 2. Send test email within 5 minutes 3. Should be processed immediately

Gmail watch expires after 7 days. We auto-renew but extended downtime may cause issues.