Mimestream Private Push (Beta)

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, 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            │
└────────────────┘      └────────────────┘

Registration Flow

To register for Private Push, the app performs a two-step authentication:

1. OAuth 2.0 with Mimestream 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 never leave your device, and 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 these events and forwards them to the appropriate device via APNs.
3. Apple Push Notification Service: Delivers the notification to the user’s device, waking the app to perform a sync.

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 can 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 exclusively on your device, stored in the macOS/iOS Keychain.

Current Deployment

Private Push is currently optional. Users who prefer the original IMAP IDLE-based push can continue using it on macOS (where background connections are permitted). Private Push is primarily intended for:

• iOS users (where IMAP IDLE is not feasible)—Private Push is available in the iOS beta
• Google Workspace users whose administrators have disabled IMAP
• Users who want faster, more comprehensive push notifications

Private Push is available as a Labs feature in Mimestream 1.9.0 and later on macOS, and is the default push mechanism in the Mimestream iOS beta. However, our intention is to eventually standardize on Private Push, as it provides the best user experience.

Questions

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