Google Workspace
Sonora can sync email and calendar data for people across your organization through Google Workspace domain-wide delegation. Your Google admin authorizes Sonora’s service account to read data on behalf of users in your domain. No credentials are exchanged.
What you’ll need
Section titled “What you’ll need”- Google Workspace admin access (Super Admin or delegated API controls)
- An admin account in your domain for Sonora to use for user discovery and mail sync (e.g.,
sonora@yourcompany.com)
Choose your scopes
Section titled “Choose your scopes”Pick the integrations you want, then combine the scopes for the next step.
| Integration | Scope | What syncs |
|---|---|---|
| Gmail | https://www.googleapis.com/auth/gmail.readonly | Email threads, participants, timestamps |
| Gmail (user discovery) | https://www.googleapis.com/auth/admin.directory.user.readonly | Lists domain users for multi-mailbox sync |
| Google Calendar | https://www.googleapis.com/auth/calendar.readonly | Events, attendees, meeting links |
All scopes are read-only. Sonora never sends emails, creates events, or modifies your data.
Configure domain-wide delegation
Section titled “Configure domain-wide delegation”Sonora’s client ID: 102467209466409202547
- Open Google Admin Console and go to Security → Access and data control → API controls
- In the Domain-wide delegation section, click Manage Domain Wide Delegation
- Click Add new
- Paste Sonora’s client ID into the Client ID field
- Paste your chosen scopes into OAuth scopes, comma-separated. For Gmail with user discovery:
https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/calendar.readonly
- Click Authorize
Changes take effect within a few minutes, though Google notes it can take up to 24 hours.
Configure Sonora
Section titled “Configure Sonora”In Sonora’s data source configuration, enter the Admin Email — a Google Workspace admin account that Sonora will use for two purposes:
- User discovery: Sonora calls the Admin SDK Directory API to list all active users in your domain.
- Mail sync: Sonora reads each user’s mailbox via domain-wide delegation.
Most teams create a dedicated admin account (e.g., sonora@yourcompany.com) rather than using a personal account. This account needs a Google Workspace license with admin privileges.
Filtering users
Section titled “Filtering users”By default, Sonora syncs all active (non-suspended) users in your domain. You can control which mailboxes are synced:
- Include Users: Only sync specific users. Enter one email per line. When set, Sonora skips user discovery and syncs only these mailboxes.
- Exclude Users: Skip specific users during sync. Enter one email per line. Applied after user discovery.
After setup
Section titled “After setup”Sonora starts syncing automatically. Initial sync pulls recent history for each user; subsequent syncs are incremental per-user.
Check sync status in Settings → Integrations. If sync stalls, the most common cause is the delegation not having propagated yet — wait an hour and check again.
Revoking access
Section titled “Revoking access”Remove Sonora’s client ID from the domain-wide delegation list in Google Admin Console. Access stops immediately. No data needs to be deleted on Google’s side since Sonora only had read access.
Security notes
Section titled “Security notes”Domain-wide delegation authorizes Sonora’s service account to call Google APIs as users in your domain, scoped to the specific permissions you granted. Sonora never receives passwords, OAuth tokens, or API keys from your organization. Your Google admin retains full control and can revoke access at any time.
If your network requires IP allowlisting, see Sonora’s static IPs.