Skip to main content

Why RustMailer Integrated the Gmail API

Background​

Based on feedback from several enterprise and developer users, large-scale use of Gmail accounts through IMAP has proven difficult in practice.

To connect via IMAP, Gmail requires apps to request the IMAP scope (https://mail.google.com/), which is considered a highly sensitive scope by Google. Gaining approval for this scope through Google’s OAuth verification process is often time-consuming and restrictive, especially for commercial or production environments.

In contrast, Google encourages developers to use more granular, limited scopes, such as those provided by the Gmail REST API. This makes it much easier to pass verification while maintaining a secure and transparent permission model.

As a result, integrating the Gmail API became the only practical way for RustMailer to support Gmail in large-scale, production-grade environments.

Why Gmail API Integration Matters​

  1. Easier OAuth Verification Gmail API scopes are narrower and easier to get approved by Google, avoiding IMAP scope restrictions.

  2. Improved User Experience RustMailer now provides a unified mail interface for both IMAP and Gmail API users. From the application’s point of view, everything works the same — you just choose your account type when creating it.

  3. Label Model Compatibility Gmail’s “label” system differs significantly from IMAP’s “folder” model. IMAP can only approximate this behavior through complex mappings, but the Gmail API exposes labels natively — making synchronization and filtering much more accurate and intuitive.

Design Overview​

The Gmail API integration in RustMailer is built to mirror the IMAP behavior where it makes sense, while taking advantage of Gmail’s unique features.

Local Caching Strategy​

  • RustMailer locally caches message metadata (subject, sender, flags, labels, etc.) for fast listing and search.
  • Message bodies and attachments are not pre-downloaded during sync. They are fetched on demand when the user opens a message.
  • Once downloaded, bodies and attachments are cached locally to reduce quota usage and network overhead.

Synchronization Mechanism​

  • RustMailer uses the Gmail History API to poll for changes.
  • It does not use the Pub/Sub push model; instead, it performs a lightweight polling cycle every few dozen seconds. This design achieves good near-real-time sync without over-complicating infrastructure.
  • Message changes (flags, labels, etc.) are handled by directly calling Gmail’s API endpoints — RustMailer does not modify the local cache directly.
  • RustMailer manages History IDs internally and will automatically resynchronize if it detects any gaps or inconsistencies.

This design lets applications:

  • List and search messages instantly without managing Gmail concurrency or incremental metadata fetching themselves.
  • Avoid repeated API calls and excessive quota consumption.
  • Rely on RustMailer for safe, consistent synchronization.

Developer Experience​

From a developer’s perspective, nothing major changes:

  • Authentication flow remains identical to IMAP OAuth2 — same redirect URI and OAuth token exchange process.
  • All other RustMailer APIs remain fully compatible.

When creating a new account, simply choose the account type:

  • IMAP/SMTP
  • Gmail API

Everything else — synchronization, message listing, and search — works transparently.

Pagination Model Update​

Both IMAP and Gmail API now share a cursor-based pagination model for listing and searching messages. This approach replaces the old page / page_size pattern, which was hard to unify because:

  • IMAP search results cannot easily be paged by fixed index.
  • Cursor-based pagination avoids deep pagination performance issues and aligns with Gmail’s own API behavior.

Summary​

By integrating the Gmail API, RustMailer:

  • Removes Google IMAP scope limitations for commercial use
  • Provides native Gmail label support
  • Unifies the developer and user experience between IMAP and Gmail
  • Reduces complexity, quota usage, and synchronization errors
  • Keeps authentication and API structure consistent for minimal integration effort

In short, Gmail API support makes RustMailer more compliant, scalable, and user-friendly — all while maintaining the same simple developer interface.