AboutFree templates
How-to · Google Workspace

Add a domain to Google Workspace

At the end your extra domain is added to Google Workspace as a secondary domain or a user alias domain, verified with a TXT record, and ready for Gmail.

Updated 8 steps4 official sources
Start hereBack to the playbook
Before you start

What you need before step 1

Applies to: Google Workspace editions that support multiple domains (Google notes the option is not available on the legacy free edition)

Admin roles you need

  • Google Workspace admin with the Domain settings administrator privilege
  • A login to the DNS host account for the domain you are adding

Licences

  • Secondary domain: each user on it needs their own Google Workspace licence. User alias domain: no extra licences (it adds addresses to existing users).

Download

BIND 9 from ISC (includes dig)Only needed on macOS or Linux if dig is missing. Windows has nslookup built in.https://www.isc.org/download/Download

Also have ready

  • The domain is registered and you control its DNS
  • If you removed this domain recently, Google says you may need to wait up to 24 hours before adding it again
Step by step

8 steps

  1. 1

    Choose secondary domain or user alias domain

    Where: Reading only

    Google offers two types:

    • Secondary domain: a separate set of users, each with their own account and mailbox. Choose this for a separate team or business unit, or if you plan to replace your primary domain with this one. Each user needs a licence.
    • User alias domain: gives every existing user an extra address at the new domain. They can send and receive from either address, with no extra licence.

    Google allows up to 599 secondary domains and up to 20 user alias domains. Google does not describe converting an alias domain into a secondary domain later, so choose carefully.

    You should see: You know which type you will add.
  2. 2

    Open Manage domains

    Where: Google Admin console (admin.google.com) > Menu > Account > Domains > Manage domains

    Sign in with your admin account and follow the menu path, or go straight to https://admin.google.com/ac/domains/manage.

    You should see: A list of your domains with an Add a domain option.
  3. 3

    Add the domain

    Where: Google Admin console > Account > Domains > Manage domains > Add a domain

    Select Add a domain, type the domain name (for example fabrikam.com), choose Secondary domain or User alias domain, and select Add domain & start verification. Domain names containing "gmail" are rejected.

    You should see: The verification screen opens for the new domain.
  4. 4

    Copy the TXT verification value

    Where: Google Admin console > Manage domains > Verify domain

    If the verification screen is not already open, select Verify domain next to the domain. Choose your registrar or DNS host from the list, or My domain uses a different host. Copy the whole Value, including google-site-verification=.

    You should see: You have a value like google-site-verification=abcdef123_456wx789yz.
  5. 5

    Add the TXT record at your DNS host

    Where: DNS host control panel > fabrikam.com > DNS records > Add record

    Add a record:

    • Type: TXT
    • Name / Host: leave blank or enter @ (for a subdomain, enter just the subdomain part)
    • Value: the full value you copied

    Select Save. Google links to host-specific steps from its Verify your domain with a TXT record article, including Cloudflare, GoDaddy, Amazon Route 53, Namecheap, Squarespace and Wix.

    You should see: The TXT record is listed at the DNS host.
  6. 6

    Confirm the record is visible

    Where: Command Prompt on Windows, or Terminal on macOS or Linux

    Check the TXT record through a public resolver before you ask Google to verify.

    nslookup -type=txt fabrikam.com 8.8.8.8
dig @8.8.8.8 TXT fabrikam.com +short
    You should see: A line containing your google-site-verification value.
  7. 7

    Confirm verification in the Admin console

    Where: Google Admin console > Manage domains > the domain's verification screen

    Select Come back here and confirm (wording may vary), then Confirm. Google says it can take up to 72 hours for the TXT record to be recognised. If your organisation uses multi-party approval for sensitive actions, wait for approval.

    You should see: The domain shows as verified in Manage domains.
  8. 8

    Activate Gmail for the domain

    Where: Google Admin console > Account > Domains > Manage domains

    Find the domain and select Activate Gmail, then follow the steps. This involves publishing Google's MX record (see the related Change MX records how-to). Do this only when you are ready for new mail to that domain to arrive in Gmail.

    You should see: Activate Gmail is no longer shown and the domain is active for Gmail.
From experience

Expert tips

Pick alias or secondary for the right reason

A user alias domain gives every existing user and group an extra address at no extra per-user cost, but people still sign in with their primary address. A secondary domain holds its own users, each with their own licence. For a merger where staff keep separate identities, use secondary; for a rebrand or extra spelling of the same organisation, use alias.

Watch for personal accounts that get renamed

Google warns that adding a user alias domain automatically renames any existing personal Google accounts that use that domain. Add it as a secondary domain first to discover those accounts and deal with them before switching to an alias.

Get the host field right

Google says to leave the host or name field blank or enter @. Typing the full domain at hosts that append it automatically creates fabrikam.com.fabrikam.com. Add the verification TXT as a new record alongside any existing TXT records such as SPF; do not overwrite them.

Check the authoritative server before waiting 72 hours

Google allows up to 72 hours for the TXT record to be recognised, but you can tell in seconds whether it is published correctly by asking the domain's own nameserver: dig NS fabrikam.com +short, then dig @<that-nameserver> TXT fabrikam.com +short. If it is not there, fix it now rather than waiting.

Verifying does not move mail; MX does

Adding and verifying the domain changes nothing for current mail. Mail moves only when you change the MX records (Google uses smtp.google.com, priority 1). Create the users and plan the data migration first, then follow change MX records on cutover day.

Check it worked

How to confirm it worked

  • In Admin console > Account > Domains > Manage domains, the domain is listed with the type you chose and shows as verified.

  • For a user alias domain, open a user in Directory > Users: they now have an alias at the new domain. Google says if mail to an alias does not arrive within 48 to 72 hours, check verification and MX records with your domain host.

  • nslookup -type=txt fabrikam.com still returns the google-site-verification value. Google says the record must stay in place until Google detects it.

Undo

How to reverse it

Rollback:

Go to Account > Domains > Manage domains, find the domain, select Remove and then Remove Domain. For a secondary domain you must first delete its groups, remove email aliases that use it, rename users on it, and remove linked alias domains. Google warns users stop receiving email at the domain and any sites built in that domain are permanently deleted. You can usually re-add the domain within 30 minutes, but large domains can take up to 24 hours.

Troubleshooting

Errors you might see

Your domain couldn't be verified

Cause: Google could not find the TXT record yet, or it was entered incorrectly.

Fix: Check the value with nslookup or dig, fix any typo, and wait up to 72 hours before confirming again.

Error when adding a domain that contains "gmail"

Cause: Google rejects domain names that contain gmail.

Fix: Use a different domain name.

Add a domain option is missing

Cause: Google notes the option is not available on the legacy free edition.

Fix: Upgrade to a current Google Workspace edition, or use a separate account.

Domain was recently removed and cannot be added

Cause: Google says you may need to wait up to 24 hours after removing a domain before adding it again.

Fix: Wait, then try again.

FAQ

Questions

What is the difference between a secondary domain and an alias domain?

A secondary domain holds its own users and mailboxes, each needing a licence. A user alias domain gives all existing users an extra address at the domain without extra licences.

How many domains can I add?

Google allows up to 599 secondary domains and up to 20 user alias domains.

Can I remove the TXT verification record after verification?

Google says the record must stay until Google detects it and verifies ownership. Leaving it in place does no harm.

Can a secondary domain become my primary domain later?

Yes. Google says you can switch a secondary domain to be the primary domain.

Sources

Official sources

Vendors change menus and requirements. Confirm on the source before you rely on a detail. Last checked 4 Nov 2026.

Google Workspace Help: Add a user alias domain or secondary domainGoogle Workspace Help: Verify your domain with a TXT recordGoogle Workspace Help: Remove a domain from your managed Google AccountGoogle Workspace Help: Set up MX records for Google Workspace