JUNOHUB-test/Documents/GMAIL_SETUP.md

Gmail Integration Setup Guide

This guide explains how to set up Gmail integration so that every vendor can connect their own Gmail account to receive and send customer emails.

How It Works

• One OAuth App: You create ONE Google OAuth application in Google Cloud Console
• Shared Credentials: All vendors use the same GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
• Individual Authorization: Each vendor authorizes their own Gmail account when connecting
• Separate Tokens: Each vendor's Gmail tokens are stored separately in the database

Login Method vs Gmail Integration

IMPORTANT: These are TWO separate things:

1. Login Method (How vendor logs into YOUR app):

   • Email/Password login ✅
   • Google OAuth login ✅
   • Both work independently

2. Gmail Integration (Authorizing Gmail API access):

   • Separate OAuth flow
   • Works regardless of login method
   • Vendor can connect ANY Gmail account (doesn't need to match login email)

Example Scenarios:

Scenario 1: Vendor logs in with email/password (talatfaheem2@gmail.com)

• ✅ Can connect Gmail integration
• When clicking "Connect Gmail", they'll be redirected to Google OAuth
• Can authorize the same Gmail (talatfaheem2@gmail.com) OR a different one (business@gmail.com)

Scenario 2: Vendor logs in with Google OAuth (talatfaheem2@gmail.com)

• ✅ Can connect Gmail integration
• When clicking "Connect Gmail", they'll be redirected to Google OAuth again
• Can authorize the same Gmail (talatfaheem2@gmail.com) OR a different one (business@gmail.com)

Key Point: The Gmail account they authorize doesn't need to match their login email!

Step-by-Step Setup

1. Create Google Cloud Project (One Time Setup)

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable Gmail API:
   • Go to APIs & Services > Library
   • Search for "Gmail API"
   • Click "Enable"

2. Create OAuth 2.0 Credentials

1. Go to APIs & Services > Credentials

2. Click "Create Credentials" > "OAuth client ID"

3. If prompted, configure OAuth consent screen (Google will prompt you the first time):

   • Choose "External" (unless you have Google Workspace)
   • Fill in app name, support email, developer contact
   • Note: You don't need to manually add scopes here - they're automatically requested when vendors connect
   • IMPORTANT: Add test users - Add ALL Gmail addresses that will connect (e.g., krypttech4@gmail.com, talatfaheem2@gmail.com, etc.)
   • Click "Save and Continue" through the steps

   OR if consent screen is already configured:

   • Go to APIs & Services > OAuth consent screen
   • Scroll down to "Test users" section
   • Click "+ ADD USERS"
   • Add the Gmail addresses that will connect (one per line or comma-separated)
   • Click "Add"

4. Create OAuth client:

   • Application type: "Web application"
   • Name: "JunoHub Gmail Integration" (or your choice)
   • Authorized redirect URIs (CRITICAL - must match exactly):

     http://localhost:3000/api/integrations/gmail/callback
     https://your-production-domain.com/api/integrations/gmail/callback
     

     • If using ngrok: https://your-ngrok-url.ngrok-free.dev/api/integrations/gmail/callback
     • Important: Add ALL environments you'll use (dev, staging, production, ngrok URLs)

3. Configure Environment Variables

Add to your .env file:

# Your Google Cloud OAuth credentials (shared for all vendors)
GOOGLE_CLIENT_ID="your-client-id-here.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret-here"

# Your app URL (used for OAuth redirects)
NEXTAUTH_URL="http://localhost:3000"  # or your production URL

4. Test the Integration

1. Start your application
2. Log in as a vendor
3. Go to Juno Engine > Gmail Connect
4. Click "Connect Gmail Account"
5. Sign in with any Gmail account (doesn't need to match the OAuth app owner)
6. Authorize the requested permissions
7. You should be redirected back and see "Gmail Connected"

Troubleshooting

Error: redirect_uri_mismatch

Problem: The redirect URI in your code doesn't match what's configured in Google Cloud Console.

Solution:

1. Check the error message - it will show the redirect URI being used
2. Go to Google Cloud Console > Credentials > Your OAuth Client
3. Add the exact redirect URI shown in the error to "Authorized redirect URIs"
4. Wait a few minutes for changes to propagate
5. Try again

Error: invalid_client

Problem: The GOOGLE_CLIENT_ID or GOOGLE_CLIENT_SECRET is incorrect.

Solution:

1. Double-check your .env file
2. Make sure there are no extra spaces or quotes
3. Restart your application after changing .env

Error: access_denied or "Access blocked: has not completed the Google verification process"

Problem: The OAuth app is in "Testing" mode and the user's Gmail address is not added as a test user.

Solution:

1. Go to APIs & Services > OAuth consent screen
2. Scroll down to "Test users" section
3. Click "+ ADD USERS"
4. Add the Gmail address that's trying to connect (e.g., krypttech4@gmail.com)
5. Click "Add"
6. Wait a few minutes for changes to propagate
7. Try connecting again

Note: In testing mode, you must add each Gmail address as a test user. For production, you'll need to publish your app (requires Google verification).

Important Notes

• OAuth Consent Screen: Google will prompt you to configure this the FIRST time you create OAuth credentials. After that, you can skip it. The scopes are automatically requested in the OAuth flow - you don't need to manually add them in the consent screen.
• OAuth App Owner: The email that created the OAuth app (i221735@nu.edu.pk) doesn't matter. Any Gmail account can authorize access.
• Vendor Gmail: Each vendor connects their own Gmail account (talatfaheem2@gmail.com, etc.). They don't need their own OAuth credentials.
• Redirect URI: Must match EXACTLY (including protocol, domain, port, path). No trailing slashes.
• Multiple Environments: Add redirect URIs for all environments (localhost, staging, production, ngrok).

Security Considerations

• OAuth tokens are stored securely in the database
• Each vendor's tokens are isolated (can't access each other's emails)
• Tokens are automatically refreshed when expired
• Vendors can disconnect their Gmail at any time

Production Checklist

• Gmail API enabled in Google Cloud Console
• OAuth consent screen configured
• Test users added (for testing mode) - Add all Gmail addresses that will connect
• OAuth client created with correct redirect URIs
• Environment variables set (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, NEXTAUTH_URL)
• Database migration run (prisma db push)
• Tested with at least one vendor account
• Production redirect URI added to Google Cloud Console
• For production: Publish your app (requires Google verification) OR keep adding test users as needed