2025 Growth Unified Hits Major Growth Milestones with 6.5x usage & 4.5x revenue growth
Unified.to
All articles

How to Integrate with Gmail API: A Step-by-Step Guide for Developers

February 26, 2026

A Gmail API integration lets your SaaS read messages, send mail, manage labels, and stay in sync with users' inbox activity. But building a production-grade integration requires more than sending a few REST requests. You must implement OAuth correctly, choose scopes carefully, handle token rotation, design for quota limits, and build reliable change detection.

This guide covers:

  1. How to integrate directly with the Gmail API
  2. The operational complexity you'll own in production
  3. How to integrate Gmail using Unified's Messaging API
  4. When to build direct vs use an integration layer

Direct Gmail API Integration

Step 1: Create a Google Cloud Project and Enable Gmail API

Start in the Google Cloud Console.

  1. Create or select a project.
  2. Navigate to APIs & Services → Library.
  3. Search for Gmail API.
  4. Click Enable.

Google's official Gmail API documentation is available in the Gmail API overview.

In APIs & Services → OAuth consent screen:

  1. Choose Internal (Workspace-only) or External (public SaaS).
  2. Provide:
    • App name
    • Support email
    • Developer contact email
  3. Add authorized domains.
  4. Add links to your privacy policy and terms.

Google documents OAuth for web server applications in the OAuth 2.0 Web Server Applications guide.

If your app requests sensitive or restricted scopes, Google requires additional verification.

Step 3: Choose the Correct Gmail Scopes

Scopes determine what your application can do.

Common Gmail scopes include:

  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.send
  • https://mail.google.com/

Google categorizes Gmail scopes as non-sensitive, sensitive, or restricted. You can review scope classifications in the Gmail API scope reference.

Key considerations:

  • gmail.send is typically categorized as Sensitive.
  • gmail.readonly and gmail.modify are Restricted scopes.
  • Restricted scopes require passing Google's restricted scope verification process, including a third-party security assessment as documented in the Restricted Scope Verification guide.

If your SaaS only needs to send email, prefer gmail.send. Reading inbox content triggers stricter compliance requirements.

Step 4: Create OAuth Credentials

In APIs & Services → Credentials:

  1. Click Create Credentials → OAuth client ID.
  2. Select Web application.
  3. Provide an authorized redirect URI, for example:
https://app.your-saas.com/oauth/google/callback

After creation, Google provides:

  • Client ID
  • Client Secret

These credentials are required to implement the OAuth authorization code flow.

Step 5: Implement the OAuth 2.0 Authorization Code Flow

Typical SaaS flow:

  1. Redirect user to Google's authorization endpoint.
  2. User consents to requested scopes.
  3. Google redirects back with an authorization code.
  4. Backend exchanges the code for:
    • Access token
    • Refresh token

Google documents the complete process in the OAuth Web Server Flow documentation.

Access tokens are short-lived. Your backend must securely store refresh tokens and automatically rotate access tokens when expired.

Core Gmail API Endpoints

All requests require:

Authorization: Bearer {access_token}

List Labels

GET https://gmail.googleapis.com/gmail/v1/users/me/labels

List Messages

GET https://gmail.googleapis.com/gmail/v1/users/me/messages

Common parameters:

  • q (search query)
  • maxResults
  • pageToken

Reference: users.messages.list documentation

Get Message

GET https://gmail.googleapis.com/gmail/v1/users/me/messages/{messageId}

You can request different formats:

  • metadata
  • full
  • raw

Reference: users.messages.get documentation

Send Email

POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send

Sending mail requires constructing a properly encoded MIME message and base64url encoding it before submission.

Reference: users.messages.send documentation

Real-Time Sync: Stop Polling

Polling Gmail every 30 seconds will exhaust quota.

Google provides push-based notifications via Pub/Sub.

Step 1: Configure Pub/Sub Topic

Create a Google Cloud Pub/Sub topic.

Step 2: Call watch()

When a user connects, call:

POST https://gmail.googleapis.com/gmail/v1/users/me/watch

You must supply your Pub/Sub topic name.

Reference: Gmail Push Notifications guide

Important:

  • You must renew watch() at least every 7 days.
  • Notifications only contain history IDs, not full message content.

Delta Sync with the History API

For reliable incremental sync:

  1. Perform initial full sync.
  2. Store the returned historyId.
  3. On notification, call:
GET https://gmail.googleapis.com/gmail/v1/users/me/history?startHistoryId={id}

Reference: users.history.list documentation

The History API returns only deltas:

  • messagesAdded
  • messagesDeleted
  • labelsAdded
  • labelsRemoved

This is essential for high-scale SaaS integrations.

Quotas and Rate Limits

Gmail API uses quota units per method.

For example:

  • Reading a message consumes quota units.
  • Sending mail consumes more quota units.

Quota reference: Gmail API Usage Limits

Best practices:

  • Implement exponential backoff.
  • Use batch requests for large imports.
  • Avoid tight polling loops.

Batch request documentation: Gmail API batching guide

Operational Complexity of Direct Gmail Integration

A production-ready Gmail integration requires:

  • OAuth lifecycle management
  • Secure token encryption at rest
  • Refresh token rotation logic
  • Handling revoked credentials
  • Scope compliance and verification
  • Pub/Sub infrastructure
  • Delta sync via History API
  • MIME parsing and message threading logic
  • Rate limit backoff
  • Multi-tenant token storage

If you request Restricted scopes, you must complete Google's security assessment process as outlined in the Restricted Scope Verification documentation.

For internal tools, this may be manageable.

For a multi-tenant SaaS serving thousands of Gmail users, this becomes infrastructure and compliance engineering.

Integrating Gmail via Unified's Messaging API

If your product supports Gmail alongside other messaging platforms, maintaining separate OAuth, Pub/Sub, and delta sync logic increases long-term complexity.

Unified provides a Messaging category integration that standardizes email access.

Step 1: Register OAuth for Unified

When integrating Gmail through Unified, configure your redirect URI as:

https://api.unified.to/oauth/code

Unified's Gmail OAuth guide is available in the Gmail OAuth credentials guide.

Unified scope mapping includes:

  • messaging_message_read → gmail.readonly
  • messaging_message_write → gmail.compose, gmail.modify
  • Identity scopes: openid, profile, email

Step 2: Activate Gmail in Unified

In your Unified workspace:

  1. Activate Gmail.
  2. Enter Client ID and Client Secret.
  3. Authorize a user.
  4. Receive a connection_id.

Step 3: Call Unified's Messaging API

Example:

GET https://api.unified.to/messaging/message/{connection_id}?limit=50
Authorization: Bearer YOUR_API_KEY

Supported methods:

  • list
  • get
  • create
  • update
  • remove

Readable fields include:

  • id
  • subject
  • message
  • message_html
  • attachments
  • created_at
  • channel_id
  • parent_id
  • root_message_id

Writable fields include:

  • subject
  • message
  • message_html
  • attachments
  • destination_members

Unified delivers change events using virtual webhooks:

  • created
  • updated
  • deleted

This allows webhook-style behavior without requiring you to build Pub/Sub consumers directly.

Direct vs Unified — When to Choose Each

Build Directly If

  • Gmail is your only messaging integration
  • You need deep Gmail-specific functionality
  • You want full control over OAuth and Pub/Sub infrastructure

Use Unified If

  • You support multiple messaging platforms
  • You want standardized message models
  • You prefer not to maintain OAuth lifecycle logic
  • You want webhook-style delivery without managing Pub/Sub
  • You want usage-based pricing instead of per-connection fees

Final Thoughts

A Gmail API integration can add enormous value to a B2B SaaS product.

The complexity lies not in listing messages, but in managing authentication, compliance, delta sync, real-time change detection, and multi-tenant reliability.

Choosing the right architecture early determines how quickly you ship — and how much infrastructure you own over time.

→ Start your 30-day free trial

→ Book a demo

All articles