Connect Gmail

This guide walks you — the tenant administrator — through everything you do in Google before connecting a Gmail mailbox from OpenDome. At the end you will have two values, a Client ID and a Client secret, that you paste into the OpenDome console. All of the work here happens in the Google Cloud Console, outside OpenDome.

You do this once per organization. There are two ways to connect, and this guide covers both:

• Google sign-in (recommended to start): one connector syncs the mailbox of the account that authorizes. This is the main path below.
• Service account, org-wide (advanced): one connector syncs a list of mailboxes in your Google Workspace, with a one-time approval by your Workspace admin and no per-user sign-in. See Org-wide sync with a service account.

Before you start: Workspace or personal Gmail?

This is the most important decision, and it shapes every step below. The connector works in both cases — it is the same Gmail API — but how you register the app differs a lot.

Your Google account	App type to create	Google verification?	Does access expire?	Recommended
Google Workspace (corporate domain)	Internal	No	No	✅ Yes
Personal Gmail, in testing	External · Testing	No	Yes — after 7 days	⚠️ Testing only
Personal Gmail, published	External · In production	Yes — security assessment (CASA)	No	❌ Not advised

Recommended path

If you are connecting company mail, use a Google Workspace account and create the app as Internal. It is the only path with no Google verification and no access expiry — exactly what a connector that syncs on a schedule needs.

Why personal Gmail is awkward

The permission we request (read your mail) is a restricted scope for Google. In an external app in testing mode, Google expires access after 7 days: the connector would stop syncing every week until someone re-authorizes by hand. Avoiding that means publishing the app, and then Google requires an annual, paid, third-party security assessment (CASA). So personal Gmail is fine for a one-off test but not for production.

What you will do

  Google Cloud Console
  ┌─────────────────────────────────────────────────────────────────────┐
  │ 1. Create/pick a project                                            │
  │ 2. Enable the Gmail API                                             │
  │ 3. Configure the consent screen (Internal vs External)              │
  │ 4. Create the OAuth client credentials  ──►  Client ID + Secret    │
  └─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
  OpenDome ── paste Client ID + Secret ── press "Connect" ── pick labels

The Client secret is a password: treat it like one (see Security).

Prerequisites

• A Google account with permission to create projects in Google Cloud.
  • For the recommended path (an Internal app), that account must belong to a Google Workspace organization and have a sufficient role (usually project Owner or Editor).
• The redirect URI OpenDome gives you (you need it in step 4). It is the address Google sends the browser back to after authorizing: https://<your-tenant-console>/v1/oauth/callback. OpenDome shows the exact URL on the connector’s connection screen — copy it from there.
• Optionally, which Gmail labels you want to sync (you pick them later, inside OpenDome; leaving it empty syncs Inbox and Sent).

Step 1 — Create (or pick) a Google Cloud project

A Google Cloud project is the container your OAuth app lives in.

1. Go to console.cloud.google.com.
2. In the project selector at the top, press New Project.
3. Give it a recognizable name (e.g. opendome-gmail-connector) and, if asked, pick your Workspace organization. Press Create.
4. Wait for it to be created and select it in the top selector before moving on.

Note

You can reuse an existing project if you already have one for integrations — for example the one you created for the Google Drive connector. What matters is that steps 2–4 happen inside the selected project.

Step 2 — Enable the Gmail API

The app can only call APIs that are enabled in the project.

1. Side menu → APIs & Services → Library.
2. Search for Gmail API.
3. Open it and press Enable.

Step 3 — Configure the OAuth consent screen

This is the window the authorizing person sees (“OpenDome wants to access your Gmail”). It must be configured once before you can create credentials.

1. Side menu → APIs & Services → OAuth consent screen.
2. User Type:
   • Pick Internal if your account is Google Workspace ← recommended. Only people in your organization can authorize, and Google requires no verification.
   • Pick External if you use personal Gmail (it is the only option).
3. Fill in the details: App name (e.g. OpenDome – Gmail connector), User support email and Developer contact. Logo and links are optional.
4. Scopes: press Add or remove scopes and add the read-only Gmail permission:

   https://www.googleapis.com/auth/gmail.readonly

   It is the only one OpenDome needs: read, never send, modify or delete. Save.
5. Only if you picked External: under Test users, press Add users and add the Google address that will authorize the connection. Without this, the authorization fails with an “unverified app” error.
6. Save. You do not need to press “Publish app” for the recommended path (Internal), nor to test with an External app in testing mode.

Step 4 — Create the OAuth client credentials

This is where the Client ID and Client secret come from.

1. Side menu → APIs & Services → Credentials.
2. Press + Create Credentials → OAuth client ID.
3. Application type: pick Web application.
4. Name: something recognizable (e.g. opendome-gmail-web).
5. Authorized redirect URIs: press + Add URI and paste OpenDome’s redirect URI (from Prerequisites). It must match exactly — protocol, host, port and path; a single different character makes Google reject the connection.

   https://<your-tenant-console>/v1/oauth/callback

6. Press Create. Google shows you a box with the Client ID and the Client secret.

Note

You can add several redirect URIs to the same app. You do not need to fill in “Authorized JavaScript origins”.

Step 5 — Copy the Client ID and Client secret

• Client ID — a long string ending in .apps.googleusercontent.com. Not a secret, but copy it as-is.
• Client secret — starts with GOCSPX-…. It is a password. Copy it somewhere safe; if you lose it you can generate another from the same screen.

Now, in OpenDome

1. Go to your tenant → Connectors → New connector → Gmail.
2. Paste the Client ID and Client secret into their fields.
3. Press Connect. The Google window opens: pick the account whose mailbox you want to sync and accept the read-only permission. You return to OpenDome automatically.
4. Optionally adjust the Labels field: empty syncs Inbox and Sent; you can list specific labels (e.g. Invoices), or use all for the whole mailbox except Spam, Trash and Drafts.
5. Save. The connector is ready for its first sync.

Note

On Connect, OpenDome obtains — inside your cell — the “refresh token” that lets it keep reading the mailbox. That token never leaves your environment. The first sync reads everything in the labels you chose; later syncs only fetch what changed.

Labels behave like Gmail, not like folders

A message keeps its labels when you add new ones — labeling does not move it out of Inbox. Nested labels are independent: syncing Invoices does not include Invoices/2026; list both if you want both. And if a Gmail filter files mail with “Skip the Inbox”, that mail never carries the Inbox label — add its label to the connector (or use all) so it is picked up.

Org-wide sync with a service account (advanced)

One connector can sync many mailboxes of your Google Workspace — no per-user sign-in — using a service account with domain-wide delegation. This requires Workspace super-admin approval and replaces the sign-in flow above (you still need steps 1–2: a project with the Gmail API enabled).

1. In the project: IAM & Admin → Service Accounts → + Create service account. Name it (e.g. opendome-gmail-org), no roles needed. Create.
2. Open the service account → Keys → Add key → Create new key → JSON. A .json file downloads — it is a password, keep it safe.
3. Copy the service account’s Client ID (the long numeric Unique ID on its details page).
4. As a Workspace super-admin, go to admin.google.com → Security → Access and data control → API controls → Domain-wide delegation → Add new:
   • Client ID: the numeric ID from the previous step.
   • OAuth scopes: exactly

     https://www.googleapis.com/auth/gmail.readonly

   • Authorize.
5. In OpenDome, in the Gmail connector’s connection step, choose the service account option, paste the whole JSON file into its field, and fill in Mailboxes to sync with the addresses, comma-separated (e.g. ana@acme.com, luis@acme.com).

Caution

With delegation, that key can read the mail of any mailbox you list. Scope it deliberately, share the JSON with no one, and remove the delegation entry in admin.google.com if you stop using the connector.

Common problems

Symptom	Cause and fix
redirect_uri_mismatch on Connect	The app’s redirect URI does not match OpenDome’s exactly. Check protocol (http/https), host, port and path (/v1/oauth/callback), with no trailing slash.
“Access blocked: unverified app”	External app and you did not add your address as a test user (step 3.5), or you are authorizing with an account that is not on the list. Add the user — or, if you have Workspace, switch to an Internal app.
The connector stops syncing after ~1 week	External app in testing mode: Google expires access after 7 days. The real fix: Workspace + Internal app.
invalid_client	Client ID or Client secret copied wrong (spaces, truncation). Copy them again from step 5.
“Label not found” in the sync	The label name in the connector does not exist in that mailbox. Names match Gmail’s exactly (case-insensitive); a nested label is its full path, e.g. Invoices/2026.
unauthorized_client with a service account	Domain-wide delegation is missing or wrong: the numeric Client ID in admin.google.com must be the service account’s, and the scope must be exactly https://www.googleapis.com/auth/gmail.readonly. Delegation changes can take a few minutes to apply.
“Refresh token not received”	Happens if you re-authorize without forcing consent. Our app already asks for access_type=offline + prompt=consent, so press Connect again and accept once more.

Security

• Read-only. The only permission we request is gmail.readonly. OpenDome cannot send, modify or delete anything in the mailbox.
• Your credentials never leave your environment. The Client secret, the token — or the service-account key — live in a Secret inside your cell; the OAuth token exchange happens inside your cell. OpenDome’s global control plane never sees them and never contacts Google on your behalf.
• Minimal egress. The connector can only reach the strictly necessary Google domains (accounts.google.com, oauth2.googleapis.com, gmail.googleapis.com, www.googleapis.com); any other outbound traffic is blocked by default.
• Revocable at any time. Remove access from the Google account (myaccount.google.com/permissions), delete the OAuth client in Google Cloud, or — for a service account — remove the delegation entry in admin.google.com; the connector loses read access immediately.
• Secret rotation. To rotate, generate a new Client secret (or a new service-account key) in Google Cloud and reconnect it in OpenDome; the previous one is invalidated.