Skip to main content
Beagle Software
All topics 40

Email integration

Google email setup

Workspace admin · one-off

Before anyone in your organisation can connect a Gmail or Google Workspace mailbox to Beagle, an administrator has to register your own Google OAuth client once. Google reserves the permission that mail access needs for apps that have passed a paid annual security assessment — unless the app belongs to your own Workspace, in which case Google trusts it outright. So Beagle asks each customer for their own client rather than passing that cost on. It is a one-off job for whoever administers your Google Workspace, and it takes about ten minutes. Microsoft 365 mailboxes need none of this — connect those straight from Organisation Settings.

You need Google Workspace

This route relies on the Internal app type, which only exists inside a Google Workspace account. A personal @gmail.com address cannot register an Internal client, so consumer Gmail mailboxes cannot be connected this way. You also need to be a Workspace administrator (or have someone who is do these steps) — and an Admin in Beagle, because the settings page is Admin-only.

Step 1 — Create a project

  1. Sign in to console.cloud.google.com with your Workspace account — not a personal one.
  2. Open the project picker at the top of the page and choose New project. Name it something recognisable, such as Beagle CRM email, and create it.
  3. Make sure that new project is the one selected before continuing.

Step 2 — Configure the consent screen as Internal

  1. Go to APIs & Services → OAuth consent screen.
  2. Choose user type Internal and continue. This is the important choice: Internal keeps the app private to your Workspace, so Google does not require verification, does not require the paid security assessment, and does not cap you at 100 users.
  3. Fill in the app name (your staff will see it on the consent screen), a support email and a developer contact email. Nothing else is required.
  4. On the Scopes step, add the scope https://mail.google.com/. This is the one that grants IMAP and SMTP access, which is how Beagle reads and sends your mail. Save and continue.

If Google offers you External instead and Internal is greyed out, you are signed in with a personal Google account rather than a Workspace one. Sign out and start again with your Workspace account.

Step 3 — Create the OAuth client

  1. Go to APIs & Services → Credentials and choose Create credentials → OAuth client ID.
  2. Application type: Web application. Give it a name you will recognise later.
  3. Under Authorised redirect URIs, add the exact address shown on Beagle's Settings → Inboxes page, in the Google email connection setup box. Copy it from there rather than typing it — a single character out and Google refuses every sign-in with redirect_uri_mismatch.
  4. Create the client. Google then shows you a Client ID and a Client secret. Keep that window open for the next step; the secret can be downloaded, and can be regenerated later if you lose it.

Step 4 — Paste it into Beagle

Go to Settings → Inboxes and find Google email connection setup at the top. Paste in the Client ID and the Client secret, then save. The Connect Google buttons on the Sales and Customer Care inboxes stay greyed out until this is done.

Beagle stores the secret encrypted and never shows it again — the box stays blank afterwards, and the panel simply reports that a secret is set. To change the client later, paste a new secret; leave the secret box empty and the stored one is kept, so you can correct the Client ID on its own.

Step 5 — Connect the mailboxes

With the client saved, Connect Google becomes available on both the Sales and Customer Care inboxes. Choose it, sign in as the mailbox owner, and approve the access. Repeat for each mailbox you want Beagle to read.

Already had Google mailboxes connected?

They have to be reconnected once, after you save your own client. The permission Google issued for a mailbox is tied to the client that asked for it, so an existing connection cannot be moved across — there is no way around this and no data is lost. Affected mailboxes show as Error on the Inboxes page with “reconnect required”, and mail flows again as soon as you press Connect Google and sign in.

If something goes wrong

  • redirect_uri_mismatch — the redirect URI in Google does not match Beagle's exactly. Copy it again from the setup box; watch for a trailing slash or http instead of https.
  • “Access blocked: this app is not verified” — the consent screen was created as External rather than Internal. Change the user type on the OAuth consent screen.
  • Mailboxes drop to Error together, some time after setup — the client was deleted or its secret regenerated in Google. Save the current secret in Beagle and reconnect.
  • Connect Google is greyed out — no client is saved yet, or you are looking at the page before it finishes loading. Save the client first; the buttons enable straight away.