# Agent file: set up business email on Google Workspace This file is written for an AI coding agent working in a repository with its owner present. Follow the steps in order and run the check at the end of each step before starting the next. It is complete without the guide it accompanies. Every fact about Google Workspace here was checked against the pages under Sources on October 11, 2026. Commands, flags and dashboard labels change. If one fails, read the linked page before trying again. Do not guess. This setup is mostly done by a human in two web consoles. Your part is the reading and the checking: look up what the domain publishes, write out the exact records to add, and verify each one with `dig` after the human says it is published. You never sign in to the Google Admin console or the DNS host, and you never change a DNS record. In every command and record below, replace `example.com` with the domain the human gives you. ## Goal Mail for the domain is delivered to Google Workspace. The domain publishes one MX setup that points at Google, one SPF record, a DKIM key that Google is signing with, and a DMARC record that starts at `p=none`. The role addresses the human wants exist as aliases or groups. The administrator account has 2-Step Verification on. ## Preconditions Check each one before preparing any record. If one is false, stop and report it. - The human has told you the exact domain. Do not infer it from the repository. - `dig` is available: `dig -v` prints a version. If it is missing, ask the human to run the lookups in Google Admin Toolbox Dig and paste the answers. - You know where the DNS is hosted. Run the first command in step 1 and report the nameservers. Records are added there, which is not always the registrar. - You know whether the domain already receives mail. If the MX lookup in step 1 returns another provider, say so plainly: changing MX records moves all incoming mail, and the human has to plan that switch. - The human has confirmed whether anything else sends mail as this domain (a newsletter tool, an app, a help desk). Each one changes the SPF record in step 4. ## Environment variables None. This setup stores nothing in the repository and needs no key, token or secret. If the repository has a DNS provider token in its environment, do not use it for this work. DNS changes here are made by the human. Values to get from the human, by name: | Value | Notes | | --- | --- | | Domain | The domain mail will be received on. | | Verification value | Starts with `google-site-verification=`. It is not a secret, but it is unique to the account, so use the one the human pastes. | | DKIM host name and value | Both are shown in the Admin console after the human generates the record. The value is a public key and is safe to paste. | | Report address | The mailbox or group that will receive DMARC reports, for the `rua` tag. | | Role addresses | The aliases or groups wanted, such as `hello`, `billing` and `support`, and who should receive each. | ## Stop and ask the human - Any secret value. Ask for the variable to be set by the human. Never print, log, commit or echo a secret, and never ask for one to be pasted into the conversation. - Any sign-in, account creation, plan choice or payment method. - Anything that deletes data or cannot be undone. - Signing up for Google Workspace, choosing an edition, starting a trial or entering billing details. - Every step in the Google Admin console: verifying the domain, Activate Gmail, creating users, aliases and groups, Generate New Record and Start authentication for DKIM, and 2-Step Verification settings. - Creating, changing or deleting any DNS record. Show the exact record and wait. This holds even if you have a working token for the DNS host. - Removing existing MX records. List what is published and what Google documents, and let the human decide when to switch. - Replacing a working legacy MX set (values that start with `aspmx`). Google documents those as still supported, with no change required when mail is working. - Moving DMARC from `p=none` to `quarantine` or `reject`. That decision needs someone to have read the reports. - 2-Step Verification enrollment, backup codes and recovery options. Never ask for a verification code or a backup code to be pasted into the conversation. ## Steps ### 1. Read what the domain publishes now ```bash dig +short NS example.com # who hosts the DNS dig +short MX example.com # where mail is delivered today dig +short TXT example.com # SPF and verification records dig +short TXT google._domainkey.example.com # DKIM at Google's default selector dig +short TXT _dmarc.example.com # DMARC; no output means no record ``` Report each answer in a short table: record, current value, and whether it matches what the later steps expect. No output from a lookup means no record. Check: you can name the DNS host, the current mail provider (or none), and which of SPF, DKIM and DMARC already exist. ### 2. Prepare the domain verification record The human signs up and opens the setup tool. Google requires the domain to be verified within the first 9 days of a trial, and deletes an unverified account within 21 days of sign-up unless billing is set up. In the setup tool the human copies the Value, which starts with `google-site-verification=`. Give them this record with their value in place. The name is blank or `@`. ```bash # Type Name Value (copy yours from the setup tool) TXT @ google-site-verification=YOUR_UNIQUE_VALUE ``` After they add it, they select Come back here and confirm, then click Confirm. Google says the record can take up to 72 hours to be recognized. Once Google has verified the domain, the record can be safely removed. Check: `dig +short TXT example.com` returns a line that starts with `"google-site-verification=`, and the human confirms the Admin console shows the domain as verified. ### 3. Prepare the MX record Confirm with the human that a user account exists for each person who will receive mail. Google lists creating user accounts before the MX change. For a new setup Google documents one record: ```bash # Type Name Priority Value MX @ 1 smtp.google.com ``` Some DNS hosts require a trailing period on the value (`smtp.google.com.`). Google says to remove any other MX records. List the existing ones from step 1 and ask before the human removes them. If step 1 returned the older Google set below, do not propose a change. Google documents that domains that started before 2023 might have values that start with `aspmx`, that these are still supported, and that no change is required when mail is working. ```bash # Type Name Priority Value MX @ 1 aspmx.l.google.com MX @ 5 alt1.aspmx.l.google.com MX @ 5 alt2.aspmx.l.google.com MX @ 10 alt3.aspmx.l.google.com MX @ 10 alt4.aspmx.l.google.com ``` Never mix the two sets, and never leave another provider's MX records next to Google's. After the record is saved, the human clicks Activate Gmail for the domain in the Admin console under Account, Domains, Manage domains. Allow up to 72 hours. Check: `dig +short MX example.com` returns `1 smtp.google.com.` and nothing else, or the complete legacy set and nothing else. ### 4. Prepare the SPF record For a domain that sends only through Google Workspace, Google gives this exact record: ```bash # Type Name Value TXT @ v=spf1 include:_spf.google.com ~all ``` A domain can have only one SPF record. If step 1 found one, propose an edit to it and do not add a second. If another service sends as this domain, its `include:` goes in the same record, before `~all`. Take the value from that service's own documentation or from the table on Google's SPF page. Do not guess an include. Google recommends `~all`. Check: `dig +short TXT example.com` returns exactly one line that starts with `"v=spf1` and it contains `include:_spf.google.com`. SPF can take up to 48 hours to start working. ### 5. Prepare the DKIM record You cannot generate this one. The human does, in the Admin console under Apps, Google Workspace, Gmail, Authenticate email, with Generate New Record. Tell them three things first: Google says to wait 24 to 72 hours after Gmail is turned on before generating the key, to choose 2048 bits if the DNS host supports it, and to keep the default prefix selector `google` unless the domain already uses it. They copy two fields, the DNS host name and the TXT record value. The record has this shape: ```bash # Type Name Value (copy both fields from the Admin console) TXT google._domainkey v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY ``` After the record is published, the human returns to the same page and clicks Start authentication. Remind them. Publishing the record does not start signing. Check: `dig +short TXT google._domainkey.example.com` returns a value that starts with `"v=DKIM1`, and the human confirms the page status reads Authenticating email with DKIM. Google allows up to 48 hours. If another selector was chosen, use it in place of `google`. ### 6. Prepare the DMARC record Run `dig +short TXT _dmarc.example.com` first. An empty answer is common, including on domains that already have SPF and DKIM. Google sets two conditions: SPF or DKIM must be on, and 48 hours should pass after setting them up. Ask the human for the report address. Google recommends a group or a dedicated mailbox and advises against a personal address, because reports arrive daily. The address should be on the same domain. Start at `p=none`: ```bash # Type Name Value # Some DNS hosts want the full name, _dmarc.example.com TXT _dmarc v=DMARC1; p=none; rua=mailto:dmarc@example.com ``` The `v` and `p` tags come first. Some DNS hosts add the domain to the name automatically and some want the full `_dmarc.example.com`. Ask which form their host uses, or check the result with the lookup. Do not propose a stricter policy during setup. Record these as the later moves for the human, to be made after the reports show that all legitimate mail passes: ```bash # Next: failing mail goes to the recipient's spam folder TXT _dmarc v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com # Last: failing mail is rejected TXT _dmarc v=DMARC1; p=reject; rua=mailto:dmarc@example.com ``` Check: `dig +short TXT _dmarc.example.com` returns one line that starts with `"v=DMARC1; p=none`. ### 7. List the aliases and groups for the human to create Write a short list from the role addresses the human named. One recipient: an alias. Several recipients: a group. - Alias: Admin console, Directory, Users, open the user, Add Alternate Emails. Google allows up to 30 aliases for each user at no extra cost, and says changes can take up to 24 hours. To send from the alias, the user adds it in Gmail under Settings, See all settings, Accounts, Send mail as, Add another email address. - Group: Admin console, Directory, Groups, Create group. A group that should receive mail from customers has to allow posts from the External category in its access settings. - If the DMARC report address from step 6 does not exist yet, it belongs on this list. Check: the human sends a message from an outside account to each address and confirms each one arrives. ### 8. Hand over the administrator security list Do not do these. Give them to the human: - Turn on 2-Step Verification for the administrator account: Google Account, Security and sign-in, Turn on 2-Step Verification. Google states that it is enforcing 2-Step Verification for administrator accounts. - Prefer a security key. Google describes security keys as the most secure form of 2-Step Verification. - Save backup codes in a safe place ahead of time, and add a recovery phone number and email address to the administrator account. - For other users: Admin console, Security, Authentication, 2-step verification, Allow users to turn on 2-Step Verification, then choose an Enforcement option. - Google recommends not using a super admin account for daily activities. Check: the human confirms 2-Step Verification is on for the administrator account. Do not ask how, and do not ask for any code. ### 9. Verify everything ```bash dig +short MX example.com # 1 smtp.google.com. dig +short TXT example.com # "v=spf1 include:_spf.google.com ~all" dig +short TXT google._domainkey.example.com # "v=DKIM1; k=rsa; p=..." dig +short TXT _dmarc.example.com # "v=DMARC1; p=none; rua=mailto:dmarc@example.com" ``` The comment under each command is the answer to expect on a new setup. Compare each real answer to it and report differences. If a lookup is empty soon after the human added a record, wait and run it again before suggesting a change. Then ask the human to send one message from the new mailbox to a Gmail address that is not their own, open it, click More next to Reply, then Show original, and read you the DKIM result in the Authentication-Results header. Google notes that DKIM cannot be verified by sending a message to yourself. Check: all four lookups match, and the DKIM result reads something like pass or OK. ## Done when - `dig +short MX` returns only Google's record or records. - `dig +short TXT` on the domain returns exactly one SPF record, and it includes `_spf.google.com`. - The DKIM lookup returns a key at the selector the human chose, and the Admin console reads Authenticating email with DKIM. - The DMARC lookup returns a record with `p=none` and a `rua` address that exists. - A message from outside reaches the main address and every alias and group. - A message sent from the new mailbox shows a passing DKIM result. - The human has confirmed 2-Step Verification on the administrator account. - You changed no DNS record and signed in to nothing. ## Sources - [Compare pricing plans](https://workspace.google.com/pricing) - [Verify your domain for Google Workspace](https://knowledge.workspace.google.com/admin/domains/verify-your-domain-for-google-workspace) - [Verify your domain with a TXT record](https://knowledge.workspace.google.com/admin/domains/verify-your-domain-with-a-txt-record) - [Activate Gmail with Google Workspace](https://knowledge.workspace.google.com/admin/gmail/activate-gmail-with-google-workspace-your-company) - [Set up MX records for Google Workspace](https://knowledge.workspace.google.com/admin/domains/set-up-mx-records-for-google-workspace) - [Set up SPF](https://knowledge.workspace.google.com/admin/security/set-up-spf) - [Troubleshoot SPF issues](https://knowledge.workspace.google.com/admin/security/troubleshoot-spf-issues) - [Set up DKIM](https://knowledge.workspace.google.com/admin/security/set-up-dkim) - [Set up DMARC](https://knowledge.workspace.google.com/admin/security/set-up-dmarc) - [Add or delete an alternate email address (email alias)](https://knowledge.workspace.google.com/admin/users/add-or-delete-an-alternate-email-address-email-alias) - [Send emails from a different address or alias](https://support.google.com/mail/answer/22370) - [Create a group in your organization](https://knowledge.workspace.google.com/admin/groups/create-a-group-in-your-organization) - [Deploy 2-Step Verification](https://knowledge.workspace.google.com/admin/security/deploy-2-step-verification) - [Turn on 2-Step Verification](https://support.google.com/accounts/answer/185839) - [Security best practices for administrator accounts](https://knowledge.workspace.google.com/admin/users/security-best-practices-for-administrator-accounts) - [Admin Toolbox Dig](https://toolbox.googleapps.com/apps/dig/)