<h2>RustMailer has now released version 1.5.0.</h2>
<h2>Background</h2>
<p>Based on feedback from several enterprise and developer users, large-scale use of <strong>Gmail accounts</strong> through <strong>IMAP</strong> has proven difficult in practice.</p>
<p>To connect via IMAP, Gmail requires apps to request the <strong>IMAP scope</strong> (<code>https://mail.google.com/</code>), which is considered <strong>a highly sensitive scope</strong> by Google. Gaining approval for this scope through Google’s OAuth verification process is often <strong>time-consuming and restrictive</strong>, especially for commercial or production environments.</p>
<p>In contrast, Google encourages developers to use <strong>more granular, limited scopes</strong>, such as those provided by the <strong>Gmail REST API</strong>. This makes it much easier to pass verification while maintaining a secure and transparent permission model.</p>
<p>As a result, <strong>integrating the Gmail API</strong> became the only practical way for RustMailer to support Gmail in large-scale, production-grade environments.</p>
<hr>
<h2>Why Gmail API Integration Matters</h2>
<ol>
<li>
<p><strong>Easier OAuth Verification</strong>
Gmail API scopes are narrower and easier to get approved by Google, avoiding IMAP scope restrictions.</p>
</li>
<li>
<p><strong>Improved User Experience</strong>
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.</p>
</li>
<li>
<p><strong>Label Model Compatibility</strong>
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.</p>
</li>
</ol>
<hr>
<h2>Design Overview</h2>
<p>The Gmail API integration in RustMailer is built to <strong>mirror the IMAP behavior</strong> where it makes sense, while taking advantage of Gmail’s unique features.</p>
<h3>Local Caching Strategy</h3>
<ul>
<li>RustMailer <strong>locally caches message metadata</strong> (subject, sender, flags, labels, etc.) for fast listing and search.</li>
<li><strong>Message bodies and attachments</strong> are <strong>not pre-downloaded</strong> during sync.
They are fetched <strong>on demand</strong> when the user opens a message.</li>
<li>Once downloaded, bodies and attachments are <strong>cached locally</strong> to reduce quota usage and network overhead.</li>
</ul>
<h3>Synchronization Mechanism</h3>
<ul>
<li>RustMailer uses the <strong>Gmail History API</strong> to poll for changes.</li>
<li>It does <strong>not</strong> use the Pub/Sub push model; instead, it performs a <strong>lightweight polling cycle</strong> every few dozen seconds.
This design achieves good near-real-time sync without over-complicating infrastructure.</li>
<li>Message changes (flags, labels, etc.) are handled by directly calling Gmail’s API endpoints — RustMailer does <strong>not</strong> modify the local cache directly.</li>
<li>RustMailer manages <strong>History IDs</strong> internally and will automatically resynchronize if it detects any gaps or inconsistencies.</li>
</ul>
<p>This design lets applications:</p>
<ul>
<li>List and search messages instantly without managing Gmail concurrency or incremental metadata fetching themselves.</li>
<li>Avoid repeated API calls and excessive quota consumption.</li>
<li>Rely on RustMailer for safe, consistent synchronization.</li>
</ul>
<hr>
<h2>Developer Experience</h2>
<p>From a developer’s perspective, nothing major changes:</p>
<ul>
<li><strong>Authentication flow</strong> remains identical to IMAP OAuth2 — same redirect URI and OAuth token exchange process.</li>
<li>All other RustMailer APIs remain <strong>fully compatible</strong>.</li>
</ul>
<p>When creating a new account, simply choose the <strong>account type</strong>:</p>
<ul>
<li><code>IMAP/SMTP</code></li>
<li><code>Gmail API</code></li>
</ul>
<p>Everything else — synchronization, message listing, and search — works transparently.</p>
<hr>
<h2>Pagination Model Update</h2>
<p>Both IMAP and Gmail API now share a <strong>cursor-based pagination model</strong> for listing and searching messages.
This approach replaces the old <code>page</code> / <code>page_size</code> pattern, which was hard to unify because:</p>
<ul>
<li>IMAP search results cannot easily be paged by fixed index.</li>
<li>Cursor-based pagination avoids <strong>deep pagination performance issues</strong> and aligns with Gmail’s own API behavior.</li>
</ul>
<hr>
<h2>Summary</h2>
<p>By integrating the Gmail API, RustMailer:</p>
<ul>
<li>Removes Google IMAP scope limitations for commercial use</li>
<li>Provides native Gmail label support</li>
<li>Unifies the developer and user experience between IMAP and Gmail</li>
<li>Reduces complexity, quota usage, and synchronization errors</li>
<li>Keeps authentication and API structure consistent for minimal integration effort</li>
</ul>
<p>In short, Gmail API support makes RustMailer <strong>more compliant, scalable, and user-friendly</strong> — all while maintaining the same simple developer interface.</p>
<hr>

Self-hosted refers to the practice of running your own applications and services on your own servers or devices, giving you full control over your data and how it is managed.

selfhosted

RustMailer 1.5.0 introduces Gmail API support as an alternative to IMAP, addressing OAuth verification challenges with Google's sensitive IMAP scope. The integration provides easier approval through granular API scopes, native label support, and local caching with on-demand message fetching. Developers can now choose between IMAP/SMTP or Gmail API account types while maintaining the same authentication flow and API compatibility. The update includes a cursor-based pagination model for both protocols and uses Gmail's History API for lightweight polling synchronization.

RustMailer Now Supports Gmail API — A Better Way to Integrate with Gmail

<p>If you find rustmailer useful or think it might be helpful to you, please consider giving it a ⭐ on GitHub or sharing it with others. This will help more people discover rustmailer and contribute to the growth of the project. <a href="https://github.com/rustmailer/rustmailer" target="_blank" rel="noopener nofollow">https://github.com/rustmailer/rustmailer</a></p>
