Gmail history and push notifications

GoogleHistoryPoller reconciles a connected mailbox from saved history state. GoogleWebhookIngress accepts authenticated push hints. A push message is not canonical mail content. Complete Google Cloud setup first.

Enable synchronization

GOOGLE_MAILBOX_SYNC_ENABLED=true enables import and history processing. GOOGLE_MAILBOX_WATCH_ENABLED=true separately enables watch/push. Watch requires working synchronization and complete trusted GOOGLE_PUBSUB_CONFIG_JSON routing. Watch is off by default.

Personal Gmail uses OAuth consent. Workspace delegation requires separate operator authority. Ingress does not receive mailbox refresh credentials. The public tunnel must forward only /v1/pubsub/push to ingress.

Configure Pub/Sub

Create a topic and authenticated push subscription in the mailbox client's Cloud project. Grant the Gmail publisher permission to publish to the topic. Match the push OIDC service account and audience to the configured MailGen route. The application then creates and renews mailbox watches.

Use the Cloud setup procedure. One subscription can serve the configured routing. Do not recreate it for every mailbox. Do not copy another deployment's callback.

Mapping checks the active subscription, verified email, watch expiry, current credential source, and original authorized onboarding operation. Identity in a notification alone does not authorize ingestion. Hints can remain held until onboarding completes.

Check progress

Inspect Gmail sync progress. Watch health, push arrival, and history advancement are separate signals. Creating Cloud resources or publishing a test message does not prove mailbox synchronization.

If push fails, inspect routing and OIDC authentication. Periodic history processing can continue without push. Expired history state triggers checked full recovery. Do not erase mailbox data to repair a history checkpoint.