Getting Started with n8n

You get an email. It needs to be read, understood, and forwarded as a concise summary to a team chat. You do it manually, every day, multiple times. Now imagine that whole chain running on its own — triggered on a schedule, reading your Gmail, summarizing the content with AI, and posting the result to Telegram — without writing a backend or deploying anything.

That is exactly what n8n enables. This article walks you through what n8n is, how to run it locally with Docker, how to connect Gmail and Telegram, and how to build a real automation that ties them all together.

What is n8n?

n8n (pronounced "n-eight-n") is an open-source, self-hostable workflow automation platform. Think of it as a programmable glue layer between your tools and services. You build automations visually by connecting nodes on a canvas — each node either listens for something, processes data, or acts on an external service.

Unlike fully managed alternatives (Zapier, Make), n8n gives you:

• Full data ownership — your credentials and payloads never leave your infrastructure.
• Code escape hatches — drop into JavaScript or Python inside any workflow when visual nodes aren't enough.
• AI-native nodes — built-in LLM nodes (OpenAI, Anthropic, etc.) for summarization, classification, and generation.
• Self-hosting — run it on your machine, a VPS, or Kubernetes.

Concepts

Before building anything, it helps to understand a handful of core terms. Everything in n8n maps to one of these ideas.

Expressions deserve a quick extra note. Inside any node field you can write {{ $json.subject }} to pull the subject field from the previous node's output. You can also do arithmetic, string manipulation, and call built-in helpers — all inline, without a separate code node.

Running n8n Locally

Docker Setup

The fastest way to get n8n running is with Docker. The command below starts a container with basic auth enabled and mounts a local folder so your workflows persist across restarts.

docker run -d \
  --name n8n-container \
  -p 5678:5678 \
  -e N8N_BASIC_AUTH_ACTIVE=true \
  -e N8N_BASIC_AUTH_USER=admin \
  -e N8N_BASIC_AUTH_PASSWORD=admin123 \
  -e N8N_HOST=localhost \
  -e N8N_PORT=5678 \
  -e N8N_PROTOCOL=http \
  -v "$(pwd)/n8n-data":/home/node/.n8n \
  n8nio/n8n

What each flag does:

• -p 5678:5678 — maps container port to your host.
• N8N_BASIC_AUTH_* — protects the UI with a username/password.
• -v "$(pwd)/n8n-data":/home/node/.n8n — persists workflows, credentials, and settings in a local n8n-data/ folder.

Tip: For production, replace admin123 with a strong password and use HTTPS behind a reverse proxy (Nginx or Caddy).

Accessing the Editor

Once the container is running, open http://localhost:5678 in your browser. Log in with the credentials you set (admin / admin123) and you will land on the n8n canvas — a blank workflow editor ready for your first automation.

# Check the container is healthy
docker ps --filter name=n8n-container

# Follow logs in real time
docker logs -f n8n-container

Connecting Gmail

n8n communicates with Gmail through the official Gmail API using OAuth 2.0. You need a Google Cloud project with credentials before n8n can read or send emails on your behalf.

Create a Google OAuth App

1. Go to Google Cloud Console and create a new project (or select an existing one).

2. Navigate to APIs & Services → Library and enable the Gmail API.

3. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.

   At this point Google will show a warning:

   "To create an OAuth client ID, you must first configure your consent screen"

   Click Configure consent screen — this is a required one-time setup. The wizard has four steps:

   Step 1 — App Information

   Fill in the required fields:

   • App name — anything descriptive, e.g. n8n local
   • User support email — your Gmail address

   Click Next.

   Step 2 — Audience

   Choose who can use this OAuth app:

   • Pick External if you are using a personal Google account.
   • Pick Internal only if you have a Google Workspace organization.

   With External selected, the app starts in Testing mode — only users you explicitly add as test users can authorize it. This is exactly what you want for local n8n use.

   Click Next.

   Step 3 — Contact Information

   Enter your Gmail address as the Developer contact email. This is just for Google to reach you if anything changes with the API.

   Click Next.

   Step 4 — Finish

   Review the summary and click Back to Dashboard. No further action needed here.

   You do not need to publish the app or go through Google's verification process. Keeping it in Testing mode is perfectly fine for personal and local use with n8n.

   Once the consent screen is configured, go back to Credentials → Create Credentials → OAuth client ID and continue below.

4. Choose Web application as the application type.

5. Under Authorized redirect URIs, add:

   http://localhost:5678/rest/oauth2-credential/callback
   

6. Copy the Client ID and Client Secret.

Add Gmail Credentials in n8n

1. In n8n, click Credentials in the left sidebar, then Add credential.
2. Search for Gmail OAuth2 API.
3. Paste the Client ID and Client Secret from the step above.
4. Click Sign in with Google — a Google consent window will open. Approve the scopes.
5. n8n stores the access and refresh token. Your credential is now reusable across all Gmail nodes.

Getting a 403 error? This happens because your Google app is in Testing mode and your Gmail address hasn't been added as a test user. Go back to Google Auth Platform → Audience (left sidebar) → scroll down to the Test users section → Add users, enter your Gmail address, and save. Then try Sign in with Google again.

Connecting OpenAI

OpenAI is simpler to connect than Gmail — there is no OAuth flow, just a single API key.

Get an OpenAI API Key

1. Go to platform.openai.com and sign in (or create an account).
2. Navigate to API Keys in the left sidebar (or go directly to platform.openai.com/api-keys).
3. Click Create new secret key, give it a name (e.g. n8n local), and copy the key.

Important: The key is only shown once. Copy it now and store it somewhere safe — you cannot retrieve it again from the dashboard.

Add OpenAI Credentials in n8n

1. In n8n, click Credentials in the left sidebar, then Add credential.
2. Search for OpenAI API.
3. Paste your API key into the API Key field.
4. Save. The credential is ready to use in any OpenAI node.

Connecting Telegram

Telegram integration is simpler than Gmail — it uses a static bot token rather than OAuth.

Create a Telegram Bot

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to pick a name and username.
3. BotFather replies with a token that looks like 7123456789:AAF....
4. Copy that token — you will need it in n8n.
5. To get your Chat ID (where messages will be sent):
   • Open Telegram, find your bot by username, and press Start or send it any message (e.g. "hello"). This step is required — getUpdates returns an empty result if the bot has never received a message.
   • Then open this URL in your browser (replace <YOUR_TOKEN> with your actual token):

   https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
   

   • Look for "chat": {"id": ...} in the JSON response and copy that number — that is your Chat ID.

Add Telegram Credentials in n8n

1. In n8n, click Credentials in the left sidebar, then Add credential.
2. Search for Telegram API.
3. Paste your bot token.
4. Save. The credential is ready to use in any Telegram node.

Real-World Example: Email Digest to Telegram

Now let's put it all together. The workflow will:

1. Trigger automatically whenever a new email arrives in Gmail.
2. Summarize it using an AI model.
3. Send the summary to a Telegram chat instantly.

Creating a Workflow

Before adding any nodes, you need to create a blank workflow canvas:

1. In n8n, click Workflows in the left sidebar.
2. Click Create Workflow (top right corner).
3. Give it a name — e.g. Email Summary to Telegram — by clicking the title at the top of the canvas.
4. You now have an empty canvas. Nodes are added by clicking the + button on the canvas or pressing Tab.

Tip: n8n auto-saves your workflow as you build. You can also manually save with Ctrl+S (or Cmd+S on Mac).

Workflow Overview

flowchart LR
    A["📧 Gmail Trigger\n(On new email)"] --> B["🤖 OpenAI\n(Summarize email)"]
    B --> C["📨 Telegram\n(Send summary)"]

Step 1: Trigger — New Email

Add a Gmail Trigger node (not the regular Gmail node — look for the one with a lightning bolt icon).

Configure it as follows:

• Credential: select your Gmail OAuth credential.
• Event: Message Received
• Poll Times: set to every minute for near-real-time response.
• Filters → Read Status: Unread emails only — this ensures the workflow only triggers for emails you haven't read yet.

Whenever a new unread email lands in your inbox, this node fires and passes the email data to the next node.

Step 2: Summarize with AI

Add an OpenAI node (or the built-in AI Agent node if you prefer a more conversational setup):

• Model: gpt-4o-mini
• Operation: Message a Model
• Messages → Prompt: use an expression to inject email content:

Summarize the following email in 2-3 sentences. Focus on what action, if any, is required.

Subject: {{ $json.Subject }}
From: {{ $json.From }}
Body: {{ $json.text ?? $json.snippet }}

The node outputs a message.content field containing the AI-generated summary.

Step 3: Send to Telegram

Add a Telegram node:

• Operation: Send Text Message
• Chat ID: your chat or group ID (the number you retrieved from getUpdates).
• Text: compose the message using expressions:

📧 *{{ $('INBOX').item.json.Subject }}*
👤 From: {{ $('INBOX').item.json.From }}
{{ $json.output[0].content[0].text }}

Once all three nodes are connected, click the Publish button (top right corner of the canvas) to activate the workflow. Until published, the workflow won't trigger on incoming emails — it only runs manually during testing.

Export & Import

n8n lets you export any workflow as a JSON file and import it into another instance. This is handy for sharing workflows with teammates, backing them up, or moving them between environments.

To export your workflow:

1. Open the workflow on the canvas.
2. Click the ⋯ (three dots) menu in the top right corner.
3. Select Export — this downloads a .json file to your machine.

To import a workflow:

1. In n8n, click Workflows in the left sidebar.
2. Click the ⋯ menu (top right) and select Import from file, then pick your .json file.
3. Once imported, open the workflow and reconnect any credentials — the imported file won't carry your personal API keys or tokens.

Note: Credentials are never included in exports for security reasons. After importing, open each node and select the appropriate credential from the dropdown.

Conclusion

n8n is a practical, self-hostable automation platform that sits comfortably between no-code simplicity and full-code flexibility. In this article you went from zero to a working workflow that reads your Gmail, summarizes emails with an AI model, and posts the digest to Telegram — all running locally in Docker with your credentials never leaving your machine.

The same pattern — trigger, fetch, transform, act — scales to far more complex workflows: processing invoices, syncing CRMs, alerting on monitoring thresholds, or orchestrating multi-step AI pipelines. Once you understand the node model and expression syntax, the surface area of what you can automate expands rapidly.

Key takeaways:

• n8n runs anywhere Docker runs; a single command is enough to get started.
• Credentials are stored once and reused across nodes — OAuth for Gmail, a bot token for Telegram.
• The expression syntax {{ $json.field }} is how you pass data between nodes; master it and you control the whole pipeline.
• AI nodes (OpenAI, Anthropic, etc.) are first-class citizens — summarization, classification, and generation fit naturally into any workflow.