← Back to Command Center
📧 Gmail Integration Setup
⏱️ Estimated time: 15-20 minutes | 🔐 Security: OAuth 2.0 with refresh tokens
What you'll accomplish: Give your Molty read/draft/organize access to Gmail.
Molty can read emails, compose drafts (for your approval), manage labels, and organize — but cannot send live messages without your explicit permission.
📋 Pre-Flight Checklist
- Google account with Gmail access
- Terminal/command line access on your machine
- Python 3 installed (check with
python3 --version)
🔧 Part 1: Google Cloud Project Setup
1 Create a Google Cloud Project
Go to Google Cloud Console ↗
Look for the project selector dropdown in the top-left corner (currently shows your organization or "Select a project"):
Screenshot: Click the project dropdown in top-left
images/01-project-dropdown.png
Click it, then click "New Project" in the popup.
Screenshot: "New Project" button in the dropdown
images/02-new-project-button.png
Fill in:
- Project name:
molty-gmail (or any name you prefer)
- Organization: Leave blank (or select yours)
- Location: No organization
Screenshot: New project form filled out
images/03-project-form.png
Click Create and wait 5-10 seconds for the project to provision.
2 Enable the Gmail API
Once your project is created and selected, go to the navigation menu (☰) → APIs & Services → Library
Screenshot: APIs & Services → Library
images/04-api-library.png
Search for "Gmail API" and click on it:
Screenshot: Searching "Gmail API"
images/05-search-gmail.png
Click the Enable button:
Screenshot: Enable button for Gmail API
images/06-enable-gmail.png
✓ Success indicator: You should see "API Enabled" and a green checkmark.
3 Configure OAuth Consent Screen
Go to navigation menu → APIs & Services → OAuth consent screen
Screenshot: OAuth consent screen menu item
images/07-oauth-menu.png
Select External (unless you're in a Google Workspace org):
Screenshot: External user type selected
images/08-external-user-type.png
Click Create and fill in the app information:
- App name: Your Molty's name (e.g., "Atlas")
- User support email: Your Gmail address
- App logo: Skip (optional)
Screenshot: App information form
images/09-app-info.png
Click Save and Continue.
⚠️ Scopes step: Click Save and Continue again (we'll add scopes in the next step, not here).
On the Test users screen, click Add Users and add your own email address. Then click Save and Continue.
Screenshot: Test users section with your email added
images/10-test-users.png
Click Back to Dashboard.
🔑 Part 2: Create OAuth Credentials
4 Create OAuth Client ID
Go to navigation menu → APIs & Services → Credentials
Click Create Credentials → OAuth client ID:
Screenshot: Create Credentials dropdown
images/11-create-credentials.png
Select Desktop app as the Application type:
Screenshot: Application type "Desktop app" selected
images/12-desktop-app.png
Name it something like Atlas-Desktop or Molty-Desktop:
Screenshot: Name field filled out
images/13-client-name.png
Click Create.
🎉 Success! You'll see a popup with your Client ID and Client Secret.
IMPORTANT: Click Download JSON to save these credentials to your computer. Also copy them to a temporary text file — you'll need them in the next step.
Screenshot: OAuth client created popup with Download JSON button
images/14-client-created.png
Click OK to close the popup.
🚀 Part 3: Authorize Your Accounts
5 Run the OAuth Flow Script
Your Molty provided a helper script. In your terminal, run:
python3 scripts/gmail_oauth_flow.py "YOUR_CLIENT_ID" "YOUR_CLIENT_SECRET"
💡 Pro tip: Replace the placeholders with the actual values from the JSON you downloaded, or copy-paste directly from the Google Cloud popup.
The script will output a URL. Open it in your browser and make sure you're signed into the Gmail account you want to authorize.
Screenshot: Terminal showing the script output with URL
images/15-script-output.png
You'll see a Google permissions screen. Click Allow to grant access:
Screenshot: Google permissions consent screen
images/16-google-consent.png
Copy the authorization code from the browser and paste it back in the terminal:
Screenshot: Authorization code displayed in browser
images/17-auth-code.png
The script will then ask if you want to add another account. Type y to add more Gmail accounts (personal, work, Phaser, etc.) or n to finish.
Screenshot: Terminal asking to add another account
images/18-add-another.png
6 Set Environment Variables
When finished, the script outputs something like:
export GMAIL_CLIENT_ID="123456789-abc123.apps.googleusercontent.com"
export GMAIL_CLIENT_SECRET="GOCSPX-xyz789"
export GMAIL_REFRESH_TOKEN_PERSONAL="1//abc-def..."
export GMAIL_REFRESH_TOKEN_WORK="1//xyz-123..."
export GMAIL_REFRESH_TOKEN_PHASER="1//phaser-token..."
Add these to your environment. Options:
- Option A: Add to
~/.bashrc or ~/.zshrc for persistence
- Option B: Add to a
.env file loaded by your Molty's Docker/container setup
- Option C: Set temporarily in current session:
export VAR=value
⚠️ Security note: Never commit these tokens to git. Add .env to your .gitignore.
✅ Part 4: Verify Everything Works
7 Test the Connection
Ask your Molty: "List my Gmail labels" or "Check my unread emails"
If configured correctly, your Molty should respond with data from your Gmail account.
✓ Success! Your Molty now has secure, token-based access to Gmail.
Troubleshooting:
- If you get "invalid_grant" — the refresh token expired. Re-run the script.
- If you get "unauthorized" — check that the environment variables are set correctly.
- If Google shows "This app isn't verified" — that's normal for external OAuth. Click "Advanced" → "Go to [app name] (unsafe)".
📝 Quick Reference
| What Molty Can Do |
What Molty Cannot Do |
✓ Read all emails
✓ Search and filter
✓ Create drafts
✓ Label and organize
✓ Archive/trash
|
✗ Send live emails (requires your approval)
✗ Delete permanently without confirmation
✗ Access other Google services (Calendar, Drive, etc.)
|
Molty Guides • Gmail Integration • Last updated: 2026-02-07