DEV Community: Pratik Kumar Ghosh

How I Set Up Nodemailer with Gmail OAuth2 in My Node.js Project

Pratik Kumar Ghosh — Sun, 12 Apr 2026 07:31:13 +0000

For a long time, I thought sending emails from a Node.js project would be simple.
Install Nodemailer, write a few lines, done.

Not really.

While adding email sending functionality to my project, I ran into configuration issues, especially with dotenv, Gmail authentication, and OAuth2. After some debugging, I finally got it working.

So in this post, I want to explain how to set up Nodemailer with Gmail OAuth2 in a simple way, and also share the exact problems I faced and how I fixed them.

Why I used OAuth2 instead of password login

Earlier, many people used Gmail with just email and password. But that is not the recommended way now.

A better setup is:

Gmail API enabled
OAuth2 credentials from Google Cloud
Refresh token from OAuth Playground
Nodemailer configured with those values

That is also the method used in the guide I followed.

Step 1: Install packages

npm install nodemailer dotenv

Step 2: Create OAuth2 credentials

Go to Google Cloud Console and do these things:

Create a project
Enable Gmail API
Create OAuth 2.0 Client ID
Choose Web Application
Add redirect URI:
- http://localhost
- https://developers.google.com/oauthplayground

After that, you will get:

CLIENT_ID
CLIENT_SECRET

Step 3: Generate refresh token

Open OAuth 2.0 Playground and:

Click the settings icon
Enable Use your own OAuth credentials
Paste your CLIENT_ID and CLIENT_SECRET
Set access type to Offline
Select the Gmail scope:

https://mail.google.com/

Authorize APIs
Exchange authorization code for tokens

Now copy the refresh token.

Step 4: Create your `.env` file

GOOGLE_USER=yourgmail@gmail.com
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_token

Make sure the variable names match exactly with your code.

Step 5: Configure Nodemailer

Here is a clean setup:

import dotenv from "dotenv";
import nodemailer from "nodemailer";

dotenv.config();

const transporter = nodemailer.createTransport({
  service: "gmail",
  auth: {
    type: "OAuth2",
    user: process.env.GOOGLE_USER,
    clientId: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    refreshToken: process.env.GOOGLE_REFRESH_TOKEN,
  },
});

// Verify the connection configuration
transporter.verify((error, success) => {
  if (error) {
    throw new Error(`Error connecting to email server: ${error.message}`);
  } else {
    console.log("Email server is ready to send messages");
  }
});

// Function to send email
export const sendEmail = async ({ to, subject, text, html }) => {
  try {
    const info = await transporter.sendMail({
      from: `"Your Name" <${process.env.Gmail_User}>`, // sender address
      to, // list of receivers
      subject, // Subject line
      text, // plain text body
      html, // html body
    });

    console.log('Message sent: %s', info.messageId);
    console.log('Preview URL: %s', nodemailer.getTestMessageUrl(info));
  } catch (error) {
    throw new Error(`Error sending email: ${error.message}`);
  }
};

Step 6: Use it in your project

await sendEmail({
  to: "recipient@example.com",
  subject: "Test Mail",
  text: "This is a test email",
  html: "<p>This is a test email</p>",
});

If everything is correct, your mail should be sent successfully.

What I learned

Setting up Nodemailer is not just about writing sendMail().

You also need to understand:

how Gmail authentication works
why OAuth2 is needed
why environment variables must load properly
why even small config mistakes can break everything

This was one of those features that looked small from outside, but taught me a lot while implementing it.

Problems I faced and how I solved them

1. My `dotenv` configuration was done afterwards

This was my main mistake.

I had set up the email functionality, but the environment variables were not being loaded properly at the right time. Because of that, values like client ID, client secret, refresh token, or email user were not available when Nodemailer needed them.

Fix

I made sure to call:

dotenv.config();

at the top, before using process.env values.

That small order issue was enough to break the whole setup.

2. Gmail authentication error

I got an error like:

530-5.7.0 Authentication Required

This happened because Gmail was not accepting the request as properly authenticated.

Fix

I stopped treating it like a simple email-password login and used the correct OAuth2 setup:

Gmail API enabled
correct client ID
correct client secret
correct refresh token
correct Gmail account in GOOGLE_USER
add same Gmail account as a test user in Google Cloud Console

3. Following the guide was not enough without matching my own project structure

The guide I followed was helpful, but I still had to adjust it to my own project setup.

For example:

I was using my own environment variable names
my project used import syntax
my file structure was different from the guide

Fix

I kept the logic the same, but adapted the code to my own project.

That made me realize an important thing:

Tutorials and README files give the path, but you still need to fit that path into your own project properly.

4. Small config mistakes can waste a lot of time

Even when the code looks correct, things can still fail because of:

wrong variable names
wrong refresh token
wrong Google account
missing .env
dotenv loading too late

Fix

I checked everything one by one instead of changing random things.

That made debugging much easier.

Final thoughts

This feature looked small, but it taught me a very useful lesson:

Backend development is not only about writing logic. A lot of real work is in configuration, authentication, environment setup, and debugging.

Getting Nodemailer working with Gmail OAuth2 was frustrating at first, but once it worked, I understood the setup much better.

And honestly, that is the good part of building projects:
you do not just learn the feature, you learn the mistakes around the feature too.

Why Hashing Refresh Tokens Broke My Auth Flow — and How I Fixed It

Pratik Kumar Ghosh — Tue, 31 Mar 2026 20:15:27 +0000

When I first decided to hash refresh tokens before storing them in the database, it felt like a straightforward security improvement.

But the moment I did that, my refresh-token flow broke.

Not because hashing itself was wrong. The real issue was that hashing changed how I had to design the lookup and verification flow.

This post is about that problem, the first working fix I used, and the more optimal version I reached after understanding the flow properly.

What I was trying to do

My auth setup was simple in principle:

access tokens for short-lived authentication
refresh tokens for issuing new access tokens
sessions stored in the database
refresh token rotation for better security

The part I wanted to improve was storage.

Instead of saving the refresh token directly in the session collection, I wanted to hash it with Argon2 before saving it, just like we hash passwords.

That part was easy enough.

A simplified schema method looked like this:

sessionSchema.methods.verifyRefreshToken = async function (token) {
  if (!this.refreshToken) return false;
  return argon2.verify(this.refreshToken, token);
};

And the pre-save hashing idea was also straightforward:

sessionSchema.pre("save", async function () {
  if (!this.isModified("refreshToken")) return;
  if (!this.refreshToken) return;

  this.refreshToken = await argon2.hash(this.refreshToken);
});

So far, so good.

Then the refresh flow broke.

Why hashing refresh tokens broke the flow

Before hashing, finding the correct session was easy.

I could do something like this:

const existingSession = await session.findOne({
  refreshToken,
  valid: true,
});

That works only when the database stores the raw refresh token.

Once I started hashing the refresh token before saving it, this approach stopped working.

Why?

Because a hashed value is not something I can directly query with the raw token anymore.

The important lesson here is this:

hash verification and database lookup are two different problems.

Hashing solved storage security, but it removed my ability to locate the session by the raw token itself.

Why verification alone was not enough

At first, this felt confusing because argon2.verify() still exists.

So I thought:

No problem. I will just verify the token against the hash.

But that was only half the story.

argon2.verify() needs two things:

the raw token coming from the cookie
the stored hash from the correct session document

And that second part is where the real design issue appeared.

I could verify the hash only after I had already found the right session document.

But if I could no longer find the session by refresh token, then what exactly was I verifying against?

That was the missing piece.

My first working fix

My first working solution was simple:

Create the session first, then generate the refresh token

The flow looked like this:

Create a session document first
Let MongoDB generate the session _id
Use userId and sessionId inside the refresh token payload
Save the real refresh token back into that session
Later, during refresh, verify the JWT, extract sessionId, find the session by that id, and only then verify the hashed token

Login flow

This was the idea in simplified form:

const sessionDoc = await session.create({
  userId: user._id,
  refreshToken: "demo",
  valid: true,
  ip: req.ip,
  userAgent: req.get("User-Agent"),
});

const refreshToken = jwt.sign(
  {
    userId: user._id,
    sessionId: sessionDoc._id.toString(),
  },
  process.env.JWT_REFRESH_SECRET,
  { expiresIn: "15d" }
);

sessionDoc.refreshToken = refreshToken;
await sessionDoc.save();

The reason this worked was simple:

I stopped trying to locate the session by raw refresh token.

Instead, I used a stable identifier: sessionId.

Later, in the refresh flow, I could do this:

const decoded = jwt.verify(refreshTokenCookie, process.env.JWT_REFRESH_SECRET);

const existingSession = await session
  .findOne({
    _id: decoded.sessionId,
    userId: decoded.userId,
    valid: true,
  })
  .select("+refreshToken");

const isValid = await existingSession.verifyRefreshToken(refreshTokenCookie);

if (!isValid) {
  return res.status(401).json({ error: "Invalid refresh token" });
}

This was the moment the whole design started making sense.

Why that first fix was not optimal

It worked, but it had two problems.

1. It needed two database writes

First I created the session. Then I updated it with the real refresh token.

That is acceptable, but not ideal.

2. I used a placeholder value first

Because refreshToken was required in the model, I temporarily stored an Empty String "" and then replaced it with the real token.

That was not elegant.

It worked as a practical fix, but it clearly felt like an implementation workaround rather than a clean design.

The better fix

After that, I moved to a cleaner approach.

Generate the Mongo ObjectId first, then create everything in one go

Instead of letting Mongo create the session id during insert, I generated the ObjectId beforehand.

That allowed me to:

generate the session id first
sign the refresh token using userId and sessionId
create the session once with the real refresh token
let the schema middleware hash it before saving

Here is the cleaner version:

const sessionId = new mongoose.Types.ObjectId();

const refreshToken = jwt.sign(
  {
    userId: user._id,
    sessionId: sessionId.toString(),
  },
  process.env.JWT_REFRESH_SECRET,
  { expiresIn: "15d" }
);

await session.create({
  _id: sessionId,
  userId: user._id,
  refreshToken,
  valid: true,
  ip: req.ip,
  userAgent: req.get("User-Agent"),
});

This solved both earlier drawbacks:

no placeholder token
only one database write

It also kept the refresh flow clean, because the token still carried the sessionId.

Comparing both approaches

Approach 1: create session first, then update

Pros

easy to understand
easy to implement
works reliably

Cons

needs two DB operations
temporary placeholder value feels awkward

Approach 2: generate ObjectId first, then create once

Pros

cleaner design
one DB write
no placeholder token
easier to reason about long-term

Cons

slightly more thought required upfront

For me, the second version was the better engineering decision.

The final refresh flow

Once I moved to the sessionId-based design, the full flow became much clearer.

During login

create an access token
generate a session id
create a refresh token containing userId and sessionId
save the session with the refresh token
let Mongoose hash the token before saving
send both tokens in cookies

A simplified login controller looked like this:

export const login = async (req, res) => {
  try {
    const { identifier, password } = req.body || {};

    if (!identifier || !password) {
      return res.status(400).json({ error: "All fields are required" });
    }

    const existingUser = await user.findOne({
      $or: [{ email: identifier }, { userName: identifier }],
    }).select("+password");

    if (!existingUser) {
      return res.status(401).json({ error: "Invalid credentials" });
    }

    const isPasswordValid = await existingUser.verifyPassword(password);

    if (!isPasswordValid) {
      return res.status(401).json({ error: "Invalid credentials" });
    }

    const accessToken = jwt.sign(
      { userId: existingUser._id },
      process.env.JWT_ACCESS_SECRET,
      { expiresIn: "15m" }
    );

    const sessionId = new mongoose.Types.ObjectId();

    const refreshToken = jwt.sign(
      {
        userId: existingUser._id,
        sessionId: sessionId.toString(),
      },
      process.env.JWT_REFRESH_SECRET,
      { expiresIn: "15d" }
    );

    await session.create({
      _id: sessionId,
      userId: existingUser._id,
      refreshToken,
      valid: true,
      ip: req.ip,
      userAgent: req.get("User-Agent"),
    });

    res.cookie("accessToken", accessToken, {
      httpOnly: true,
      secure: process.env.NODE_ENV === "production",
      sameSite: "strict",
      maxAge: 15 * 60 * 1000,
    });

    res.cookie("refreshToken", refreshToken, {
      httpOnly: true,
      secure: process.env.NODE_ENV === "production",
      sameSite: "strict",
      maxAge: 15 * 24 * 60 * 60 * 1000,
    });

    return res.status(200).json({
      message: "Login successful",
      user: existingUser,
    });
  } catch (error) {
    return res.status(500).json({ error: "Internal server error" });
  }
};

During refresh

read refresh token from cookie
verify JWT
extract sessionId
find the session by _id
verify raw token against stored hash
rotate tokens if valid

A simplified refresh flow looked like this:

export const refreshToken = async (req, res) => {
  try {
    const refreshTokenCookie = req.cookies?.refreshToken;

    if (!refreshTokenCookie) {
      return res.status(401).json({ error: "Missing refresh token" });
    }

    const decoded = jwt.verify(
      refreshTokenCookie,
      process.env.JWT_REFRESH_SECRET
    );

    const existingSession = await session
      .findOne({
        _id: decoded.sessionId,
        userId: decoded.userId,
        valid: true,
      })
      .select("+refreshToken");

    if (!existingSession) {
      return res.status(401).json({ error: "Invalid refresh token" });
    }

    const isValid = await existingSession.verifyRefreshToken(
      refreshTokenCookie
    );

    if (!isValid) {
      return res.status(401).json({ error: "Invalid refresh token" });
    }

    return res.status(200).json({ message: "Token verified successfully" });
  } catch (error) {
    return res.status(500).json({ error: "Internal server error" });
  }
};

What this taught me

This problem taught me something important:

security improvements often change architecture, not just storage.

At first, I treated hashed refresh token storage as a simple replacement:

store token
hash token
done

But hashing a refresh token changes the lookup strategy completely.

Once the token is hashed, it should no longer be treated as the thing used to find the session document.

Instead:

use a stable identifier like sessionId to find the session
use hash verification only to validate the token

That separation made the whole flow much cleaner.

Key takeaways

Hashing refresh tokens is safer than storing them in plain text
But once you hash them, direct database lookup by raw token no longer works
argon2.verify() helps with validation, not identification
You still need a stable way to find the correct session first
Including sessionId inside the refresh token is a clean solution
Generating the Mongo ObjectId beforehand is a better version because it removes the extra DB update

Closing thought

This was a small bug, but it changed the way I think about authentication design.

I started with a storage problem and ended up learning a flow-design problem.

And that was the real lesson.

Sometimes the hard part in auth is not generating or verifying the token itself.

It is designing the path that lets you verify the right thing, in the right place, for the right reason.

I Thought I Knew What an API Was. I Was Wrong.

Pratik Kumar Ghosh — Thu, 26 Mar 2026 17:08:13 +0000

For a long time, I had this feeling that I basically knew what an API was.

I mean, I’ve used APIs before.

In frontend projects, I used things like a weather API and got JSON data.
In backend, I created routes and heard people call them REST APIs.
Sometimes an API looked like a URL.
Sometimes it looked like a function.
Sometimes it looked like just a JSON response.

So I was honestly confused:

What is an API actually?
Is the weather JSON file the API?
Is an Express route the API?
Is an API just a way to fetch data?

Today I properly studied it, and finally the confusion became much smaller.

So this post is basically me sharing what I understood in simple words.

what is an API, really?

API stands for Application Programming Interface.

That sounds fancy, but the simple meaning is:

An API is a way for one software to talk to another software using defined rules.
That’s it.

Think of it like this:

your frontend wants data
your backend has that data
the API is the way they communicate

Or:

your app wants weather data
some weather service has that data
the API is the bridge between them

Real-life analogy

Imagine you are in a restaurant:

You = client
Kitchen = server
Waiter = API

You don’t go inside the kitchen and cook by yourself.
You tell the waiter what you want.
The waiter takes the request to the kitchen.
Then the waiter brings the response back.

That waiter-like role is what an API does.

Then what was I misunderstanding in the weather app?

This was one of my biggest confusions.

When I make a weather app, I often do something like this:

fetch("https://api.example.com/weather?city=Kolkata")
  .then(res => res.json())
  .then(data => console.log(data));

And then I get something like:

{
  "city": "Kolkata",
  "temperature": 31,
  "condition": "Cloudy"
}

Earlier, I used to think:

“This JSON is the API.”

But that is not exactly correct.

What is actually happening?

The API is the system/interface/endpoints/rules that let my app request data
The JSON is the response format returned by the API

So the JSON is not the API itself.
It is the data sent back by the API.

That cleared up a lot for me.

Easy way to remember it

API = the communication system
JSON = one common format of the response data

So in a weather app, the API is not “a JSON file.”
The JSON is just the reply you get after using the API.

A backend route also feels like an API. Why?

Because it usually is.

For example:

app.get("/users", (req, res) => {
  res.json([
    { id: 1, name: "Pratik" },
    { id: 2, name: "Aman" }
  ]);
});

This route allows a client to request user data.

If a frontend sends a request to /users, the backend sends a response.

That route becomes part of your API.

So yes, when I build backend routes, I am often building an API.

So what is the simplest definition I should remember?

Here’s the definition I’ll remember from now on:

An API is a set of rules and endpoints that allows one software system to communicate with another.

And in web development:

An API usually lets a client send a request and receive a response.

Types of API

This part also confused me because people say “types of API” in different ways.

Sometimes they mean who can use the API.
Sometimes they mean how the API works.

So I’ll keep both simple.

1) Public API

A public API is available for external developers to use.

Example

A weather service giving data to developers.

Use case

You are building a weather app and want live temperature data.

fetch("https://api.weather-service.com/current?city=Delhi")

You are using someone else’s public API.

2) Private API

A private API is used only inside an organization or company.

Example

An admin dashboard talking to the company’s internal backend.

Use case

A company has internal employee data, sales data, analytics, etc.
That API is not open for the whole world.

3) Partner API

A partner API is shared only with selected business partners.

Example

A payment company allowing trusted partner apps to connect to its services.

Use case

An e-commerce platform integrating a shipping provider’s partner API.

4) REST API

This is the type I hear the most in backend development.

A REST API is a web API that uses HTTP methods like:

GET
POST
PUT
PATCH
DELETE

Example

app.get("/products", (req, res) => {
  res.json([{ id: 1, name: "Laptop" }]);
});

app.post("/products", (req, res) => {
  res.status(201).json({ message: "Product created" });
});

Use case

Most CRUD apps:

users
posts
products
comments
tasks

REST is common because it is simple and structured.

5) SOAP API

SOAP is older and more strict than REST.

It often uses XML instead of JSON and follows stricter rules.

Example use case

Banking systems, enterprise systems, older business software

SOAP is less beginner-friendly, but it still exists in some places where strict standards matter.

6) GraphQL API

With GraphQL, the client can ask for exactly the data it needs.

Example

Instead of getting a big object, you can request only specific fields.

{
  user(id: 1) {
    name
    email
  }
}

Use case

Apps where over-fetching or under-fetching data is a problem

For example, if you only want name and email, GraphQL helps you avoid receiving unnecessary data.

7) WebSocket API

This is useful when you want real-time, two-way communication.

Example use case

chat apps
live notifications
multiplayer games
stock price updates

Unlike normal request-response flow, WebSockets keep the connection open.

The easiest way I now think about it

If someone asks me about API types, I’ll think like this:

Based on access

Public
Private
Partner

Based on style/communication

REST
SOAP
GraphQL
WebSocket

That makes the topic much less messy in my head.

A little about status codes

When a client sends a request to a server, the server responds with not just data, but also a status code.

That code tells us what happened.

Example:

app.get("/profile", (req, res) => {
  res.status(200).json({ name: "Pratik" });
});

Here, 200 means the request worked successfully.

Status codes are super useful because they quickly tell us whether:

the request succeeded
something was missing
access was denied
the server crashed

Tiny example: request + response + status code together

Here’s a super small Express example:

app.post("/login", (req, res) => {
  const { email, password } = req.body;

  if (!email || !password) {
    return res.status(400).json({ error: "Email and password are required" });
  }

  if (email !== "test@example.com" || password !== "1234") {
    return res.status(401).json({ error: "Invalid credentials" });
  }

  return res.status(200).json({ message: "Login successful" });
});

This one route already shows a lot:

400 if input is missing
401 if credentials are wrong
200 if login works

That made status codes feel much more practical to me.

What I finally understood today

If I explain it to my old confused self, I’d say:

API is not just JSON
API is not just a backend function
API is not just a URL
API is the communication bridge with defined rules

And the JSON in apps like weather apps is usually just the response data returned by the API.

That one difference cleared up a lot of confusion for me.

Final summary

Today I finally stopped treating “API” like a vague buzzword.

What I learned is:

an API lets one software communicate with another
in web development, APIs usually work through request and response
the JSON we get is usually the response, not the API itself
backend routes often become part of our API
APIs can be public, private, partner-based, or different in style like REST, SOAP, GraphQL, and WebSocket
status codes help us quickly understand what happened after a request

This was one of those topics I thought I already understood, but actually needed to sit down and study properly.

And honestly, now it feels way less scary.

DEV Community: Pratik Kumar Ghosh

How I Set Up Nodemailer with Gmail OAuth2 in My Node.js Project

Why I used OAuth2 instead of password login

Step 1: Install packages

Step 2: Create OAuth2 credentials

Step 3: Generate refresh token

Step 4: Create your .env file

Step 5: Configure Nodemailer

Step 6: Use it in your project

What I learned

Problems I faced and how I solved them

1. My dotenv configuration was done afterwards

2. Gmail authentication error

3. Following the guide was not enough without matching my own project structure

4. Small config mistakes can waste a lot of time

Final thoughts

Why Hashing Refresh Tokens Broke My Auth Flow — and How I Fixed It

What I was trying to do

Why hashing refresh tokens broke the flow

Why verification alone was not enough

My first working fix

Create the session first, then generate the refresh token

Login flow

Why that first fix was not optimal

1. It needed two database writes

2. I used a placeholder value first

The better fix

Generate the Mongo ObjectId first, then create everything in one go

Comparing both approaches

Approach 1: create session first, then update

Approach 2: generate ObjectId first, then create once

The final refresh flow

During login

During refresh

What this taught me

Key takeaways

Closing thought

I Thought I Knew What an API Was. I Was Wrong.

what is an API, really?

Then what was I misunderstanding in the weather app?

What is actually happening?

Easy way to remember it

A backend route also feels like an API. Why?

So what is the simplest definition I should remember?

Types of API

1) Public API

Example

Use case

2) Private API

Example

Use case

3) Partner API

Example

Use case

4) REST API

Example

Use case

5) SOAP API

Example use case

6) GraphQL API

Example

Use case

7) WebSocket API

Example use case

The easiest way I now think about it

Based on access

Based on style/communication

A little about status codes

Tiny example: request + response + status code together

What I finally understood today

Final summary

Step 4: Create your `.env` file

1. My `dotenv` configuration was done afterwards