How to Connect Gmail to n8n (OAuth)

You need Gmail connected to n8n to automate email workflows without manual intervention. This guide walks through OAuth 2.0 setup for both Gmail trigger nodes (to monitor incoming mail) and send nodes (to dispatch emails from workflows).

OAuth is the only authentication method that works reliably long-term. Google deprecated "less secure app access" in 2022, and app passwords don't support the full Gmail API scope needed for trigger nodes.

Required accounts:

• Active n8n instance (self-hosted version 0.220.0+ or n8n Cloud)
• Google Workspace or personal Gmail account with admin access
• Google Cloud Platform account (free tier works fine)

Time required: 15-20 minutes for first-time setup, 5 minutes for subsequent connections.

Cost: Zero. Google Cloud free tier includes 1 billion Gmail API

calls per month.

1. Navigate to console.cloud.google.com
2. Click the project dropdown in the top navigation bar (next to "Google Cloud")
3. Click "New Project" in the modal that appears
4. Enter project name: n8n-gmail-production (or your preferred naming convention)
5. Leave organization field blank unless you're using Google Workspace
6. Click "Create"
7. Wait 10-15 seconds for project creation
8. Copy the Project ID from the notification (format: n8n-gmail-production-123456)

Why this matters: Each Google Cloud project isolates API

credentials and usage quotas. Using a dedicated project prevents conflicts with other integrations.

1. In the left sidebar, click "APIs

   APIs

   Click to read the full definition in our AI & Automation Glossary.

   & Services" > "Library"
2. Type gmail api in the search bar
3. Click the "Gmail API

   API

   Click to read the full definition in our AI & Automation Glossary.

   " card (published by Google)
4. Click the blue "Enable" button
5. Wait for the "API

   API

   Click to read the full definition in our AI & Automation Glossary.

   enabled" confirmation (appears in 3-5 seconds)

Verification step: Click "APIs

& Services" > "Enabled APIs

APIs

Click to read the full definition in our AI & Automation Glossary.

& services". You should see "Gmail API

API

Click to read the full definition in our AI & Automation Glossary.

" listed with a green checkmark.

This screen is what users see when granting n8n access to their Gmail account.

1. Go to "APIs

   APIs

   Click to read the full definition in our AI & Automation Glossary.

   & Services" > "OAuth consent screen"
2. Select "External" user type (even for Google Workspace accounts)
3. Click "Create"

App information section:

• App name: n8n Email Automation
• User support email: Select your email from dropdown
• App logo: Skip (optional)
• Application home page: Enter your n8n instance URL (e.g., https://n8n.yourcompany.com)
• Application privacy policy: Skip for internal use
• Application terms of service: Skip for internal use
• Authorized domains: Add your n8n domain without protocol (e.g., yourcompany.com)

Developer contact information:

• Enter your work email address
• Click "Save and Continue"

Scopes section:

1. Click "Add or Remove Scopes"
2. Filter for "Gmail API

   API

   Click to read the full definition in our AI & Automation Glossary.

   " in the dropdown
3. Select these three scopes:

   • https://mail.google.com/ (Full Gmail access)
   • https://www.googleapis.com/auth/gmail.modify (Read and modify but not delete)
   • https://www.googleapis.com/auth/gmail.readonly (Read-only access)
4. Click "Update" then "Save and Continue"

Test users section (critical for External apps):

1. Click "Add Users"
2. Enter the Gmail address that will authenticate with n8n
3. Add up to 100 test users (limit for unverified apps)
4. Click "Save and Continue"

Summary screen:

• Review all settings
• Click "Back to Dashboard"

Publishing note: Leave the app in "Testing" mode unless you need organization-wide access. Testing mode works indefinitely for up to 100 users.

1. Go to "APIs

   APIs

   Click to read the full definition in our AI & Automation Glossary.

   & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. Application type: Select "Web application"
4. Name: n8n-gmail-oauth-client

Authorized JavaScript origins:

• Click "Add URI"
• Enter your n8n instance URL: https://n8n.yourcompany.com
• Do NOT include trailing slash

Authorized redirect URIs:

• Click "Add URI"
• Enter: https://n8n.yourcompany.com/rest/oauth2-credential/callback
• Replace n8n.yourcompany.com with your actual n8n domain
• The /rest/oauth2-credential/callback path is mandatory and case-sensitive

5. Click "Create"
6. Copy the Client ID (format: 123456789-abc123.apps.googleusercontent.com)
7. Copy the Client Secret (format: GOCSPX-abc123xyz789)
8. Click "OK" to close the modal

Save these credentials immediately. Store them in your password manager or secure documentation system.

1. Open your n8n instance
2. Click "Credentials" in the left sidebar
3. Click "Add Credential" (top right)
4. Search for "Gmail OAuth2 API

   API

   Click to read the full definition in our AI & Automation Glossary.

   "
5. Click the "Gmail OAuth2 API

   API

   Click to read the full definition in our AI & Automation Glossary.

   " option

Credential configuration:

• Credential Name: Gmail Production OAuth
• Client ID: Paste the value from Step 4
• Client Secret: Paste the value from Step 4
• Leave all other fields at default values

6. Click "Save"
7. Click the "Connect my account" button
8. New browser tab opens with Google sign-in
9. Select the Gmail account you added as a test user in Step 3
10. Click "Continue" on the permission request screen
11. Review the scopes (should match what you configured)
12. Click "Continue" to grant access
13. Browser redirects back to n8n with success message

Troubleshooting authentication failures:

• "Access blocked: This app's request is invalid" = Check redirect URI matches exactly
• "Error 403: access_denied" = Gmail account not added as test user in Step 3
• "Redirect URI mismatch" = Verify n8n instance URL matches authorized origins

Gmail trigger nodes monitor your inbox and execute workflows when new emails arrive.

1. Create new workflow or open existing workflow
2. Click the "+" button on canvas
3. Search for "Gmail Trigger"
4. Click "Gmail Trigger" node

Node configuration:

• Credential to connect with: Select "Gmail Production OAuth" from dropdown
• Event: Select "Message Received"
• Filters section:

  • Label Names: Leave empty to monitor all mail, or select "INBOX"
  • Sender: Leave empty or enter specific email address to filter
  • Subject: Leave empty or enter text to match in subject line

Polling interval:

• Default: Every 60 seconds
• Recommended for production: Every 120-300 seconds to avoid rate limits
• Gmail API

  API

  Click to read the full definition in our AI & Automation Glossary.

  free tier: 250 quota units per user per second

5. Click "Execute Node" to test
6. Send a test email to the connected Gmail account
7. Wait for polling interval to elapse
8. Node should output the email data in JSON format

Common trigger issues:

• No emails appearing = Check label filter matches where test email landed
• "Insufficient permissions" error = Re-authenticate credential with all required scopes
• Rate limit errors = Increase polling interval above 120 seconds

Gmail send nodes dispatch emails from your workflows.

1. Click "+" button after your trigger or any other node
2. Search for "Gmail"
3. Select "Gmail" (not Gmail Trigger)

Node configuration:

• Credential to connect with: Select "Gmail Production OAuth"
• Resource: "Message"
• Operation: "Send"

Message fields:

• To: Enter recipient email or use expression {{ $json.from }} to reply to sender
• Subject: Enter static text or use expression Re: {{ $json.subject }}
• Message Type: Select "Text" or "HTML"
• Message: Enter email body content

Using expressions for dynamic content:

Hello `{{ $json.payload.headers.find(h => h.name === 'From').value }}`,

Thank you for your email regarding `{{ $json.subject }}`.

This is an automated response from our n8n workflow.

Attachments (optional):

• Click "Add Field" > "Attachments"
• Use binary data from previous nodes
• Reference with expression: {{ $binary.data }}

5. Click "Execute Node" to send test email
6. Check recipient inbox for delivery
7. Verify sender shows as your authenticated Gmail account

1. Click "Execute Workflow" button (top right)
2. Workflow enters listening mode (for trigger nodes)
3. Send test email to monitored Gmail account
4. Wait for polling interval
5. Trigger node activates and passes data to send node
6. Send node dispatches reply email
7. Check execution log for success confirmation

Production deployment:

• Click the toggle switch at top of workflow to "Active"
• Workflow now runs automatically on schedule
• Monitor executions in "Executions" tab

Different Gmail operations require different OAuth scopes:

Read-only monitoring:

• https://www.googleapis.com/auth/gmail.readonly
• Use for: Trigger nodes that only read email metadata

Modify but not delete:

• https://www.googleapis.com/auth/gmail.modify
• Use for: Marking emails as read, applying labels, moving to folders

Full access (recommended for automation):

• https://mail.google.com/
• Use for: Send nodes, delete operations, full mailbox management

To change scopes after initial setup:

1. Return to Google Cloud Console > OAuth consent screen
2. Edit scopes section
3. Update scope list
4. In n8n, delete existing credential
5. Create new credential and re-authenticate

Gmail API

enforces these limits per user per second:

• 250 quota units for read operations
• 100 quota units for send operations
• 25 quota units for modify operations

Each operation costs:

• Trigger node poll: 5 units
• Send email: 100 units
• Read email body: 5 units

Staying under limits:

• Set trigger polling to 120+ seconds
• Batch operations when possible
• Monitor quota usage in Google Cloud Console > APIs

  APIs

  Click to read the full definition in our AI & Automation Glossary.

  & Services > Dashboard

If you hit rate limits:

• Increase polling intervals
• Implement exponential backoff in error handling
• Request quota increase (requires app verification for >100 users)

Credential rotation:

• Rotate OAuth client secrets every 90 days
• Update in both Google Cloud Console and n8n credentials

Access control:

• Limit test users to only those who need workflow access
• Use separate Google Cloud projects for dev/staging/production
• Never commit client secrets to version control

Monitoring:

• Enable Google Cloud audit logs for credential usage
• Set up alerts for unusual API

  API

  Click to read the full definition in our AI & Automation Glossary.

  call patterns
• Review n8n execution logs weekly for failed authentications

Your Gmail integration is now production-ready. The OAuth connection persists indefinitely unless you revoke access in Google account settings or delete the credential in n8n.