On
n8n tutorial - Lesson 06: Connect Gmail to n8n: OAuth Setup & Reading Emails

Hi everyone, in this post we are going to walk through how to set up the n8n Gmail integration from scratch — enabling OAuth, reading emails, and applying labels using real workflow steps. This is Session 6 of our n8n Workflow Automation Tutorial series, and it is where Week 2 kicks off with some genuinely useful, production-ready patterns.

How to do:

Step 1 — Enable Gmail API and Set Up OAuth in Google Cloud Console

Before n8n can talk to your Gmail, you need to enable the Gmail API inside Google Cloud Console and add the correct OAuth scope.

  1. Go to Google Cloud Console and open your project. In this tutorial we use a project called Default Gemini Project — you can use any existing project you already have.
  2. In the left menu, go to APIs & Services → Library, search for Gmail API, and click Enable.
  3. Now go to APIs & Services → OAuth Consent Screen. Scroll down to the Data Access section and click Add or Remove Scopes.
  4. Add the scope https://mail.google.com/. This is a restricted scope, but if your app is still in Testing mode and your account is added as a Test User, Google will let you authorize it without a full verification review.
  5. Save the consent screen settings.

Tip — Reuse your existing OAuth Client: If you already set up an OAuth Client ID for Google Sheets in a previous session (we called ours n8n-sheets-client), you do not need to create a new one. One OAuth Client can cover multiple Google APIs. Just reuse the same Client ID and Client Secret — you will simply sign in again and Google will request the new Gmail scope during authorization. This follows a clean convention: one OAuth Client, many Google APIs.

Step 2 — Create the Gmail Credential in n8n

  1. Open n8n and go to Credentials → Add Credential. Search for Gmail OAuth2.
  2. Name the credential Gmail (Personal) (or any name that helps you identify it).
  3. Paste your Client ID and Client Secret from the OAuth Client you set up in Google Cloud Console.
  4. Click Sign in with Google. A Google authorization window will appear. Select your account, accept the Gmail scope, and click Allow.
  5. You should see a green Connection Tested Successfully message. Click Save.

Step 3 — Read Emails with Gmail Get Many

Now let's build a simple playground workflow to read emails. Create a new workflow and name it T2-B2-Gmail-Playground.

  1. Add a Manual Trigger node as the starting point.
  2. Add a Gmail node. In the new n8n UI, instead of selecting a Resource and Operation separately, you will see a flat Action picker. Choose Get Many.
  3. Connect it to your Gmail credential.
  4. First test run — Simplify ON, Limit 5: Leave Simplify turned on and set Limit to 5. Click Execute Node. You will get a clean, compact output with just the core fields you need.
  5. Second test run — Simplify OFF, Limit 5: Turn Simplify off and run again. Here is something important to know: the raw Gmail API returns a nested MIME structure with fields like payload and internalDate. But n8n pre-processes this for you. Even with Simplify off, the output is already flattened into clean fields: headers, text, html, attachments, and a label array where each item has both an id and a human-readable name. Do not assume the raw Gmail API structure — always run the node first and check the JSON tab to see what n8n actually gives you.
  6. Third test run — Filter unread emails: In the Filters section, add a search query: is:unread. Run it again. Now you only get unread emails, and you will see the UNREAD label in the label array.

Production tip — What to feed an AI classifier: When you plan to pass email data to an AI model for classification, only send these three fields: headers.from, headers.subject, and snippet. Together they cost roughly 150 tokens per email. Avoid sending the html field — it can be 5,000 to 10,000 tokens per email and will burn through your AI budget fast. We will use this pattern in the email classification pipeline coming in the next session.

Step 4 — Create Custom Gmail Labels

To organize emails processed by your n8n workflow, create a dedicated set of labels in Gmail directly from n8n. Create a new workflow named T2-B3-Setup-Labels.

  1. Add a Manual Trigger node.
  2. Add a Gmail node and choose the action Create Label.
  3. In the Label Name field, type the name of the first label. Run the workflow. Then change the name and run again for each label you need. We created five labels for our Week 2 project:
    • n8n/Important
    • n8n/Awaiting Reply
    • n8n/Invoice
    • n8n/Newsletter
    • n8n/Marketing Spam
  4. Notice the n8n/ prefix. Gmail supports nested labels using a forward slash. Using a prefix like n8n/ keeps all your automation labels grouped together and separate from your personal labels. This is a clean naming convention worth adopting from the start.

Step 5 — Add a Label to an Email

Now let's test adding a label to a real email. Go back to your T2-B2-Gmail-Playground workflow and extend it.

  1. After the Gmail Get Many node, add another Gmail node and choose the action Add Label.
  2. Set Limit to 1 in the Get Many node so you only process one email for this test.
  3. In the Add Label node, set Message ID to {{ $json.id }} to reference the email from the previous node.
  4. Set Label to n8n/Important.
  5. Click Execute Workflow.
  6. Check the output of the Add Label node. You will notice it returns raw label IDs like Label_1 — it does not enrich the label with a human-readable name the way Get Many does. This is a known difference between operations in the same node. Always check the JSON tab for each operation independently.
  7. Go to your Gmail inbox in the browser and open that email. You should see the n8n/Important label chip attached to it. That confirms the operation worked correctly. Do not rely only on the n8n output panel — verify in the actual service when the output is ambiguous.

A Quick Note on Cost and Quota

One practical question that comes up right after connecting Gmail: does calling the Gmail API cost anything? The short answer is no. The Gmail API is completely free. Google does enforce quota limits — 250 units per second per user and around 1 billion units per day per project — but for personal automation these limits are essentially never a concern.

The real cost in any n8n Gmail workflow is the AI tokens you spend on classification or analysis. For a personal email automation running every 15 minutes and processing a moderate volume, expect something in the range of a dollar or two per month. Keep this in mind before you build a large pipeline: always estimate your AI token cost first, and keep the data you send to the AI model as small as possible.

Key Lessons from This Session

  1. Always run the node and check the JSON tab first. Do not trust the Gmail API documentation to predict what n8n gives you. n8n flattens and enriches the raw API response, and the output can look very different from what the original API returns.
  2. Different operations on the same node can return different shapes. Gmail Get Many enriches labels with names. Gmail Add Label returns raw IDs. Check each operation independently.
  3. The new n8n UI uses a flat Action picker instead of separate Resource and Operation dropdowns. If your UI looks different from older tutorials, this is why.
  4. One OAuth Client can cover multiple Google APIs. You do not need a new Client ID for every Google service you connect.

What Comes Next

In the next session of this n8n tutorial series, we will build a full end-to-end email classification pipeline. It will use a Schedule Trigger running every 15 minutes, pull only unread and unclassified emails, pass the minimal fields to an AI model for classification, and then route each email to the correct label using a Switch node. That is where all the pieces we set up today come together into a real automated workflow.

Conclusion:

Setting up the n8n Gmail integration is straightforward once you understand the OAuth scope requirement and the way n8n flattens Gmail's raw API response. With the credential in place and these basic read and label operations working, you now have a solid foundation for building a fully automated email management workflow as part of your n8n workflow automation practice.

If you have any questions, feel free to leave a comment below. Thank you!

Tags: n8n gmail integration, n8n tutorial, n8n workflow automation, gmail oauth n8n, n8n email automation, google cloud oauth setup, n8n gmail labels, n8n beginner tutorial

Maybe you are interested!