Linking Gmail to n8n allows you to automate email processing, parse invoices, send customized reports, and track lead interactions. However, Google's developer settings can be intimidating, leading many developers to believe they need a paid enterprise console account. This guide explains how to integrate Gmail for free using a personal Google Account and a "testing mode" application.

1. Create a Project on Google Cloud Console

First, navigate to the Google Cloud Console. Google projects are completely free for personal API access:

  • Click on **Select a Project** > **New Project**.
  • Enter a name like `My Self-Hosted n8n` and hit Create.
  • Ensure the newly created project is selected in the console header dropdown.

2. Enable the Gmail API

In the sidebar, select **APIs & Services** > **Library**. Search for **Gmail API**, click on it, and click **Enable**. This register the API scopes inside your project space.

3. Setup the OAuth Consent Screen

To acquire credentials, you must configure Google's OAuth consent screen:

  • Go to **OAuth Consent Screen** in the sidebar.
  • Choose **User Type: External** (personal accounts cannot choose Internal).
  • Fill in the App Name (e.g. `n8n Helper`) and your email.
  • Under Scopes, add: https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.send.
  • Publishing Status: Keep the application in **Testing** status. Do not submit for verification. Verification is only needed if you are building an app for hundreds of unknown external users.
  • Under **Test Users**, add your own Gmail address. Only users listed here will be allowed to authorize the connection.

4. Create OAuth2 Credentials

Go to **Credentials** > **Create Credentials** > **OAuth Client ID**:

  • Select **Application Type: Web Application**.
  • Under **Authorized Redirect URIs**, paste the redirect URI provided inside your n8n Gmail node settings window (e.g., https://my-n8n-domain.com/rest/oauth2-credential/callback).
  • Click **Create** and save your Client ID and Client Secret values.

💡 Note on Token Expiry: Since the Google App is kept in "Testing" mode, authorize refresh tokens will expire every 7 days by default. If your credentials disconnect weekly, simply log back into n8n and re-authenticate the Gmail node, or publish the application to production status (even without verification, personal accounts can keep tokens active longer under specific parameters).