Skip to main content

Google Service Accounts

Service accounts provide a powerful way for Google Workspace admins to grant EmailEngine access to any email account in the organization without requiring individual user consent. This guide shows you how to set up service accounts with domain-wide delegation.

Overview​

What are Service Accounts?​

Service accounts are a special type of Google account intended for applications rather than users. With domain-wide delegation, a service account can act on behalf of any user in your Google Workspace organization.

Key Concepts​

Two-Legged OAuth2:

  • No user interaction required
  • No consent screens
  • Admin grants access once for entire domain
  • EmailEngine can access any user's mailbox

Domain-Wide Delegation:

  • Requires Google Workspace (not free Gmail)
  • Requires super admin privileges
  • Admin authorizes specific scopes for the service account
  • Service account can impersonate any user in the domain

When to Use Service Accounts​

Best For:

  • Enterprise Google Workspace deployments
  • Centralized email management
  • Accessing multiple user mailboxes from one application
  • Automated workflows without user interaction
  • Systems integration and monitoring

Not Suitable For:

  • Free Gmail accounts (Google Workspace only)
  • Public-facing applications (users outside your organization)
  • Applications where users should control access

Benefits and Limitations​

Benefits​

No User Consent Required:

  • Access granted by admin once
  • No OAuth2 flow for each user
  • Seamless automated access

Centralized Management:

  • Admin controls all access
  • Easy to revoke for entire organization
  • Audit trail of service account usage

Scalability:

  • Add new users without re-authentication
  • Access any user's mailbox with same credentials
  • Ideal for enterprise deployments

Limitations​

Google Workspace Only:

  • Does not work with free @gmail.com accounts
  • Requires paid Google Workspace subscription

Requires Admin Access:

  • Must be Google Workspace super admin
  • Cannot be delegated to non-admin users

Organization-Scoped:

  • Only works for users in your organization
  • Cannot access external Gmail accounts

Credential Security:

  • Service account credentials provide access to all users
  • Must be stored very securely
  • Compromised credentials = access to entire organization's email

Step 1: Create a Google Cloud Project​

Go to Google Cloud Console and create a new project.

Click the project selector and then New Project.

Fill in the project name (e.g., "EmailEngine Service Account").

Wait for the project to be created, then click Select project to switch to it.

Even though service accounts don't show consent screens to users, the form allows us to configure required project details.

Navigate to APIs & Services → OAuth consent screen.

Select User Type​

Must Be Internal

For service account projects, the user type must be Internal. Service accounts only work within your Google Workspace organization.

Select Internal and click Create.

Fill in App Information​

Fill in the required fields:

  • App name: "EmailEngine Service Account" (or your app name)
  • User support email: Your email address
  • Developer contact information: Your email address

These fields are required but won't be shown to users since service accounts don't use consent screens.

Click Save and continue.

Configure Scopes​

Click Add or remove scopes.

The required scope (https://mail.google.com/) for IMAP and SMTP is not in the default list, so we need to add it manually.

Scroll to the end of the scopes list and manually add:

https://mail.google.com/

Click Add to table then Update.

The scope should now appear in the "Restricted scopes" section.

Click Save and continue to finish consent screen setup.

Step 3: Create Service Account​

Navigate to APIs & Services → Credentials and click the Manage service accounts link (bottom right corner).

Click Create service account.

Configure Service Account​

Service account name: Choose a descriptive name (e.g., "emailengine-service")

Service account ID: Auto-generated, but you can customize

Description: Optional description

Click Create and continue.

Grant Role​

Role: Select Owner

Role Selection

The "Owner" role is used here for simplicity. For production, you may want to use a more restrictive role, but "Owner" has been tested and confirmed working.

Click Continue.

Complete Setup​

Leave the optional fields empty and click Done.

Step 4: Enable Domain-Wide Delegation​

Now we need to authorize the service account to access user mailboxes.

Get Client ID​

From the service accounts list, copy the OAuth2 Client ID for your service account.

Finding Client ID

The Client ID is a long numeric string in the service account listing. You'll need this for domain-wide delegation setup.

Open Google Admin Console​

Open Google Admin Console for your domain and search for "API Controls".

Manage Domain-Wide Delegation​

Scroll down to find the "Domain-wide delegation" section and click Manage domain-wide delegation.

Click Add new.

Authorize API Client​

Client ID: Paste the Client ID you copied from the service account

OAuth scopes: Enter the same scope as in the consent screen setup:

https://mail.google.com/

Click Authorize.

Scope Must Match

The scope entered here must exactly match what you configured in the OAuth consent screen. Otherwise, the service account won't have the required permissions.

Step 5: Generate Service Account Key​

Return to the Google Cloud Console service accounts page.

Open the context menu for your service account (three dots) and click Manage keys.

Click Add Key → Create new key.

Select JSON as the key type and click Create.

The browser will automatically download the key file as a .json file.

Store Key Securely

This key file provides access to all email accounts in your organization. Store it very securely:

  • Use secret management systems (AWS Secrets Manager, Azure Key Vault, etc.)
  • Never commit to version control
  • Restrict file permissions
  • Rotate keys periodically

Key File Format​

The downloaded JSON file contains:

{
  "type": "service_account",
  "project_id": "service-test-338412",
  "private_key_id": "83fd56801b0e46d21ad88300b73d3727e6d46961",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w...\n",
  "client_email": "emailengine-2lo-test@service-....iam.gserviceaccount.com",
  "client_id": "103965568215821627203",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/.../x509/emaile..."
}

The important fields are:

  • client_id: Maps to "Service client" in EmailEngine
  • private_key: Maps to "Secret service key" in EmailEngine

Step 6: Enable Gmail API​

Service accounts need Gmail API enabled to resolve account email addresses during setup.

Navigate to APIs & Services → Dashboard and click Enable APIs and Services.

Search for "mail" to find Gmail API.

Click Enable.

Step 7: Configure EmailEngine​

Now configure EmailEngine to use the service account.

Add Gmail Service Account Application​

  1. Open EmailEngine dashboard
  2. Navigate to Configuration → OAuth2
  3. Click Add application
  4. Select Gmail Service Accounts

Upload Credentials File​

Credentials file: Use the file input to select the service account key JSON file

EmailEngine will automatically extract and populate:

  • Service client (from client_id)
  • Secret service key (from private_key)

Base scope: Select IMAP and SMTP

Enable this app: Check if you want it available immediately

Click Register app to save.

Automatic Field Population

When you upload the JSON key file, EmailEngine automatically fills in all required fields. You don't need to copy and paste individual values.

Step 8: Add Email Accounts​

With the service account configured, you can now add email accounts without any user interaction.

Add Account via API​

Add accounts using the Register Account API endpoint:

curl -X POST https://your-ee.com/v1/account \
  -H "Authorization: Bearer YOUR_EMAILENGINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user123",
    "name": "John Doe",
    "email": "john@company.com",
    "oauth2": {
      "provider": "gmailService",
      "auth": {
        "user": "john@company.com"
      }
    }
  }'

Key Points:

  • No accessToken or refreshToken needed
  • No passwords required
  • Just specify the user email address
  • Service account handles authentication automatically

Response:

{
  "account": "user123",
  "state": "new"
}

The account will be created and should transition to "connected" state within moments.

Add Multiple Accounts​

You can add any user in your organization:

# Add sales team accounts
curl -X POST https://your-ee.com/v1/account \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "sales-1",
    "email": "alice@company.com",
    "oauth2": {
      "provider": "gmailService",
      "auth": { "user": "alice@company.com" }
    }
  }'

curl -X POST https://your-ee.com/v1/account \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "sales-2",
    "email": "bob@company.com",
    "oauth2": {
      "provider": "gmailService",
      "auth": { "user": "bob@company.com" }
    }
  }'

Verify Accounts​

Check the accounts list in EmailEngine:

Service account-based accounts appear as "Gmail OAuth2" accounts in the list.

Account Management​

Listing Service Account Accounts​

Service account accounts appear like any other OAuth2 account:

curl https://your-ee.com/v1/accounts \
  -H "Authorization: Bearer YOUR_TOKEN"

Updating Service Account Accounts​

Update account settings using the Update Account API endpoint:

curl -X PUT https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe (Updated)",
    "subconnections": ["\\Sent"]
  }'

Deleting Service Account Accounts​

Delete accounts using the Delete Account API endpoint:

curl -X DELETE https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Security Best Practices​

Key Storage​

Do:

  • Store keys in secret management systems (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
  • Encrypt key files at rest
  • Use environment variables for production
  • Restrict file permissions (0600)

Don't:

  • Commit keys to version control
  • Store keys in plain text
  • Share keys via email or chat
  • Store keys in public locations

Access Control​

Limit Access:

  • Only admins should access service account keys
  • Use separate keys for different environments (dev/staging/prod)
  • Audit key usage regularly
  • Rotate keys periodically (e.g., every 90 days)

Monitor Usage:

  • Enable Google Cloud audit logs
  • Monitor EmailEngine access logs
  • Alert on unusual account access patterns
  • Review service account activity regularly

Scope Limitation​

Principle of Least Privilege:

  • Only grant scopes actually needed
  • For IMAP access, https://mail.google.com/ is required
  • Consider separate service accounts for different purposes
  • Document why each scope is needed

Use Cases​

Enterprise Email Management​

Monitor and manage all employee email accounts:

  • Compliance and archiving
  • Security scanning
  • Backup solutions
  • E-discovery

Help Desk Integration​

Access user mailboxes for support:

  • Troubleshoot email issues
  • Recover deleted messages
  • Investigate delivery problems
  • Provide user assistance

Automated Workflows​

Build automated systems:

  • Invoice processing from shared mailbox
  • Customer support ticket creation
  • Email-based data extraction
  • Notification routing

Migration and Sync​

Synchronize email data:

  • Migrate between systems
  • Backup to external storage
  • Mirror to CRM systems
  • Sync with document management