Knowledge BaseKnowledge Base

Setting Up the Gmail Connector

Let your team's AI assistants read, search, and compose Gmail messages on their own behalf via Domain-Wide Delegation.

April 25, 2026
6 min read

Path: Connectors → Gmail → Configuration

What this connector does

The Gmail connector lets your team's AI assistants read recent emails, search the inbox, draft replies, and send messages — each on behalf of the signed-in user, not a shared mailbox. The signed-in user's permissions in Gmail (and your Wazzi access groups) determine what they can do.

Wazzi connects via a Google Service Account with Domain-Wide Delegation (DWD). You configure the connector once at the org level with a service account JSON key; from there, every API call impersonates the logged-in user automatically. No per-user OAuth tokens to manage.

Before you start

Gmail's setup is the most involved of any Wazzi connector — there's a one-time GCP + Google Workspace Admin pairing. Plan for ~30 minutes the first time. Once it's done it's done.

You'll need:

  • Admin access to a Google Cloud project (any project will do; new projects are free).
  • Super Admin access to your Google Workspace (admin.google.com) — DWD has to be authorized at the Workspace level, not just GCP.
  • Your Google Workspace primary domain (e.g., yourcompany.com).
  • A Workspace email in your domain that has Gmail enabled — used to validate the connection.

1. Create a service account in Google Cloud

  1. Go to console.cloud.google.com and pick (or create) a project.
  2. Open APIs & Services → Library, search for Gmail API, and click Enable.
  3. Open APIs & Services → Credentials, click Create Credentials → Service Account.
  4. Name it "Wazzi Gmail MCP" (or similar). Skip the optional roles step. Click Done.
  5. Open the new service account, go to the Keys tab, click Add Key → Create new key, choose JSON, and click Create. A JSON file downloads. Treat this like a password.
  6. Copy the service account's client_id from the same page — you'll need it for the next step (it's a long number, not the email).

2. Authorize Domain-Wide Delegation in Google Workspace

  1. Go to admin.google.com → Security → Access and data control → API controls.
  2. Click Manage Domain Wide Delegation → Add new.
  3. Paste the service account Client ID from step 1.
  4. Add the OAuth scopes Wazzi needs:
    • https://www.googleapis.com/auth/gmail.readonly — list, search, read messages
    • https://www.googleapis.com/auth/gmail.compose — create drafts
    • https://www.googleapis.com/auth/gmail.send — send messages
    Add only the ones you actually want available — fewer scopes = smaller blast radius.
  5. Click Authorize.

Reference: Google's official guide is at Create credentials → Service account and Workspace Admin → Domain-wide delegation.

What this connector unlocks for your team

Once configured, members with the right MCP permissions can ask Claude / ChatGPT / Cursor things like:

  • "List the last 10 emails in my inbox."
  • "Find the email from Acme legal about the renewal."
  • "Draft a reply to the most recent thread saying we'll get back tomorrow."
  • "Send 'Quick FYI: standup moved to 10am' to the team alias."

Each call operates on the signed-in user's mailbox — there's no shared "Wazzi" account.

Steps — configuring Gmail in Wazzi

1. From the Connectors catalog, click Configure on the Gmail tile.

You'll land on Gmail's Configuration tab:

Gmail connector Configuration tab

2. Fill in the fields.

  • Service Account JSON — open the JSON key file you downloaded and paste the entire contents. It looks like { "type": "service_account", "project_id": "...", "private_key": "...", ... }. The full blob.
  • Email Address — a Workspace email in your domain (e.g., admin@yourcompany.com). Wazzi uses this to verify Domain-Wide Delegation is wired up correctly, and as a default sender for any drafts created on behalf of the org.
  • Company Domain — your Workspace primary domain (e.g., yourcompany.com).

3. Click Test Connection.

Wazzi attempts a lightweight Gmail API call as the verification email. Success means DWD is wired correctly.

4. Click Save Configuration.

Troubleshooting

  • "Service account not authorized" or "unauthorized_client". The Workspace Admin Domain-Wide Delegation entry is missing or the client_id you pasted there doesn't match this service account. Re-do step 2 of Before you start.
  • "Insufficient Permission" when calling a tool. The scope for that action wasn't added in DWD. Add it in admin.google.com → API controls → Domain Wide Delegation, then retry. (Token cache may need ~5 minutes to refresh.)
  • "User not found" / 404. The Email Address field doesn't match a real Workspace user. Use a real, mailbox-enabled user in your domain.
  • "Gmail API has not been used in project ... or it is disabled." Step 1.2 was skipped. Go back to GCP Console → APIs & Services → Library and enable the Gmail API.
  • The JSON key looks malformed. Make sure you pasted the full file contents, including the curly braces. The private_key field has embedded \n — that's normal, leave them as-is.

Best practices

  • Use a dedicated service account, not a personal Google project. Tie its lifecycle to the Wazzi integration so revoking access is one click in GCP.
  • Restrict scopes to what's actually needed. If your team will only read Gmail, don't grant gmail.send or gmail.compose.
  • Rotate the service account key periodically. Quarterly rotation is a healthy cadence — generate a new key in GCP, paste into Wazzi, then delete the old key in GCP.
  • Audit who has Gmail MCP permissions. Reading another employee's email (because they're signed in to Wazzi MCP from the AI) is sensitive. Grant carefully — see Managing Permissions.

Frequently asked questions

Does each user need to grant OAuth consent?
No — that's the whole point of Domain-Wide Delegation. The service account is pre-authorized at the Workspace level to impersonate any user in your domain.

What does "impersonate" mean here? Can the service account read my email without me knowing?
The service account's API calls happen only when a signed-in Wazzi user invokes a Gmail MCP tool from an AI assistant. Each call is logged in your org's Audit Log. Outside of that, the service account makes no calls.

Does this work for personal Gmail (not Workspace)?
No. Domain-Wide Delegation is a Google Workspace feature; personal Gmail accounts don't support it.

Where is the JSON key stored?
Encrypted at rest with per-org keys. The plaintext is decrypted only at request time and never logged.

What's next

Was this article helpful?