Google Workspace integration

Google Workspace integration for AgentSDR

One Google Cloud service account, authorised once by your Workspace admin, lets AgentSDR send from and read your team's Gmail mailboxes. Nobody signs in to Google, and no password is shared.

Read the setup guide All integrations

Google Workspace

Gmail sending and reply sync through a service account

Per organization

Connected in: Settings, Email, Connection
Powers: Email campaignsMailboxesReply sync
Credentials: Verified with one live call, then stored encrypted

What it powers

Sending, mailboxes and replies

Until Google Workspace is connected for an organization, email accounts, email campaigns and reply sync are off.

Sending
Campaign emails go out through Gmail's send API, from the mailbox you add, with its own daily limit and sending hours.
The mailbox list
Add each Workspace address under Settings, Email, Mailboxes. AgentSDR acts as that user to prove delegation works, then keeps it connected.
Reading replies
Gmail pushes a notification to AgentSDR through Google Cloud Pub/Sub, so a reply is matched to its lead and stops the sequence.

What you need

Workspace admin access, plus about 15 minutes

A Google Workspace domain. A free personal @gmail.com account does not work.
A Workspace super admin, who does the Admin console part. Only super admins can set up domain-wide delegation.
Someone who can create a project and a service account in Google Cloud. Creating the key needs the Service Account Key Admin role.
An AgentSDR owner or admin, to save the credentials.
For reply sync: permission to create Pub/Sub topics in the same project, and a public HTTPS address for your AgentSDR.

Setup

Five steps from a blank Google Cloud project to a connected mailbox

The short version. The documentation has every click, with screenshots and the fixes for each error Google can return.

01
Create a service account and key
In a Google Cloud project, enable the Gmail API, create a service account with no roles, and download a JSON key.
02
Authorise it in the Admin console
A super admin adds the service account's Unique ID under Manage domain-wide delegation, with the two Gmail scopes on one line.
03
Connect it in AgentSDR
Open Settings, Email, Connection, upload the key file and click Connect & test. AgentSDR asks Google for one token to prove the key is real.
04
Add a mailbox
Enter a real Workspace address. AgentSDR acts as that user and reads their Gmail profile, which proves delegation for that address.
05
Turn on reply sync
Create a Pub/Sub topic, let Gmail publish to it, add a push subscription pointing at AgentSDR and schedule the daily watch renewal.

The full step-by-step guide with screenshots and troubleshooting

Security and data

Two scopes, an encrypted key, one organization per mailbox

What AgentSDR can do in Gmail is decided by the delegation your admin grants, and you can review or remove it at any time.

Two scopes only
gmail.send to send mail and gmail.readonly to read mail, test a mailbox and register reply notifications. AgentSDR cannot delete mail or change settings.
Encrypted at rest
Saved credentials are encrypted with AES-256-GCM using your instance's INTEGRATION_CREDENTIALS_KEY and are never sent back to the browser. Leave a secret field blank when editing to keep the saved value.
Verified before saving
Each credential is checked with one live call before it is saved. If the check fails, nothing is stored and the form shows the reason.
Disconnecting is two steps
Disconnecting in AgentSDR does not remove the delegation. Remove it in the Admin console too if you are done with it. To rotate, upload a new key and delete the old one in Google Cloud.

FAQ

Questions, answered

Do my reps have to sign in to Google?

No. A Workspace super admin authorises the service account once through domain-wide delegation. AgentSDR then asks Google for a token that says this service account is acting as a given mailbox, so there is no per-user consent screen and no password.

Can I use a personal Gmail address?

No. The integration needs a Google Workspace domain, because only a Workspace super admin can set up domain-wide delegation. A free personal @gmail.com account does not work.

Which permissions does AgentSDR ask for?

Two Gmail scopes: gmail.send and gmail.readonly. They let it send mail and read mail. It cannot delete mail or change mailbox settings.

Do I need Pub/Sub?

Sending works as soon as Google Workspace is connected. Replies are only picked up if you also set up Pub/Sub, because Gmail has to push a notification to AgentSDR. Without it a sequence keeps going after someone answers. A localhost install cannot receive pushes.

Can one mailbox belong to two organizations?

No. A Gmail address can belong to only one AgentSDR organization. Remove it from the other organization first.

What happens if I disconnect Google Workspace?

Background sending stops and the email pages show a Connect Google Workspace prompt. There is no environment-variable fallback. The delegation stays in your Admin console until you remove it there.

Blog