Email Integration (Gmail)

Connect Gmail so your agents can read, respond to, and manage email. There are three ways to set this up — choose the one that fits your security posture.

Email Forwarding

Easiest. Forward specific emails to your agent. You control what it sees.

IMAP / App Password

Direct inbox access using a Google App Password. No OAuth setup required.

Your Own OAuth App

Full control. Create your own Google Cloud project. Credentials never leave your infrastructure.

Option 1: Email Forwarding (Recommended for Getting Started)

The simplest approach. You set up a forwarding rule in Gmail that sends specific emails to your agent’s inbox. Your agent only sees what you forward — nothing else.

Best for: Testing, support queues, specific use cases where you want tight control.

Create a forwarding address

Your Moe’s AI agent has a dedicated inbox address (provided during setup, e.g. support-agent-abc123@inbound.moes.ai).
Set up a Gmail filter

In Gmail → Settings → Filters → Create new filter:
- From: *@yourcompany.com (or whatever criteria you want)
- Subject: contains “support” (optional)
- Action: Forward to your agent’s inbound address
Confirm forwarding

Gmail will send a confirmation email to the agent address. Your agent will automatically approve it, or you can confirm manually in the Moe’s dashboard.
Test it

Send a test email matching your filter. Your agent should pick it up within 60 seconds.

Limitations:

Agent can only see forwarded emails (not search your full inbox)
Replies come from the agent address, not your Gmail (unless you configure send-as)
Slight delay (Gmail forwarding is near-instant but not guaranteed)

Option 2: IMAP with App Password

Direct inbox access without OAuth complexity. Your agent connects to Gmail via IMAP using a Google App Password.

Best for: Full inbox access with minimal setup. Good for dedicated support@ accounts.

Requirements: Google account with 2-Factor Authentication enabled.

Enable 2FA (if not already)

Go to Google Account Security → 2-Step Verification → Enable.
Generate an App Password

Go to App Passwords:
- Select app: “Mail”
- Select device: “Other” → name it “Moe’s AI”
- Copy the 16-character password
Configure your agent

During onboarding, your agent will ask:

“Would you like to connect Gmail? I can read and respond to emails on your behalf.”

Choose “IMAP / App Password” and provide:
- Email address: you@gmail.com
- App password: (the 16-character code)
Test access

Your agent will confirm it can access your inbox and show you the 3 most recent emails (subject lines only) to verify.

Limitations:

Full inbox access (can’t scope to specific labels/folders at the IMAP level)
App password must be regenerated if revoked
Some enterprise Google Workspace admins disable app passwords

Option 3: Your Own Google Cloud OAuth App

Maximum security. You create a Google Cloud project, configure OAuth credentials, and your agent uses your project’s credentials. Tokens stay on your infrastructure.

Best for: Enterprise deployments, compliance-sensitive environments, Google Workspace orgs.

Create a Google Cloud project

Go to Google Cloud Console → Create New Project → name it (e.g., “Moe’s AI Integration”).
Enable the Gmail API

APIs & Services → Enable APIs → Search “Gmail API” → Enable.
Configure OAuth Consent Screen

APIs & Services → OAuth Consent Screen:
- User type: Internal (if Google Workspace) or External
- App name: “Moe’s AI Agent”
- Scopes: gmail.readonly, gmail.send (add gmail.modify if agent needs to archive/label)
Create OAuth Credentials

APIs & Services → Credentials → Create Credentials → OAuth Client ID:
- Application type: Desktop app
- Download the client_secret.json file
Provide to your agent

During onboarding, choose “Own OAuth App” and upload your client_secret.json. Your agent will:
- Open an authorization URL
- You sign in with your Google account
- Authorize the requested scopes
- Agent stores the refresh token locally
Verify

Your agent confirms access and shows recent email subjects to verify.

Advantages:

Credentials never leave your infrastructure
You control exactly which scopes are granted
Can be revoked from Google Cloud Console at any time
No dependency on Moe’s AI OAuth app

Which Should I Choose?

Factor	Forwarding	IMAP/App Password	Your OAuth App
Setup time	2 minutes	5 minutes	15-20 minutes
Security	High (you control what’s forwarded)	Medium (full inbox access)	Highest (your credentials)
Inbox access	Only forwarded emails	Full inbox	Full inbox (scoped by OAuth)
Can reply as you	No (unless send-as configured)	Yes	Yes
Enterprise ready	Good for testing	Good for dedicated accounts	Yes
Requires GCP	No	No	Yes

Onboarding Flow

During setup, your agent will walk you through this:

Agent: "Would you like me to monitor an email inbox?
        I can handle support tickets, forward important
        messages, or triage your inbox."

You:    "Yes, connect my Gmail"

Agent:  "Great! How would you like to connect?

        1. Email Forwarding — easiest, I only see what you forward
        2. App Password — I access your inbox directly via IMAP
        3. Your Own OAuth — you create Google Cloud credentials (most secure)

        Which works best for your setup?"

Your agent will then guide you step-by-step through whichever option you choose, verifying each step as you go.

Troubleshooting

Agent can’t access inbox:

Verify the app password hasn’t been revoked
Check that IMAP is enabled in Gmail Settings → Forwarding and POP/IMAP
For OAuth: check that the refresh token hasn’t expired (re-authorize if needed)

Forwarded emails not arriving:

Check Gmail filter is active (Settings → Filters)
Verify the forwarding address was confirmed
Check agent logs for inbound email events

Enterprise Google Workspace blocking access:

Ask your admin to allow “Less secure app access” or whitelist the OAuth app
For IMAP: admin may need to enable IMAP at the org level
For OAuth: use “Internal” user type to skip Google verification