borisngaleu8 min read
API IntegrationGmail APIOAuth

How the Gmail API Works (And How to Get It to Send Emails for You)

Hey there, fellow dev! Let me break down how we use the Gmail API to send emails on your behalf — and yes, it all starts with good old-fashioned user consent. I remember the first time I had to figure this out, I spent like two hours just staring at Google's documentation wondering why it felt like I needed a law degree to send a simple email. So let me save you that pain.

Does Gmail Have an API to Send Emails?

Short answer: yes! And honestly, it's one of the better-designed APIs I've worked with once you get past the initial setup headache.

Google's Gmail API is a full REST API that lets you send, read, search, and manage emails programmatically. Forget wrestling with raw SMTP — you know, that old-school protocol where you're basically knocking on a mail server's door and hoping it answers nicely. The Gmail API is cleaner, more secure, and way more predictable. No more "why is my email landing in spam?" mysteries caused by misconfigured SMTP settings. The API handles all of that under the hood because the email is literally coming from Gmail itself. That's the big win here.

If you've ever used a third-party app that says "sign in with Google and we'll send emails on your behalf," you've already been on the receiving end of the Gmail API. Now you get to be the one building that experience. Pretty cool, right?

The Lowdown on Gmail API and Consent

1. All with Google Cloud Project

First things first — before you write a single line of code, you need to set up a Google Cloud Project. I know, I know. Nobody wakes up excited about cloud consoles. But this part is actually pretty straightforward once you've done it once.

Here's what you do:

  1. Head over to console.cloud.google.com and create a new project — name it after whatever app you're building, keeps things sane.

  2. Navigate to APIs & Services → Library, search for Gmail API, and hit Enable.

  3. Go to OAuth consent screen and fill in your app name, the scopes you need, and your test users.

  4. Under Credentials, create an OAuth 2.0 Client ID — choose "Web Application" if you're building a web app.

  5. Download the credentials.json file it gives you and keep it somewhere safe.

⚠️ Do not commit that credentials file to GitHub. I'm saying this because I've seen it happen. Don't be that person.

For the scope, if you only need to send emails, use:

Don't go grabbing gmail.modify or the full gmail scope unless you actually need it. Users see these scopes on the consent screen, and the more you ask for, the more suspicious it looks. Keep it minimal. It's just good practice and it respects the user.

2. Get User Consent (The OAuth Way)

Okay, this is the part that confused me the most when I was starting out. OAuth 2.0 sounds intimidating but once you understand what it's actually doing, it clicks.

Here's the flow step by step:

  1. Your app redirects the user to a Google authorization URL built with your client ID, requested scopes, and a redirect URI pointing back to your app.

  2. Google shows the user a consent screen — "This app wants to send email on your behalf." The user clicks Allow.

  3. Google redirects back to your app with a short-lived authorization code in the URL.

  4. Your backend exchanges that code for two things:

    • An access token — what you use to make API calls (expires in ~1 hour)

    • A refresh token — lives much longer, lets you silently get new access tokens without asking the user again

  5. Store the refresh token securely — encrypted in a database, in environment variables, whatever your setup is. Just not in plain text in your code.

One thing I learned the hard way: handle the case where a user revokes access from their Google account. When that happens, your refresh token becomes invalid and your next API call will throw an error. Catch it gracefully and prompt the user to reconnect. I had a user complain their emails suddenly stopped sending — yep, they had revoked access without knowing it broke my app.

3. Send Emails with a Simple API Call

Alright, OAuth is done, tokens are stored — now let's actually send something. This is where it gets satisfying.

The Gmail API expects your email in RFC 2822 format — the standard that's been around since the 80s. Here's what it looks like:

To: recipient@example.com
Subject: Hello from the Gmail API!
Content-Type: text/html; charset=UTF-8

<h1>Hey there!</h1><p>This was sent via the Gmail API.</p>

To send it, you:

  1. Build that string with your headers and body.

  2. Base64url-encode it — that's base64 but with + replaced by -, / replaced by _, and no = padding at the end.

  3. POST it to https://gmail.googleapis.com/gmail/v1/users/me/messages/send with your access token in the Authorization header.

In Node.js with the official googleapis package, it looks like this:

const rawEmail = [
  `To: recipient@example.com`,
  `Subject: Hello!`,
  `Content-Type: text/html; charset=UTF-8`,
  ``,
  `<h1>It works!</h1>`,
].join('\n');

const encoded = Buffer.from(rawEmail)
  .toString('base64')
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
  .replace(/=+$/, '');

await gmail.users.messages.send({
  userId: 'me',
  requestBody: { raw: encoded },
});

When that works for the first time and you see the email land in the inbox — it's genuinely one of those small developer victories that feels disproportionately satisfying. I may have done a little fist pump. No shame.

4. Refresh Tokens: The Part Everyone Forgets

I'm going to say this loudly because most tutorials gloss over it: your access token expires after one hour.

Here's how to handle it properly:

  • If you're using the Google client libraries, they handle refresh almost automatically as long as you set the credentials with the refresh token attached.

  • If you're making raw HTTP requests, you need to:

    1. Detect a 401 Unauthorized response.

    2. Hit Google's token endpoint to exchange your refresh token for a fresh access token.

    3. Retry the original request.

I had a production app once where I didn't implement refresh properly. Everything worked great in testing because I was always refreshing the page. Then real users came in, stayed logged in for more than an hour, and emails just silently stopped sending. No errors shown to the user, just... nothing. That was a fun debug session. Don't skip the refresh logic.

5. We Keep It Secure and Transparent

This might sound obvious but it's worth saying out loud. Here's the checklist I follow:

  • ✅ Tell users exactly what your app does with their Gmail access — don't bury it in a privacy policy nobody reads. Put it right on your onboarding screen.

  • ✅ Use the most restrictive scope that gets the job done. If you only need to send, don't request read access too.

  • ✅ Handle revoked access gracefully — detect the error, show a friendly message, let the user reconnect.

  • ✅ Never store tokens in plain text — encrypt them, use environment variables, treat them like passwords.

  • ✅ Let users know they can revoke anytime at myaccount.google.com/permissions.

It's all about trust. A solid consent process means fewer headaches and a lot more happy users — and inboxes that won't hate you.

What Can You Actually Build with This?

Once you've got the Gmail API wired up, the possibilities open up a lot. I've personally used it to build:

  • Automated follow-up email sequences for a side project

  • A tool that syncs sent emails into a CRM automatically

  • A script that forwards specific emails to Slack based on subject line keywords

Beyond that, people use it for:

  • Inbox zero automation tools

  • Email analytics dashboards that parse your own inbox data

  • Customer support tools that reply to emails from within a custom interface

  • Notification systems and transactional email flows

Basically — if it involves Gmail, the API can touch it.

A Real Talk on Limits

Before you go all in, know the daily sending limits:

Account type Daily sending limit Regular Gmail 500 emails/day Google Workspace 2,000 emails/day Max message size 36 MB

If you're building something that needs to blast tens of thousands of emails, the Gmail API alone isn't your answer — you'd want to pair it with something like SendGrid or Amazon SES for the heavy lifting.

For most indie projects, internal tools, or anything where you're sending on behalf of individual users, those limits are more than enough. Just keep an eye on your quota usage in the Google Cloud Console so you don't hit a wall at the worst possible moment.

That's It!

The Gmail API basically lets your app do the emailing dance — provided you take care of the credentials, the OAuth flow, the token refresh, and the consent transparency. It's secure, it's robust, and once you've got it set up once, it's actually pretty elegant to work with.

Yeah, the setup feels like a lot of steps the first time. But do it once, document it for yourself, and the second time around it takes maybe 20 minutes. Worth it.

Happy coding! imastories :)