Gmail realtime push setup (administrator)

Turn on provider-native push for a Gmail or Google Workspace mailbox so that new mail arrives in MailDesk in seconds instead of waiting for the next scheduled sync. A guided setup assistant walks you through every step inside Odoo and checks each prerequisite for you before you spend time in Google Cloud.

Turn on provider-native push for a Gmail or Google Workspace mailbox so that new mail arrives in MailDesk in seconds instead of waiting for the next scheduled sync. A guided setup assistant walks you through every step inside Odoo and checks each prerequisite for you before you spend time in Google Cloud.

Available in: Pro. Gmail realtime push is part of the MailDesk Pro module — it is not present in Basic, which always uses scheduled background sync. The mailbox itself is connected with the same Gmail OAuth credentials used for normal sync; realtime push reuses that connection and asks for no new permissions.

What it does

Gmail's API can notify your server whenever a mailbox changes, using Google's Cloud Pub/Sub messaging service and a Gmail "watch" registration. MailDesk's setup assistant helps you create the Pub/Sub resources in your own Google Cloud project, validates that everything is wired correctly, then registers the watch. After that, each time mail arrives, Google publishes a notification that reaches MailDesk's secure webhook, which triggers the normal Gmail sync for just that mailbox.

The push notification does not carry the email itself. It only tells MailDesk "this mailbox changed" — MailDesk then runs its usual incremental fetch and updates the inbox. Push therefore shortens the delay; it does not replace the proven sync engine behind it.

Why it matters

• Faster mail. New messages surface in seconds rather than waiting for the next scheduled sync.
• You stay in control. Every Google Cloud resource is created in your own project and owned by you. MailDesk only stores non-secret identifiers (your project id, the topic name, and the notifying service-account email) plus the settings its webhook needs to verify incoming notifications.
• Safe fallback. If push ever stops arriving, MailDesk automatically falls back to its scheduled background sync, so no mail is ever lost — push only ever makes things faster.

Requirements

• A Gmail or Google Workspace mailbox already connected to MailDesk over OAuth and syncing. See Gmail OAuth setup first.
• A Google Cloud project you can administer, with permission to enable APIs and create Pub/Sub topics, subscriptions, and a service account. The recommended path runs a single script in Google Cloud Shell.
• Your Odoo server reachable over HTTPS at a stable public address. Google will only push notifications to an https:// URL with a valid certificate. Plain http:// and local-only addresses cannot receive push.
• MailDesk Pro 4.2.0 installed (see the status note above).
• MailDesk works on Odoo 17, 18, or 19 — the steps below are the same on each.

Permissions required

• Configuring Gmail realtime push is restricted to MailDesk administrators (the Mailbox administrator access group). The assistant refuses to register a watch for a user without that access.

• The webhook secret that authenticates incoming notifications is visible only to MailDesk administrators.

Step 1 — Open the setup assistant

1. Go to MailDesk → Configuration → Mailboxes → Mailbox Accounts and open the Gmail account you want to speed up.
2. In the form header, click Configure Gmail Realtime. (Once push is configured, the same button reads Manage Gmail Realtime and reopens the assistant for review.)

The assistant opens as a step-by-step dialog with a status bar at the top: Preflight → Choose mode → Run setup script → Paste result → Validate & enable → Run realtime test → Done.

Step 2 — Run the preflight checks

The first screen confirms the prerequisites before you touch Google Cloud, so you do not waste time on a setup that cannot work. Click Run preflight. MailDesk checks, with a clear "OK" or "Action needed" beside each row:

• the account is a connected Gmail account with a usable OAuth token;
• your public address (web.base.url) is set and uses HTTPS;
• the webhook can be reached from the internet (MailDesk probes its own push URL);
• the push renewal and fallback sync jobs are active.

If a required check fails, the screen tells you exactly what to fix (for example "Set web.base.url in System Parameters" or "Switch web.base.url to https://"). Fix it, then click Run preflight again.

Step 3 — Choose a setup mode

When the required checks pass, pick how you want to create the Google Cloud resources:

Step 4 — Run the setup script in Google Cloud Shell (Recommended mode)

1. Enter your GCP project id. MailDesk fills in sensible default names for the topic (maildesk-gmail-push), the push subscription (maildesk-gmail-push-sub), and the signer service account (maildesk-pubsub-push) — adjust them only if you have a naming convention.
2. A ready-to-run script appears below. It is safe to re-run (idempotent): existing resources are detected and reused. The script:
   • enables the Gmail API and the Pub/Sub API in your project;
   • creates (or reuses) the Pub/Sub topic;
   • grants Google's Gmail publisher service account ([email protected]) permission to publish to that topic;
   • creates (or reuses) the OIDC signer service account;
   • creates (or updates) the push subscription pointing at your MailDesk webhook URL;
   • prints a final line beginning MAILDESK_PUSH_RESULT= followed by the values to paste back.
3. Copy the whole script, open Google Cloud Shell (a console link is provided), paste, and run it.

Step 5 — Paste the result

1. Click I've run the script to move to the paste step.
2. Copy the last line the script printed (it starts with MAILDESK_PUSH_RESULT={…}) and paste it into the box.
3. Click Parse JSON. MailDesk reads the three values it needs — your project id, the fully-qualified topic name, and the signer service-account email — and advances to validation.

If you used Advanced mode instead, type the same three values in directly and click Validate manually.

Step 6 — Validate and enable

Click Enable Realtime. MailDesk runs a checklist and shows each row's result:

• the public URL is configured and HTTPS;
• the webhook is reachable from the internet;
• the notification audience matches your URL;
• the topic name and signer service-account email are well-formed;
• the signer is saved to the webhook's allow-list;
• finally, Gmail's users.watch call succeeds against your topic.

When the last step succeeds, MailDesk stores the watch and shows its expiration date.

Step 7 — Run the realtime test

After the watch is registered, the assistant moves to a realtime test screen. Send a test email to this Gmail inbox from a safe sender, wait a few seconds, and click Re-check to watch the timeline confirm that the notification was delivered, verified, synced, and the message became visible in MailDesk. Click Finish when you are done.

Expected result

The mailbox now receives push notifications. New mail in the Gmail inbox appears in MailDesk within a few seconds, and the mailbox account form shows the realtime status as Active. The watch is renewed automatically before it expires, so you do not need to repeat this setup.

Troubleshooting

Related

• Gmail OAuth setup — connect the mailbox first
• Outlook realtime push setup
• Realtime & synchronization architecture — how push, sync, and prefetch fit together
• Mailbox setup
• Licensing & tiers