Grant domain-wide delegation and scopes
Authorize your Tantra service account in the Google Admin console with the exact OAuth scopes needed to send email and calendar invites.
Open in Tantra
These open the app in a new tab. You may be asked to sign in.
Overview
Domain-wide delegation is the permission that lets your Tantra service account act on behalf of the mailboxes in your Google Workspace domain. You grant it once, in your own Google Admin console, by authorizing the service account's client ID with a specific list of OAuth scopes. This article gives you the exact scopes to paste.
Before you start
- You must be a Google Workspace super administrator.
- You need the service account's client ID (a long numeric string). See Create a Google service account.
- Decide which engines you will use. Cold email needs the Gmail scopes. Calendar campaigns need the Calendar scope. Grant both if you plan to use both.
The scopes to grant
Copy these values exactly. Each is a full URL and must be entered as shown.
For cold email (the Gmail API):
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.modify
For calendar campaigns (the Calendar API):
https://www.googleapis.com/auth/calendar
If you plan to use both engines, grant all three in one delegation entry, separated by commas.
Field reference
| Scope | Required for | What it does |
|---|---|---|
https://www.googleapis.com/auth/gmail.send | Cold email | Lets Tantra send email as the mailbox |
https://www.googleapis.com/auth/gmail.modify | Cold email | Lets Tantra read message bodies to detect genuine replies and separate them from auto-responders |
https://www.googleapis.com/auth/calendar | Calendar campaigns | Lets Tantra create calendar events and add attendees so Google sends the invitation |
The gmail.modify scope is used to tell a real reply from an out-of-office bounce. If your policy narrows Gmail access to metadata only, Tantra still works, but it cannot read message bodies, so some reply details are left blank. You do not need to grant anything broader than the three scopes above.
Step-by-step
- Sign in to the Google Admin console at
admin.google.comas a super administrator. - Go to Security, then Access and data control, then API controls.
- Under Domain-wide delegation, click Manage domain-wide delegation.
- Click Add new.
- In Client ID, paste your service account's client ID.
- In OAuth scopes, paste the scopes you need from the list above, separated by commas.
- Click Authorize. The new entry appears in the delegation list.
What happens next
Delegation can take a few minutes to propagate across Google's systems. After you authorize, upload the service account to Tantra if you have not already, then verify your senders. If verification fails immediately, wait a few minutes and try again.
Common mistakes
- Pasting the service account email into the Client ID field. Use the numeric client ID, not the email.
- Granting a broader Gmail scope such as full mailbox access. Tantra only needs
gmail.sendandgmail.modify. - Forgetting the Calendar scope when you plan to run calendar campaigns. Gmail scopes alone do not enable calendar sending.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Senders stay disconnected after verifying | Delegation not propagated yet, or wrong client ID | Wait a few minutes, confirm the client ID matches the service account, then re-verify |
| Sender is calendar-only, not Gmail capable | Gmail scopes were not included in the delegation | Add gmail.send and gmail.modify and re-verify |
FAQ
Do I have to grant all three scopes?
No. Grant only the scopes for the engines you use. Cold email needs the two Gmail scopes. Calendar campaigns need the Calendar scope.
Why does Tantra need gmail.modify and not just gmail.send?
Sending needs gmail.send. Detecting real replies, and telling them apart from auto-responders, needs to read message bodies, which requires gmail.modify.
Is it safe to grant domain-wide delegation?
You grant it in your own console and can revoke it any time. The scopes above are limited to sending and reply detection. Tantra cannot use permissions you did not grant.
How long until delegation takes effect?
Usually a few minutes. If verification fails right after you authorize, wait and retry.
Related articles
Was this article helpful?
Related articles
- Create a Google service accountCreate a Google Cloud service account, enable the Gmail and Calendar APIs, and download the JSON key that Tantra uses to send as your mailboxes.
- Upload your service account to TantraUpload your service account JSON files to Tantra, tag them, and manage them. Files are encrypted at rest and can be soft-deleted.
- Add and verify your sendersPaste the mailboxes you want to send from and verify them against your uploaded service accounts using domain-wide delegation.