n8n Gmail Node: OAuth Setup, Operations, and CRM Use Cases

According to n8n community data, Gmail OAuth credential failures are one of the most reported issues on self-hosted n8n instances. The root cause is a single checkbox most tutorials skip entirely. This guide to n8n Gmail node send email OAuth setup walks through every step, including the two failure modes that break workflows silently. If you're running n8n and need Gmail to actually stay connected, this is the reference.

Disclosure: Some links in this article are affiliate links. If you sign up for n8n through our link, we earn a referral commission at no extra cost to you. We recommend n8n because we run 50+ production workflows on it for our own business and our clients. Our affiliate relationship does not influence the technical guidance in this tutorial.

What Is the n8n Gmail Node?

The n8n Gmail node is a native integration that connects your Gmail or Google Workspace account to n8n workflows using OAuth2 authentication. It supports four operations: Send Message, Reply, Send and Wait, and Draft. Unlike the generic Send Email (SMTP) node, the Gmail node handles email threading, human-approval pauses, and draft creation natively.

Before you start configuring credentials, you need to decide whether the Gmail node is the right choice for your workflow. The table below compares it against the Send Email (SMTP) node so you can pick the right tool.

Feature	Gmail Node (OAuth2)	Send Email Node (SMTP)
Authentication	OAuth2 via Google Cloud Console	SMTP username + password or app password
Threading / Reply support	Yes, maintains In-Reply-To headers	No, every message starts a new thread
Send and Wait (approval flow)	Yes, pauses workflow for human response	Not available
Supported providers	Gmail and Google Workspace only	Any SMTP provider (Mailgun, Resend, AWS SES, Gmail SMTP)
Delivery rate for Gmail accounts	Uses Gmail API directly, subject to Gmail sending limits	Routes through SMTP relay, same Gmail limits apply
Setup complexity (self-hosted)	Medium: requires Google Cloud Console project, OAuth consent screen, redirect URI configuration	Low: requires SMTP host, port, and credentials only
Draft creation	Yes	No

If you've already decided on the Gmail node and want OAuth setup steps, skip to Step 1. For a deeper comparison of when to choose each node, see our n8n Send Email Node reference or the dedicated n8n Send Email vs Gmail Node: Which to Use for Your Workflow.

Prerequisites

You need three things before starting: an n8n instance (cloud or self-hosted), a Google account or Google Workspace account, and access to Google Cloud Console. n8n Cloud users can skip Steps 1 through 3 entirely by using Managed OAuth2.

Here's the checklist:

• An n8n instance, either cloud-hosted or self-hosted (Docker, npm, or desktop)
• A Gmail or Google Workspace email account
• Access to Google Cloud Console (free tier works)
• Your n8n instance's OAuth callback URL (you'll grab this in Step 3)

If you're on n8n Cloud, Google provides a Managed OAuth2 option. You click "Sign in with Google" inside n8n, authorize your account, and you're done. No Client ID, no Client Secret, no Cloud Console project. The steps below are for self-hosted users or anyone who needs a custom OAuth2 credential.

In my experience building n8n workflows for small businesses, roughly 80% of Gmail credential issues come from self-hosted setups. Rain Automation's own production n8n instance (v2.22.3, Docker-hosted) runs 79 workflows, 16 of which use Gmail or Send Email nodes for client notifications, lead alerts, and warmup sequences. One example: our Prospect Reply Detector workflow, which watches the inbox for replies to outbound prospect emails and routes them for follow-up, has executed 878 times in the last 30 days on that same instance. The two gotchas I'll call out in Steps 2 and 3 are things I've had to fix across those workflows and on client instances more times than I can count. For reference on how that instance is provisioned, including the server specs and cost breakdown behind 10,000+ monthly executions, see how we set up and run n8n in production.

Step 1: Enable the Gmail API (Without This, Every Credential Attempt Fails)

Open Google Cloud Console, create a new project (or select an existing one), and enable the Gmail API. This takes about 2 minutes and gives n8n the API access it needs to send, read, and manage emails on your behalf.

1. Go to console.cloud.google.com
2. Click the project dropdown at the top of the page and select "New Project"
3. Name it something recognizable (e.g., "n8n Integrations") and click Create
4. Once the project is created, go to APIs & Services > Library
5. Search for "Gmail API"
6. Click Gmail API in the results, then click Enable

If you already have a Google Cloud project for n8n (maybe you set one up for Google Sheets or Google Calendar), add the Gmail API to that existing project instead of creating a new one. One project can hold credentials for multiple Google APIs.

This is also where you'd enable other Google APIs if you're building multi-step CRM workflows that touch Google Sheets, Calendar, or Drive alongside Gmail.

Step 2: Fix the 7-Day Token Expiry Before It Starts (OAuth Consent Screen)

The OAuth consent screen defines what your app requests access to. For n8n's Gmail node, the critical step here is setting the Publishing status to Production. Leaving it in Testing mode causes Google to expire your refresh token every 7 days, which silently breaks all Gmail workflows.

1. In your Google Cloud project, go to APIs & Services > OAuth consent screen
2. Choose a User Type:
   • Internal (Google Workspace accounts only): skips the verification process, works immediately
   • External (personal Gmail accounts): requires you to add test users during Testing mode
3. Fill in the required fields: App name, User support email, Developer contact email
4. Click Save and Continue through the Scopes and Test Users screens (n8n injects its own scopes automatically)

The 7-Day Token Expiry Fix

This is the single most common reason Gmail credentials stop working on self-hosted n8n. Here's what happens:

When your OAuth app is in Testing mode, Google enforces a hard 7-day expiry on all refresh tokens. After 7 days, your n8n credential silently loses access. Your workflows fail with "Unable to sign without access token" or "Refresh token is required" errors. You reconnect, it works for another 7 days, then breaks again.

The fix:

1. Go to APIs & Services > OAuth consent screen
2. Find the Publishing status section
3. Click Publish App
4. Confirm the prompt

That's it. Once published, refresh tokens no longer expire on a 7-day cycle. For External user types, Google may show a warning that your app is "unverified," but this only appears during the initial consent screen and does not affect functionality. You (or your users) click "Advanced" > "Go to [app name]" once during setup.

I had a property management client in metro Atlanta last year who was reconnecting their Gmail credential every Monday morning for two months. Their n8n instance handled tenant maintenance request notifications (a workflow similar to our own Prospect Reply Detector), and every Monday the workflows silently stopped sending. After we published their OAuth app to Production, that credential ran without a single disconnection for the next six months (and counting). Two clicks in Google Cloud Console fixed it permanently. The n8n community thread on refresh token failures has dozens of users who hit this same wall.

What Scopes Does n8n Request?

The built-in Gmail OAuth2 credential in n8n automatically requests these scopes:

Scope	What It Allows
gmail.modify	Read, send, delete, and organize emails
gmail.compose	Create and send new emails
gmail.send	Send emails on behalf of the user

You cannot narrow these scopes when using n8n's built-in Gmail credential type. If you reject gmail.modify at the Google consent screen, the credential will fail with a 403 error. Users who need minimal permissions (only gmail.send) would need to use the Generic OAuth2 credential type instead, which requires more manual configuration.

This is a common point of confusion. As discussed in the n8n community thread on scope restriction, the scopes are hardcoded into n8n's credential definition. It's not a bug.

Step 3: Avoid the redirect_uri_mismatch Error (OAuth Client Credentials)

In Google Cloud Console, create an OAuth 2.0 Client ID of type "Web application" and set the Authorized redirect URI to match your n8n instance's callback URL exactly. Getting the redirect URI wrong is the second most common setup failure.

1. Go to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. For Application type, select Web application
4. Name it (e.g., "n8n Gmail")
5. Under Authorized redirect URIs, add your n8n OAuth callback URL

Finding Your n8n OAuth Callback URL

In n8n, go to Settings > Personal Settings (or Settings > Community Settings on older versions). You'll see an "OAuth Redirect URL" field. It typically looks like:

• n8n Cloud: https://your-instance.app.n8n.cloud/rest/oauth2-credential/callback
• Self-hosted: https://your-domain.com:5678/rest/oauth2-credential/callback

Self-hosted users on Docker commonly hit a redirect_uri_mismatch error here. The problem is almost always one of these:

• Missing port: If your n8n runs on port 5678, the redirect URI must include :5678
• HTTP vs HTTPS: The protocol must match exactly
• Trailing slash: Google is strict about trailing slashes, so don't add one unless n8n shows one
• N8N_WEBHOOK_URL mismatch: If you've set the N8N_WEBHOOK_URL environment variable, the callback URL derives from it. Make sure this env var matches what you put in Google Cloud Console

The n8n community thread on OAuth callback failures shows this is a persistent first-time setup blocker. Double-check every character.

6. Click Create
7. Copy the Client ID and Client Secret from the popup. You'll paste these into n8n in the next step.

Step 4: Connect Without a 401 Callback Error (Adding the Gmail Credential in n8n)

Open n8n, create a new Gmail OAuth2 API credential, paste your Client ID and Client Secret, and click Connect to authorize your Google account. The credential should show a green "Connected" status when complete.

1. In n8n, go to Credentials in the left sidebar
2. Click Add Credential (or the + button)
3. Search for "Gmail OAuth2 API" and select it
4. Paste your Client ID and Client Secret from Step 3
5. Click Sign in with Google (or "Connect" depending on your n8n version)
6. Complete the Google sign-in flow. If your app is External and unverified, click Advanced > Go to [app name]
7. Grant all requested permissions
8. Return to n8n. The credential should show Connected with a green indicator

If you see an error at this stage, check these in order:

• Redirect URI matches exactly (Step 3)
• Gmail API is enabled in your Cloud project (Step 1)
• App is published to Production (Step 2)

For n8n Cloud users with Managed OAuth2, you skip all of this. Just select "Sign in with Google" when creating the credential. No Client ID or Secret needed.

Now that your credential is connected, you're ready to build workflows. If you want to test it quickly, the n8n webhook guide shows how to trigger a workflow manually so you can verify your Gmail sends are working before connecting a production trigger.

The Four Gmail Node Operations

The n8n Gmail node supports four distinct operations: Send Message, Reply, Send and Wait, and Draft. Each serves a different workflow pattern, from simple notifications to human-in-the-loop approval chains.

Send Message

The most common operation. It sends a new email from your connected Gmail account. You can set To, CC, BCC, Subject, and Body (plain text or HTML). Attachments are supported via binary data from upstream nodes.

Use it for: automated notifications, report delivery, alert emails, drip campaign messages.

Reply

Sends a reply within an existing email thread. You provide the Message ID of the original email, and the Gmail node handles In-Reply-To and References headers automatically. This keeps the reply in the same Gmail conversation, which the Send Email SMTP node cannot do.

Use it for: automated customer responses, follow-up sequences, ticket acknowledgments.

This threading capability is actually why many users switch from SMTP to the Gmail node. In community forums, it's a recurring discovery: people realize their SMTP-based auto-replies create new threads every time, confusing customers. The Gmail node's Reply operation solves that.

Send and Wait

This is the operation that makes the Gmail node unique. It sends an email and then pauses the entire workflow until the recipient takes action. The email includes Approve and Reject buttons (or custom action labels). When the recipient clicks one, n8n resumes the workflow with the response.

Here's what happens step by step:

1. The workflow reaches the Gmail node configured for Send and Wait
2. n8n sends the email with embedded action buttons
3. The workflow execution pauses (it's stored in n8n's database, not holding a thread)
4. The recipient opens the email and sees the message plus Approve/Reject buttons
5. They click one of the buttons, which hits an n8n webhook URL
6. n8n resumes the workflow. In n8n v1.x, the approval result is available at $json.data.response.lastResponse.body.action. Starting in n8n v2.x (including the current v2.22.x), the Wait node output has been simplified, but the exact path depends on your node configuration and version. Always test the output by running the workflow once and inspecting the JSON output panel before referencing the variable in downstream nodes
7. Downstream nodes can branch based on the response (IF node, Switch node)

Picture this: your finance team gets an email saying "New expense report from Sarah, $2,400 for conference travel. Approve or Reject?" They click Approve in their inbox, and the workflow automatically updates the accounting system, notifies Sarah, and logs the approval. No dashboard login required.

This operation is completely absent from the Send Email SMTP node. If you need human approvals in your deal pipeline, Send and Wait is the tool.

Draft

Creates a draft in your Gmail Drafts folder without sending it. The email sits in Drafts until you (or another workflow) sends or deletes it.

Use it for: AI-generated email drafts that need human review before sending, scheduled content that needs a final check, compliance workflows where outbound messages require approval.

Operations Comparison

Operation	Sends Immediately	Pauses Workflow	Requires Recipient Action	Best For
Send Message	Yes	No	No	Notifications, alerts, reports
Reply	Yes	No	No	Threaded follow-ups, ticket replies
Send and Wait	Yes	Yes	Yes (Approve/Reject)	Expense approvals, content review, human-in-the-loop
Draft	No	No	No	AI drafts, compliance review, scheduled sends

Practical Walkthrough: Gmail Notification When a HubSpot Contact Is Created

This workflow fires a formatted Gmail notification to your inbox whenever a new contact is created in HubSpot, pulling the contact's name, email, and source into an HTML email template. It takes about 5 minutes to build using three nodes.

If you've already set up n8n with HubSpot, adding a Gmail notification is straightforward. Here's the full setup:

Step 1: Add the HubSpot Trigger Node

1. Create a new workflow in n8n
2. Add a HubSpot Trigger node
3. Set the Event to contact.creation
4. Connect your HubSpot credentials (API key or OAuth2)
5. Save and activate. This node fires whenever a new contact is created in your HubSpot CRM

The trigger outputs a JSON payload with the contact's properties. The fields you'll use are nested under properties.

Step 2: Add a Set Node to Extract Fields

Add a Set node after the HubSpot Trigger. Map these fields:

• firstName: {{ $json.properties.firstname }}
• email: {{ $json.properties.email }}
• source: {{ $json.properties.hs_analytics_source }}
• createDate: {{ $json.properties.createdate }}

Note on field paths: HubSpot's n8n node outputs properties as a flat object (e.g., $json.properties.firstname), not nested under .value. If you're using an older version of the HubSpot node, the path might be $json.properties.firstname.value instead. Test your trigger output to confirm.

Step 3: Add the Gmail Node (Send Message)

1. Add a Gmail node after the Set node
2. Select the Send Message operation
3. Set To to your notification email address
4. Set Subject to: New HubSpot Contact: {{ $json.firstName }} ({{ $json.source }})
5. Set Email Type to HTML
6. Set the HTML Body to:

<h2>New Contact Created in HubSpot</h2>
<p><strong>Name:</strong> {{ $json.firstName }}</p>
<p><strong>Email:</strong> {{ $json.email }}</p>
<p><strong>Source:</strong> {{ $json.source }}</p>
<p><strong>Created:</strong> {{ $json.createDate }}</p>
<p>View in <a href="https://app.hubspot.com/contacts/">HubSpot</a></p>

7. Under Options, toggle off "Append n8n Attribution" if you don't want the "Sent with n8n" footer
8. Select your Gmail OAuth2 credential from the dropdown
9. Save and test the workflow

When a new contact hits HubSpot, you'll get a clean HTML email in your inbox within seconds. For a more advanced version that routes leads to different team members based on source or deal value, check out the n8n HubSpot deal automation guide.

The n8n workflow template library has a pre-built version of this pattern that also sends a Slack message alongside the Gmail notification.

Common Issues and How to Fix Them

The five most frequent n8n Gmail node errors all have straightforward fixes. Most trace back to the OAuth consent screen configuration or the redirect URI.

Here's the troubleshooting reference:

1. Token Expired After 7 Days

Symptom: Gmail credential works for about a week, then workflows fail with "Refresh token is required" or "Unable to sign without access token."

Fix: Your Google Cloud app is still in Testing mode. Go to Google Cloud Console > APIs & Services > OAuth consent screen > Publishing status > Publish App. Reconnect the credential in n8n after publishing. See the detailed explanation in Step 2.

2. Redirect URI Mismatch

Symptom: Clicking "Sign in with Google" in n8n returns a redirect_uri_mismatch error page.

Fix: The redirect URI in Google Cloud Console must match your n8n callback URL character-for-character. Check the port (:5678), protocol (https vs http), and path (/rest/oauth2-credential/callback). No trailing slash. See the redirect URI section in Step 3.

3. OAuth Callback 401 on Self-Hosted

Symptom: The Google sign-in completes, but n8n shows a 401 error when the callback returns.

Fix: Verify that your N8N_WEBHOOK_URL environment variable matches the domain and port your n8n instance is actually accessible at. If you're behind a reverse proxy (nginx, Caddy), the N8N_WEBHOOK_URL should use the proxy URL, not the internal localhost:5678 address.

4. Security Warning About gmail.modify Scope

Symptom: Google shows a warning that the app is requesting broad permissions including gmail.modify.

Fix: This is expected behavior, not a bug. The built-in n8n Gmail credential requests gmail.modify, gmail.compose, and gmail.send automatically. Click Advanced > Go to [app name] to proceed. The scope list is hardcoded in n8n's source code and cannot be narrowed without using a Generic OAuth2 credential.

5. "Unable to Sign Without Access Token"

Symptom: A previously-working credential fails with this error after a period of inactivity.

Fix: This is usually the 7-day Testing mode expiry (see issue 1). If your app is already published, try reconnecting the credential: go to Credentials, open the Gmail credential, and click "Reconnect." If that doesn't work, delete the credential, create a new one with the same Client ID and Secret, and re-authorize.

Gmail Node vs Send Email (SMTP) Node: Quick Reference

Use the Gmail node when you have a Google or Google Workspace account and need OAuth security, email threading, reply operations, or Send and Wait approvals. Use the Send Email node when you need a third-party SMTP provider like Mailgun, Resend, or AWS SES, or when you want the simplest possible setup.

The comparison table at the top of this article covers the key differences. For a full deep-dive on the SMTP node's parameters, authentication options, and configuration, see our n8n Send Email Node tutorial.

Here's the decision in one sentence: if your emails come from a Gmail address and you need threading or approvals, use the Gmail node. If your emails come from a custom domain routed through a third-party SMTP service, use the Send Email node.

When App Passwords Actually Beat OAuth (Contrarian Take)

Here's something conventional wisdom gets wrong: the common advice is that OAuth is always the superior authentication method for Gmail in n8n. For most use cases, that's true. But for simple send-only notification workflows running on n8n Cloud, a Gmail App Password through the SMTP node is genuinely lower-maintenance than OAuth.

Why? OAuth requires a Google Cloud Console project that can be accidentally misconfigured, rotated by a team member who doesn't know what it does, or broken by Google's periodic consent screen UI changes. App Passwords, by contrast, are a single credential string with no consent screen, no redirect URI, no 7-day Testing mode trap, and no scope negotiation. They just work.

Before setting up OAuth, run through what I call The Three-Question Gmail Auth Test. If all three answers are "yes," App Passwords via the Send Email node are the lower-maintenance choice:

1. Does the workflow only send emails? It never reads, threads, or uses Send and Wait approvals.
2. Is the instance on n8n Cloud? You don't manage the redirect URI or the Docker environment.
3. Are App Passwords enabled in your Google Workspace admin? (Increasingly, admins disable them, so check first.)

If all three are true, an App Password through the Send Email node eliminates every failure mode covered in this guide. You lose threading and approval flows, but you gain zero-maintenance authentication.

So when should you still choose OAuth? When the answer to any of those three questions is "no." You need a Gmail node operation beyond basic sending, you're self-hosting and need the redirect URI to work reliably, or your Workspace admin has locked down App Passwords. For everything else, the simpler path is the more reliable one.

And if you're building broader automation workflows for your business, the choice between n8n and other platforms like Make matters more than which email node you pick.

Frequently Asked Questions

The six questions below cover the most common Gmail OAuth setup problems, scope requirements, and multi-account configurations for n8n. Each answer is written to stand alone -- you can read any one of them without reading the rest of the article.

How do I set up Gmail OAuth for n8n?

Create a Google Cloud Console project, enable the Gmail API, configure the OAuth consent screen (and publish it to Production), create OAuth client credentials with your n8n callback URL as the redirect URI, then paste the Client ID and Secret into n8n's Gmail OAuth2 API credential. The full process takes 10 to 15 minutes.

Can n8n access Gmail without a password?

Yes. The Gmail node uses OAuth2, which means you authorize n8n through Google's sign-in flow. No Gmail password is ever stored in n8n. Google issues an access token and refresh token that n8n uses to make API calls on your behalf.

Does n8n support multiple Gmail accounts?

Yes. You can create multiple Gmail OAuth2 API credentials in n8n, each connected to a different Google account. When adding a Gmail node to a workflow, you select which credential to use from a dropdown. Each credential requires its own OAuth authorization.

What Gmail scopes does n8n request during OAuth authorization?

n8n's built-in Gmail credential requests three scopes: gmail.modify, gmail.compose, and gmail.send. These scopes allow n8n to read, send, and manage emails. You cannot reduce these scopes with the built-in credential type. For minimal permissions, use a Generic OAuth2 credential instead.

Why does my Gmail credential keep disconnecting in n8n self-hosted?

The most common cause is leaving your Google Cloud OAuth app in Testing mode, which enforces a 7-day refresh token expiry. Go to Google Cloud Console, then APIs and Services, then OAuth consent screen, then click Publish App under Publishing status. Reconnect the credential after publishing.

Can n8n access Gmail with a service account instead of OAuth?

Service accounts can access Gmail only in Google Workspace environments where domain-wide delegation is configured. For personal Gmail accounts, OAuth2 is the only supported method. Most n8n users find OAuth2 simpler to set up than service account delegation.

Next Steps

You now have a working Gmail OAuth2 credential in n8n, an understanding of all four operations, and a template for CRM-triggered email notifications. But email is just one piece of workflow automation.

If you're looking to connect more of your business tools, our n8n CRM integration tutorial covers connecting CRM platforms to n8n for automated lead routing.

If you want to go further than individual nodes and build workflows that make decisions end to end, see our guide on AI agents and automation workflows.

And for teams building complex multi-step workflows with branching logic and automated follow-ups, Rain Automation offers custom workflow design and automation consulting.

Need help setting up n8n workflows for your business? Get in touch and we'll build the automation your team actually needs.

Disclosure: This article contains affiliate links to n8n. Rain Automation may earn a commission at no additional cost to you.