Mimestream Private Push

Private Push does not have access to your Google account’s tokens or data.

Private Push is Mimestream’s unique push notification offering, designed to deliver real-time notifications without server-side access to your Google account data or tokens, protecting your privacy. This article provides a technical overview of the architecture and its privacy properties.

Background

Mimestream’s original push implementation uses IMAP IDLE (RFC 2177) to receive notifications directly from Gmail’s IMAP endpoint. While this approach requires no intermediary service, it has some limitations:

• Not possible on iOS: IMAP IDLE requires a persistent TCP connection, which iOS background execution policies do not permit.
• Blocked by administrators: Google Workspace administrators can disable IMAP access for their domain, breaking push entirely.
• Limited event types: IMAP IDLE only notifies on mailbox changes, missing other sync-relevant events like label modifications or message deletions.
• Higher latency: Google’s implementation of IMAP IDLE has much higher latency than their API-based push implementation does. There isn’t any theoretical reason for this, it’s purely an in-practice reality of Google’s implementation.

Private Push addresses these limitations using Google’s Gmail API push notifications via Cloud Pub/Sub, while maintaining a minimal-trust architecture.

Private Push Architecture

The following diagram is a high-level overview of the components and services involved in Mimestream Private Push:

      Google                Mimestream                Apple

┌────────────────┐      ┌────────────────┐      ┌────────────────┐
│ Google         │      │ Mimestream     │      │ Apple Push     │
│ Cloud Pub/Sub  │─────▶│ Private Push   │─────▶│ Notification   │
│                │      │ Service        │      │ Service (APNs) │
└────────────────┘      └────────────────┘      └────────────────┘
        ▲                       ▲                        │
        │                       │                        │
        │                       ▼                        │
┌────────────────┐      ┌────────────────┐               │
│ Gmail API      │◀─────│ Mimestream     │◀──────────────┘
│                │      │ App            │
└────────────────┘      └────────────────┘

On macOS, the app makes a direct encrypted connection to push.mimestream.com to receive push events. On iOS and iPadOS, the app receives events via Apple Push Notification Service (APNs). In both cases, the event is simply a signal for the Mimestream app to retrieve the actual mailbox changes/content directly from Gmail.

Registration Flow

To register for Private Push, the app performs a three-step process:

1. OAuth 2.0 with Mimestream Private Push Service: The app authenticates with the Mimestream Private Push Service using OAuth 2.0. This establishes a secure session and authorizes the device to register for push notifications.
2. OIDC Identity Token from Google: The app obtains an OpenID Connect (OIDC) identity token from Google and presents it to the Private Push Service. This token:
   • Proves identity only: It asserts the user’s email address but grants no API access.
   • Cannot access Gmail: Unlike OAuth access tokens, OIDC identity tokens cannot be used to read mail, send messages, or perform any Gmail API operations.
   • Short-lived: Identity tokens expire quickly and are only used during the registration handshake.
3. Gmail API Watch: The Mimestream app calls users.watch to register for push notifications on the user’s mailbox and have Gmail deliver them to the Mimestream-owned Pub/Sub topic.

The combination of Mimestream OAuth (for service authorization) and Google OIDC (for email address verification) ensures that only the legitimate account owner can register their device, while keeping Gmail credentials exclusively on the device.

The Mimestream Private Push Service does not have OAuth access tokens for your Google account. Your Gmail credentials stay on your device and only get used to authenticate with the Gmail API directly. The service cannot access your email data.

What the Private Push Service Stores

• Email address: Route notifications to the correct device
• APNs device token: Deliver push notifications via Apple
• Device identifier: Associate registrations with a specific device

Event Flow

1. Google Cloud Pub/Sub: Gmail publishes notification events to a Mimestream-owned Pub/Sub topic.
2. Mimestream Private Push Service: Our service receives each event and routes it to the appropriate device.
3. Device delivery: On macOS, the service forwards the event over a direct encrypted connection to push.mimestream.com. On iOS, APNs delivers it to the device and wakes the app.
4. Direct Gmail sync: The app uses its on-device Google credentials to retrieve the actual mailbox changes directly from Gmail.

Event Payload Structure

When Gmail publishes a notification to Cloud Pub/Sub, the payload is intentionally minimal:

{
  "emailAddress": "user@example.com",
  "historyId": "1234567"
}

• emailAddress: Identifies which mailbox changed. Used to route the notification.
• historyId: An opaque identifier representing a point in the mailbox’s history timeline. The app uses this to call users.history.list and fetch the actual changes.

The Private Push Service receives and forwards this payload without modification. The historyId is semantically meaningless without an authenticated Gmail API connection—it’s simply an integer that the app uses to request “what changed since this point?”

What the Private Push Service Cannot Do

Because the Private Push Service does not have OAuth tokens for your Google account, the service:

• Cannot read your email: No access tokens means no API access.
• Cannot see message content: The push payload contains only an email address and history ID.
• Cannot see who emailed you: Sender information is not included in push events.
• Cannot see message subjects: Subject lines are not included in push events.
• Cannot impersonate you: OIDC identity tokens cannot be exchanged for access tokens.
• Cannot modify your mailbox: Read, write, send, and delete operations all require OAuth tokens.

The Private Push Service functions purely as a routing layer, mapping email addresses to device tokens and forwarding opaque history IDs.

Comparison to Other Email Apps

Most third-party email apps that offer push notifications require your OAuth credentials to be stored on their servers. The typical solution is to build a sync service that:

1. Holds your OAuth refresh token in their cloud infrastructure
2. Maintains an authenticated IMAP session with Gmail on your behalf
3. Receives push events and fetches message details server-side
4. Delivers rich notifications containing message content

This architecture means these services have persistent, full access to your email—they could read every message, see every sender, and access your complete mail history. A breach of their infrastructure could expose:

• Complete email archives for all users
• OAuth credentials enabling ongoing account access
• Ability to send email as compromised users
• Historical message content and metadata

Private Push explicitly avoids this model. By forwarding only opaque history IDs and leaving the actual Gmail sync to the on-device app, we eliminate the need for server-side credentials entirely. Your OAuth tokens remain stored on your device’s system keychain.

Availability

Private Push launched with Mimestream 1.10 and is enabled by default on macOS 26 and later. Users on older macOS versions continue to use the original IMAP IDLE-based push. Private Push also powers notifications for Mimestream on iOS and iPadOS, where persistent IMAP IDLE connections are not feasible.

Questions

For questions about Private Push or Mimestream’s security model, contact privacy@mimestream.com.