domainwidedelegation.comStart free

Use cases → Admin and governance

Automatically assign secondary email aliases in bulk

Add or update secondary email aliases for users across an organisation using domain-wide delegation and the Admin SDK.

Who it is forIT administrators managing user aliases at scale, e.g., for rebranding or department changes.
APIsAdmin SDK
Typical scopesadmin.directory.user.alias

The problem

Manually adding aliases is slow and error-prone, especially during migrations or when applying new naming standards. Bulk updates are needed, but the Admin console UI is impractical for hundreds of users.

How it works

  1. Prepare a list of users and desired aliases, ensuring no duplicates or conflicts.
  2. Impersonate an admin user via a service account with domain-wide delegation.
  3. Use the Admin SDK to add or update aliases for each user, handling conflicts in code.
  4. Log every change and verify alias assignment by querying the user object after each operation.

What changes

Aliases are programmatically assigned, cutting manual effort and ensuring consistency across the tenant.

The trap in this one. The Admin SDK's alias creation is eventually consistent: querying immediately after adding an alias often returns the old state, so scripts that re-check or retry too soon can double-assign or falsely report errors. Always implement a backoff and poll for propagation, or you risk duplicate alias errors and confusing logs.

Watch it explained

“Add Free Additional Email Addresses with Google Workspace” — StuffedBox on YouTube. Third-party video, included because it covers this ground well. We are not affiliated with the channel.

Questions people ask

Can I assign an alias that matches a deleted account or group?

No. The Admin SDK will reject attempts to assign an alias if that address is still reserved by a recently deleted user or group. Wait for the retention period to expire or clear the conflict manually.

What happens if I try to assign the same alias to multiple users?

The API will throw a 409 conflict error. Your automation must check for existing assignments and handle errors gracefully, especially in bulk operations.

Want this built?

This is a pattern we run in production. We will set up the delegation and build this on top of it — $500 per hour, most of it working the same day.

Talk to us Or read the setup guide

Related use cases

Audit which third-party apps can read your mail

List every OAuth grant across the domain and find the retired tools still holding access.

Automate joiners, movers and leavers

Create accounts, set group membership, provision Drive and hand over mailboxes without a manual checklist.

Continuously verify your delegation still works

A scheduled probe that proves every API still answers under every tenant, before a customer finds out otherwise.