Setting Up Ses Domain Identity

This file owns the whole DNS and identity leg of SES domain setup. It assumes the sending domain is not yet fully set up in this Region, and it is finished when SKILL.md’s domain-setup-complete gate passes.

Rules this file owns:

• MUST ask which MAIL FROM subdomain to use; suggest one, never default it (Step 4).
• MUST publish DMARC p=none or stronger, and preserve a stronger existing policy (Step 5).
• MUST build each DKIM value as {token}.{SIGNING_HOSTED_ZONE} from the API response (Step 6).
• MUST read DkimAttributes.SigningAttributesOrigin before any Easy DKIM handling (Step 2), and stop at the DKIM leg on any value other than AWS_SES — this file configures Easy DKIM only.
• MUST present one batch containing only records absent or incorrect this run (Step 6).
• MUST NOT use Route 53 UPSERT or DELETE. CREATE only.
• SHOULD detect whether Route 53 hosts the domain and offer to create records there. MUST get permission before writing, after showing the zone, each record, TTL, conflicts, and no-overwrite or no-delete behavior.
• SHOULD NOT present SES’s documented 72-hour DNS search limit as the expected wait.

Required IAM actions

Apply SKILL.md’s IAM scoping, and grant only the actions the path actually taken reaches — a request that stops at reading state needs none of the writes. On the full journey the caller also needs onboarding.md‘s list, because that file owns the account and send legs.

Scope SES identity actions to arn:aws:ses:{region}:{account-id}:identity/{domain}.

Route 53 splits into reads and one write. The reads — route53:ListHostedZonesByName, route53:GetHostedZone, route53:ListResourceRecordSets — are needed whenever the agent checks whether Route 53 hosts the domain, so grant them for that check alone. Add route53:TestDNSAnswer only for Step 1’s narrow lookup fallback, and route53:ChangeResourceRecordSets only after the user has approved a write. Scope them per SKILL.md, using the bare zone ID; ListHostedZonesByName and TestDNSAnswer require Resource: *.

Parameters

Entry from onboarding.md: reuse its DOMAIN, REGION, MAIL_FROM and PROFILE. Do not ask again.

Direct invocation: run aws sts get-caller-identity before collecting any inputs. If it fails, explain how to refresh credentials and ask which account and Region to use once they are back. Resolve the Region by SKILL.md’s precedence chain — a Region the user named, AWS_REGION, AWS_DEFAULT_REGION, then aws configure get region with --profile '{profile}' when the user named a profile; that last command reads the CLI configuration files and not the environment, which is why the two environment variables come first. Only if none of them yields a value, ask for it in the same message as the other missing inputs. Ask once for the remaining scope, never for a profile or Region that resolved, and state the Region before any mutation.

The user chooses domain and mail_from_subdomain; never derive either. Do not ask about behavior_on_mx_failure during normal setup. Validate and single-quote every substituted value per SKILL.md.

Carry these values forward:

Step 1: Verify Prerequisites

Confirm AWS CLI v2 is configured, that the Region supports SES, and that dig is available — it ships in bind-utils or dnsutils. If dig is absent, use nslookup -type=CNAME|MX|TXT '{name}' wherever dig appears below, dropping +short and reading the answer section instead.

If neither tool exists, do not skip or guess: ask the user to run the lookup or check the record at their DNS provider and report back. For a known Route 53 public zone, aws route53 test-dns-answer (which needs route53:TestDNSAnswer) covers record read-back only — it proves nothing about public propagation, returns no subdomain name servers, and does not work with private zones, so those still need the user’s result.

Stop and surface SendingEnabled: false or EnforcementStatus: PROBATION|SHUTDOWN; this workflow fixes neither. onboarding.md Step 1 owns ProductionAccessEnabled, Details.ReviewDetails.Status, SendQuota and their routing — do not repeat those reads. On direct invocation, read that step before finishing, because ProductionAccessEnabled: false restricts recipients even after domain verification.

Step 2: Check Existing Identity State

Read before you create — creating over an existing identity returns AlreadyExistsException:

If NotFoundException → the identity does not exist. This is the only route into Step 3.

If identity exists → skip Step 3 and add only what’s missing.

First, before any DKIM status handling, read DkimAttributes.SigningAttributesOrigin into DKIM_ORIGIN. This gate comes before the status branches: the whole Easy DKIM flow — the three DKIM CNAMEs and put-email-identity-dkim-signing-attributes — is wrong for an identity whose DKIM is managed elsewhere, whatever the status says.

• DKIM_ORIGIN is exactly AWS_SES, or absent → Easy DKIM. Continue with the status branches below.
• Any other value → this identity’s DKIM is outside the scope of this onboarding. Leave DKIM entirely alone. Do not present the three DKIM CNAMEs, do not put them in RECORDS_NEEDED, and do not call put-email-identity-dkim-signing-attributes. EXTERNAL means the customer manages their own signing keys, which SES calls BYODKIM. An AWS_SES_<REGION> value means this identity is a replica whose DKIM is managed from another Region, so there is no DNS or DKIM change to make here either. Tell the user which of the two you read and that this workflow neither configures nor troubleshoots it, then split on DkimAttributes.Status:
  • SUCCESS → the DKIM leg is already satisfied. Continue with custom MAIL FROM (Step 4) and DMARC (Step 5) only.
  • Anything else → the domain-setup-complete gate cannot pass from here. Report that DKIM has to be resolved outside this workflow, name DkimAttributes.Status as the outstanding field, and stop. The full journey stops with it, because its send prerequisite needs SUCCESS.

With DKIM_ORIGIN cleared, branch on DkimAttributes.Status:

Re-initialising signing — the one call the FAILED and NOT_STARTED rows use. The origin gate above has already been applied, so reaching here means the origin is absent or exactly AWS_SES:

Gate on status, not on whether the records resolve — never run it on a SUCCESS identity, because re-initialising can change its tokens. The response returns DkimStatus, DkimTokens and SigningHostedZone: bind DKIM_TOKENS and SIGNING_HOSTED_ZONE from it, or re-read the identity. Compare those against what is published, put only the records that differ into RECORDS_NEEDED, and do not tell the user their DKIM records were rotated unless the values changed.

Then branch on MailFromAttributes:

The DMARC check is not in this branch — it lives in Step 5 and runs on every path through this file.

Step 3: Create Domain Identity with DKIM

Run this only after Step 2 returns NotFoundException. Existing identities, including NOT_STARTED, stay in Step 2.

This creates an Easy DKIM identity whose signing keys are SES-managed 2048-bit RSA keys. Bind DKIM_TOKENS from DkimAttributes.Tokens and SIGNING_HOSTED_ZONE from DkimAttributes.SigningHostedZone, re-reading the identity if either is absent from this response. Re-query once DNS has propagated; there is no API that forces a re-check. If a published record does not resolve, use “Troubleshooting: DKIM Stuck in PENDING”.

Step 4: Configure Custom MAIL FROM

Use the collected mail_from_subdomain. If missing, ask:

What subdomain would you like for MAIL FROM? Common choices are mail.{domain} or bounce.{domain}. It appears in the Return-Path and enables SPF alignment.

Validate that the answer is at least one label below {domain}. SES rejects the apex, because MAIL FROM must be a subdomain of {domain} — the domain being verified as this identity. If the user answers with the apex, explain that and re-ask; never quietly substitute one of the suggestions. Left unvalidated, the call returns BadRequestException (HTTP 400), which is invalid input rather than a permissions or service failure.

Preserve the identity’s current BehaviorOnMxFailure on every re-setup, including Step 2’s FAILED restart and subdomain-change paths, per the Parameters table. MAIL FROM configuration does not wait for DKIM verification.

SES requires exactly one MX record on the MAIL FROM subdomain (Using a custom MAIL FROM domain (opens in a new tab)). Check with dig MX '{mail_from_subdomain}' +short. An existing MX takes the same show-user, user-removal path as an existing TXT — never a silent omission. Show each MX record found and explain that SES needs only its own MX at this name. Removing MX can break inbound mail, so get explicit confirmation for each removal; the user performs removals themselves, because this skill issues no DELETE or UPSERT. If they decline, or the name receives mail, have them move MAIL FROM to a different empty subdomain and re-run Step 4 with that name. CREATE the SES MX only once nothing else answers there, and wait for status only after exactly the SES MX remains.

If the MX cannot be published at all, offer the documented USE_DEFAULT_VALUE fallback only after disclosing its effect, and repeat the command with it only on explicit agreement. That is the allowed repeat while status is PENDING or TEMPORARY_FAILURE, because it changes fallback behavior rather than forcing detection.

The fallback does not complete domain setup — never report it as complete. MailFromDomainStatus stays unresolved, so SKILL.md’s gate does not pass. Report setup as incomplete, name MailFromDomainStatus as outstanding, and state the consequences: the envelope sender is a subdomain of amazonses.com, so SPF passes without aligning to {domain}, DMARC can pass only on its DKIM leg, and the Return-Path recipients see is not at {domain}. A domain-setup-only request stops there. On the full journey it is not a dead end — onboarding.md‘s send prerequisite permits a send with USE_DEFAULT_VALUE and owns that decision — so return there rather than declaring the domain done.

Step 5: Build DMARC Record

Check for an existing DMARC record first — on every path, whether the identity was just created in Step 3 or already existed at Step 2, because a domain can carry a DMARC record long before SES:

Normalise the answer one resource record at a time. dig TXT +short prints one line per TXT resource record, and a long record appears within a line as several quoted character-strings. Strip the quotes and concatenate within a single line only — never across lines: joining two lines invents a record that does not exist and can make two broken records look valid. Test each line independently:

• No line begins v=DMARC1 → no effective DMARC policy. If some other TXT record sits on _dmarc, say it is not a policy record and receivers will not evaluate it as one. Build the record below.
• More than one line begins v=DMARC1 → invalid, and a blocking user action before Step 6. Receivers have no single policy to apply. Show every record found, in full, say that exactly one may exist, and have the user decide which to keep and remove the others; this file issues no DELETE, so the removal is their own action. Do not put a p=none record into RECORDS_NEEDED — a further record deepens the ambiguity, and which policy survives is the user’s choice. If any record found is valid with p=quarantine or p=reject, never propose the weaker policy: what remains must be the stronger one. Continue to Step 6 only after the user confirms exactly one effective policy is left, then re-run this check and follow whichever single-record branch it lands on.
• Exactly one line begins v=DMARC1 → read it back. Skip creating a record only when it is valid: exactly one p= tag whose value is none, quarantine or reject. No p= tag, more than one, or an unrecognised value means the policy is unusable — warn, say which it is, and treat the existing record as the value the user replaces.
• An existing valid p=quarantine or p=reject → preserve it. Never downgrade to p=none. It is stronger than what this file would create, and lowering it silently weakens the domain. Say it is in force now, while the DKIM and MAIL FROM records are still propagating, so mail failing alignment meanwhile may be quarantined or rejected rather than merely reported — and that changing it is the user’s decision.
• It sets aspf=s → the custom MAIL FROM subdomain will not align with a From at {domain}, so DMARC’s SPF leg fails even though SPF passes; DKIM alignment is then the only leg that can pass.

A per-line string test is enough; do not build a DMARC parser. Both DNS paths in Step 6 follow this result, and the DMARC record enters RECORDS_NEEDED only when the check found no v=DMARC1 line at all, or found exactly one that is not valid — never while more than one exists, which is the blocking branch above.

When a record is needed, construct the DMARC TXT record for _dmarc.{domain}:

Start at p=none to monitor, progress to p=quarantine once DKIM and SPF alignment pass consistently, and to p=reject when quarantine shows no legitimate mail failing. A domain left at p=none indefinitely has no spoofing protection.

What DMARC requires, and what this file chooses. AWS documents that “a message passes DMARC if one or both of the described SPF or DKIM checks pass” — one aligned mechanism is enough. This file sets up both anyway, so forwarded mail (which breaks SPF) still authenticates on DKIM. That is this file’s choice, not a DMARC requirement: never tell the user DKIM alignment is mandatory and SPF optional. The record omits aspf deliberately, because AWS documents SPF alignment as requiring the policy not to specify aspf=s.

No aggregate reports arrive from that record — no rua= tag. Judge progression either by adding a rua=mailto: tag naming an address the user picks and accepts exposing in public DNS, or from the Authentication-Results header of test mail received; say which.

Step 6: Present ALL DNS Records Together

Present RECORDS_NEEDED as a single batch — never one record at a time, and never a record the user already has. Omit the DKIM CNAMEs when DKIM is SUCCESS with unchanged tokens, and omit all three whenever Step 2’s origin gate read a DKIM_ORIGIN other than AWS_SES; omit the MAIL FROM MX and TXT when MAIL FROM is already SUCCESS on the chosen subdomain; omit DMARC when Step 5 found exactly one valid record, or found more than one v=DMARC1 record — a blocking user action reached before this step, not a record to add. If RECORDS_NEEDED is empty, say the DNS side is complete and go to Step 7.

Build each DKIM record value as {token}.{SIGNING_HOSTED_ZONE} from the values read in Step 2 or Step 3 — never from a remembered literal. AWS documents this construction and states that the hosted-zone portion varies by AWS Region and cell (Creating and verifying identities (opens in a new tab)). If SIGNING_HOSTED_ZONE is missing, re-read the identity.

Check for an existing TXT record on {mail_from_subdomain} before publishing the SPF record — on both paths below, Route 53 and external provider alike:

Normalise one resource record at a time, exactly as Step 5’s DMARC check does. Pick the line beginning v=spf1; any other TXT record on the name is unrelated and left alone. Then:

• Nothing published → add the SES SPF record as shown above.
• An unrelated TXT record (a verification token, say) → the two may coexist, because the one-record rule applies to SPF records specifically. The existing value must still be preserved.
• Another record starting with v=spf1 → merge it; never publish a second. Two SPF records on one name is a permerror, which fails SPF outright. Show the user the existing value and merge the mechanisms into one record by inserting include:amazonses.com immediately before the terminal all mechanism (~all, -all or ?all) — evaluation stops at all, so a mechanism after it is unreachable. If include:amazonses.com is already present, no change is needed.

In Route 53, every TXT value for one name lives in a single record set, so CREATE cannot add a value to a name that already has one. A merge — and equally, keeping an unrelated TXT value alongside the SES one — is therefore the user’s action: present the complete updated value list, have them confirm it, and have them apply it. Never publish only the SES record on a name that already carries a TXT value; that drops what was there.

Determine whether Route 53 hosts the domain (steps below); if no authoritative zone is found, use the external DNS provider path:

1. Find the zone: aws route53 list-hosted-zones-by-name --dns-name '{domain}'

   Pick the zone explicitly — never the first result. This call returns zones from that name onward in lexical order, so it can include neighbouring domains and private zones, and one domain can have more than one zone. Take only the entry whose Name is exactly {domain}. and whose Config.PrivateZone is false. Normalise its Id before storing it as {hosted_zone_id}: strip the /hostedzone/ prefix and keep the bare Z123ABC, which CLI flags and the IAM ARN both assume. If more than one entry matches, stop and ask.

   If no entry matches {domain}. exactly, walk up to the parent before concluding Route 53 cannot host the records. A sending domain is often a subdomain whose records live in an ancestor’s zone: strip the leftmost label to get {parent} and search again (list-hosted-zones-by-name --dns-name '{parent}'), applying the same exact-name, public-zone rule at each level until a zone matches or no labels remain. Record the matched zone’s Name as {zone_name} — every later delegation and authority check queries that name, not {domain}. Records for {domain} live in that zone as fully-qualified names.

   If the walk matched an ancestor, check it has not delegated the branch away before writing anything into it — records placed in a parent for a delegated name are never served. Either of these is a STOP:

   • In the list-resource-record-sets read below, an NS record set whose Name is {domain}. or any intermediate label between {zone_name} and {domain} — with {domain} = mail.sub.example.com and {zone_name} = example.com, an NS set on sub.example.com. counts. Ignore the NS set on {zone_name}. itself; that is the zone’s own delegation.
   • dig NS '{domain}' +short returning name servers that differ from the found zone’s DelegationSet.NameServers. Empty output is not a STOP — a subdomain with no zone of its own has no NS record, the normal case this walk serves.

   On either signal, do not write to the ancestor zone. If the delegated child zone is in this account, find it under the same exact-name, public-zone rule and use it; otherwise use the external DNS provider path below.

   MUST NOT create a hosted zone — out of scope. A child zone does not resolve until the parent publishes NS delegation for it, it adds a monthly charge, and an undelegated parent zone can carry the records directly. Say all of that, and if the user wants separately delegated management have them create the zone and publish its delegation themselves, then return here. Never call route53:CreateHostedZone: it is deliberately absent from this file’s Required IAM actions.

2. Verify the zone is authoritative — its delegated name servers must match what public DNS answers:

   bashCopy

   aws route53 get-hosted-zone --id '{hosted_zone_id}' --query 'DelegationSet.NameServers'
   dig NS '{zone_name}' +short   # the found zone's own name — an ancestor, not '{domain}', when the walk matched one

   A null or empty DelegationSet.NameServers means the zone is not authoritative for public DNS — what a private hosted zone returns — not that the command produced no output. Treat it as not authoritative and use the external-provider path.

3. If they do not match, do not write to the zone. Records added there will not resolve and SES will never detect them. Say which name servers the domain actually delegates to, and use the external DNS provider path below.

4. Read what already exists before building the batch:

   bashCopy

   aws route53 list-resource-record-sets --hosted-zone-id '{hosted_zone_id}'

   Apply step 1’s delegation check to this output first: an NS record set whose Name is {domain}. or an intermediate label below {zone_name} is a STOP, not a record to skip over. Otherwise include only absent records — the change batch is transactional (“either makes all or none of the changes”), so one already-existing record set fails every other change in the request. For any record that exists with a different value, show the user that value and what SES needs, and let them decide. Two collisions must never be silently omitted, because omitting them leaves the SES record unpublished: a TXT set on {mail_from_subdomain} goes to the merge rule above, and an MX set on {mail_from_subdomain} goes to Step 4’s MX rule.

5. MUST ask for explicit permission before creating DNS records — and show the whole change first. Route 53 mutations can affect live traffic. Present all of this before asking:

   • the zone: {zone_name} and {hosted_zone_id};
   • every record to be created, each with its name, type, value and TTL — the TTL is part of the change batch, so disclosing it for every record is what makes the consent informed, and a user who wants a different TTL has to say so before the write;
   • any conflict the list-resource-record-sets read found, and what happens to it (left alone and taken to the show-user path, not overwritten);
   • the confirmation that nothing existing is overwritten or deleted.

   Then ask in these terms, and proceed only on an explicit yes:

   I’ll add these records to {zone_name} ({hosted_zone_id}) as new records only, each with the TTL shown above — this CREATEs them and replaces or deletes nothing already in the zone. Go ahead?

   If the user declines, use the external DNS provider path below.

6. If permission is granted, write the absent records with an explicit CREATE action in one call. Never use UPSERT: AWS documents it as updating a record set that already exists with the request’s values, so it silently replaces a live record. This file issues no UPSERT and no DELETE. Pass the change batch inline — file:// is AWS-CLI-specific and does not resolve through the AWS MCP server:

   bashCopy

   aws route53 change-resource-record-sets \
     --hosted-zone-id '{hosted_zone_id}' \
     --change-batch '{
       "Comment": "Amazon SES domain authentication records",
       "Changes": [
         {"Action": "CREATE", "ResourceRecordSet": {
           "Name": "{DKIM_TOKENS[0]}._domainkey.{domain}", "Type": "CNAME", "TTL": 1800,
           "ResourceRecords": [{"Value": "{DKIM_TOKENS[0]}.{SIGNING_HOSTED_ZONE}"}]}},
   
   
   
   
   
   
   
   

If external DNS provider:

• Present the records in RECORDS_NEEDED — only those, each with name, type, value and the TTL to set — and have the user add them at their provider, applying the same omissions as the Route 53 path.
• Apply the SPF-collision check above before the SPF TXT record is added: the user publishes the merged value rather than a second record. Apply Step 4’s MX rule the same way — another MX on the MAIL FROM name is removed, or MAIL FROM moves to another empty subdomain, before the SES MX is added.
• Apply Step 5’s DMARC result the same way: a valid record means do not ask for another; more than one v=DMARC1 record is the blocking branch, so the extras come down to one effective policy first.
• Warn about provider quirks: some append the domain automatically, so {token}._domainkey becomes {token}._domainkey.example.com.example.com.
• Once the user confirms the records are live, go to Step 7.

Step 7: Verify DNS Propagation

After the user confirms the records are added:

Then confirm SES has picked up the changes:

Domain setup is complete only when all three fields in SKILL.md’s domain-setup-complete gate are true in this one response. Report which are outstanding rather than reporting “verified” on two.

Troubleshooting: DKIM Stuck in PENDING

If DKIM remains PENDING after the records are added:

1. Get the expected values from the API, not from memory:

   bashCopy

   aws sesv2 get-email-identity --email-identity '{domain}' --region '{region}' \
     --query 'DkimAttributes.{tokens:Tokens, zone:SigningHostedZone}'

2. Check that all three CNAMEs resolve — Step 7’s three dig CNAME lookups. All three must resolve before the status can reach SUCCESS. Expected value: {token}.{SIGNING_HOSTED_ZONE}, built from the zone read in this session, never a literal remembered from another Region or account.

3. Common causes:

   • Value built from the wrong signing zone (a remembered literal, not this identity’s SigningHostedZone)
   • DNS provider appended the domain (record is {token}._domainkey.example.com.example.com)
   • Records in a zone that exists but isn’t authoritative — re-run Step 6’s authority check, querying {zone_name}, not {domain}; if the name servers differ, add the records at the authoritative provider
   • Wildcard CNAME conflict overriding the specific DKIM record, or TTL propagation delay
   • More than one MX record on the MAIL FROM subdomain — does not affect DKIM, but blocks the MAIL FROM half of the gate

4. If the records are correct but SES still shows PENDING: there is no API to force re-verification; SES will find them on its own. The SESv2 API reference documents SES searching the domain’s DNS configuration “for up to 72 hours” (DkimAttributes (opens in a new tab)) — the outer bound of the search, not the expected wait. Re-query after DNS propagates.

Security Considerations

Apply SKILL.md’s IAM, credential, CloudTrail and value-validation rules; the consent gate for any DNS write is owned by Step 6 and must not be bypassed. When a domain identity is deleted or its DKIM keys are rotated, tell the user to remove the DKIM CNAMEs the retired tokens point at: a CNAME left pointing at a target nobody owns any more is a dangling-DNS record, the same class of exposure as a subdomain takeover. Large mailbox providers publish their own authentication requirements for bulk senders, DMARC among them — check each provider’s current requirements rather than assuming a threshold.

Next: what happens after the domain is set up

This depends on what the user asked for — check the requested scope first.

• Domain setup only (the common direct-invocation case: “set up my domain”, “fix my DKIM”) → report the gate result as it stands, naming all three gate fields, and stop. Say “complete” only when all three are true in one response; otherwise say it is incomplete and name the outstanding field. Step 4’s USE_DEFAULT_VALUE fallback ends here incomplete, and so does an identity whose DKIM is out of scope per Step 2’s origin gate and not already SUCCESS. Do not raise production access, do not offer a test send, and do not route into onboarding.md: neither was asked for, and one opens an AWS Support case while the other sends real mail. Say in one line that both are available when they want them.
• The user asked for the full journey, production access, or a first/test send → a verified domain is not yet a delivered email. Return to onboarding.md carrying region and domain; it re-reads identity state with get-email-identity rather than relying on values carried back, so hand back no DKIM tokens or signing zone. Report the gate result as it stands, and when Step 2’s origin gate read a DKIM_ORIGIN other than AWS_SES, report that origin and DkimAttributes.Status with it.

If the scope is ambiguous, ask one question rather than assuming the larger one.

Repeat the CNAME entry for DKIM_TOKENS[1] and DKIM_TOKENS[2], and add _dmarc.{domain} as a TXT entry unless Step 5’s DMARC check found exactly one valid existing record, or found more than one v=DMARC1 record — that is its blocking branch, where the extras come down to one effective policy before any record is added here. Up to six records, but only those in RECORDS_NEEDED that the list-resource-record-sets read showed absent: the batch is all-or-nothing, so one already-present record fails every change with InvalidChangeBatch, whose response carries one error message per failed change — read them to see which record collided. An existing but invalid _dmarc record is not omitted by that rule: like an existing TXT on the MAIL FROM name it takes the show-user path, where Step 5’s record is the replacement value. Two shapes matter: TXT values keep their own enclosing double quotes inside Value, escaped as shown, and the MX priority 10 is part of the value string. TTL is the caller’s choice; 1800 is an example, and whatever is used must be what the consent step disclosed.