Onboarding

Session state

Carry these forward between steps; re-read rather than assume.

If PROFILE is set, append --profile '{PROFILE}' to every command; all sesv2 commands also take --region '{REGION}'. Every substituted value is validated and single-quoted first.

Required IAM actions

This list covers only the actions this file calls. The domain-setup leg is owned by setting-up-ses-domain-identity.md, which has its own list; the full journey needs the union, because Step 2 hands the DNS and identity-creation work to that file. Scope as SKILL.md describes; never a wildcard.

• Read, always needed: sts:GetCallerIdentity, ses:GetAccount, ses:ListEmailIdentities, ses:GetEmailIdentity. Scope the ses:GetEmailIdentity statement to every identity this file reads, not only identity/{DOMAIN}: Step 4 reads identity/{CHOSEN_RECIPIENT} for option 1, and for option 3 the exact identity ARN of the other verified domain the user names. A policy scoped only to the sending domain denies those reads, and the failure looks like a missing recipient rather than a missing permission.

• Write, only for the scope actually being run. A read-only or domain-setup-only request needs none of the three writes below, though domain setup still needs the other file’s writes:

  • ses:PutAccountDetails — only when requesting production access (Step 3).
  • ses:SendEmail — only when a first or test send is in scope (Step 5).
  • ses:CreateEmailIdentity — two distinct scopes, and only one belongs here. Creating the domain identity is owned by setting-up-ses-domain-identity.md, scoped to identity/{DOMAIN}. What this file calls it for is narrower: verifying an individual address as a sandbox recipient (Step 4, option 1), scoped to identity/{CHOSEN_RECIPIENT}. A policy scoped only to the domain denies that call.

• Narrow ses:SendEmail so a confused or compromised caller cannot send as anyone from this domain. Scope the statement to the identity that authorizes {FROM_ADDRESS} — three cases: an address at {DOMAIN} (the default and common case) → identity/{DOMAIN}; an address verified as its own email identity → identity/{FROM_ADDRESS}; an address at a different verified domain → that domain’s identity ARN. Then pin the sender with the ses:FromAddress condition key:

  jsonCopy

  {
    "Effect": "Allow",
    "Action": "ses:SendEmail",
    "Resource": "arn:aws:ses:{REGION}:{ACCOUNT_ID}:identity/{DOMAIN}",
    "Condition": {"StringEquals": {"ses:FromAddress": "{FROM_ADDRESS}"}}
  }

  ses:FromAddress is an exact string match, so pin it to the {FROM_ADDRESS} collected for this workflow — pinned elsewhere it denies every send and reads like a broken permission.

How to run this: check, then do

Every step is check, then do: read current state first, and if a step is already satisfied say so in one line (✓ Domain already verified) and move on.

Precedence: identity state is evaluated before review state, and a Details.ReviewDetails row never overrides identity state. The table is ordered to match: account-state rows, then identity rows, then review rows. Two thresholds matter and differ: the full domain-setup-complete gate, which Step 3 requires, and the narrower send prerequisite stated in Step 2. Route to Step 2 before a send only when that prerequisite fails — read it in Step 2, not from a row.

Step 1: Preflight — one question set, then read state

Ask in ONE message, and ask only for what the request needs. Do not drip-feed questions; equally, do not block domain setup on inputs belonging to a later step. Never ask for anything already supplied, and never ask for the AWS CLI profile or Region — SKILL.md’s Critical Rules own both, including the two credential/Region cases where you do ask. Two ordering requirements here.

First, run aws sts get-caller-identity before composing the question set — credentials found dead afterwards throw the answers away and may have pointed at the wrong account. If it fails, say how to refresh them and ask, in the same message, which account (profile) and Region to use once back.

Second, resolve the Region by SKILL.md’s precedence chain before any aws sesv2 call — user-named, AWS_REGION, AWS_DEFAULT_REGION, then aws configure get region (profile-aware). If none yields a value, ask for one in the same question set. Bind it as REGION and state it before any mutation.

Scope the question set to the request:

The From address is never one of the questions. Default it to onboarding@{DOMAIN} — the bare address, with no display name — state it in the same message as the question set, and invite an override in the same breath. Bounce notices arrive there by default, so a real mailbox is worth having. Because it is stated rather than asked, the question set for the full journey carries three items.

Example, for the full journey:

To get you from nothing to a delivered email I need three things:

1. Sending domain — the domain you want mail to come from, e.g. example.com. You need to be able to add DNS records for it.
2. MAIL FROM subdomain — a subdomain used as the envelope sender, which is what makes SPF align. Common choices are mail.example.com or bounce.example.com; pick one.
3. Test recipient — an email address you can actually open, to receive the first message.

MUST NOT ask for mail type or website URL before Step 3 — not even when the user says they want production sending. Production access requires a verified domain first, so asking up front delays the identity creation that has to happen anyway.

If the user overrides the From address, check it against the sending domain. An override not at {DOMAIN} is held until the state read below — an address at another identity already verified in this Region is also legitimate. At no verified identity, say so and ask for one that is.

Then read state before doing anything:

From get-account read ProductionAccessEnabled, Details.ReviewDetails.Status, SendQuota.SentLast24Hours and SendQuota.MaxSendRate, and record CASE_ID and MAX_24_HOUR_SEND — read the account’s own limits here rather than asserting a figure later — then route with the table above. Two fields decide whether the journey can run at all: SendingEnabled: false means sending is switched off in this Region and no send will succeed; EnforcementStatus of PROBATION or SHUTDOWN means a reputation problem this workflow does not address (HEALTHY is the good value). Surface either and stop.

From list-email-identities, note whether {DOMAIN} is present. If it is, read it with get-email-identity before deciding anything — presence alone does not mean the gate passes.

Step 2: Verify the sending domain

Create a domain identity with Easy DKIM, add a custom MAIL FROM subdomain for SPF alignment, and publish a DMARC record — then present all DNS records in a single batch.

Do not run any create or put call from here, and do not improvise the record shapes. The whole procedure lives in setting-up-ses-domain-identity.md, which owns the entire DNS leg — including asking the user to add the records and confirm they are live, so do not ask for either a second time here. Follow it, then return carrying whatever its handoff produces.

SES detects the records on its own once they resolve; there is no API to force a re-check. Do not wait open-endedly: re-read the identity once the lookups resolve rather than polling on a timer, and if every record resolves publicly while the status has not moved, go to that file’s DKIM troubleshooting section.

Step 2 is complete when the domain-setup-complete gate in SKILL.md’s “Invariants” passes — all three of its fields true in one response:

The send prerequisite — stated here, and applied rather than redefined elsewhere. A send may proceed when the identity is verified for sending with DkimAttributes.Status: SUCCESS, and either MailFromAttributes.MailFromDomainStatus is SUCCESS or it is unresolved with BehaviorOnMxFailure set to USE_DEFAULT_VALUE. It may not proceed while MAIL FROM is unresolved and BehaviorOnMxFailure is REJECT_MESSAGE: AWS documents that SES then returns MailFromDomainNotVerified and does not attempt delivery. MailFromAttributes absent entirely → no custom MAIL FROM in effect, and this journey routes to Step 2 because custom MAIL FROM is a MUST here. In the USE_DEFAULT_VALUE case SES falls back to a subdomain of amazonses.com as the envelope sender — say plainly that it will not align with {DOMAIN} and DMARC must pass on DKIM alignment alone, then go to Step 5. Never report the domain as complete in either state.

Why DKIM SUCCESS is in that prerequisite when SES itself does not require it. Per SKILL.md’s sender invariant, the service minimum is a verified sender; this journey holds the higher bar because it promises a delivered, authenticated first email whose Authentication-Results shows dkim=pass. If the user explicitly wants to send sooner, say what they give up and never silently relax the prerequisite.

Scope gate — check the requested scope before going on to Step 3 or Step 5. A domain-setup-only request ends here: report the result, name any outstanding field, and stop. Do not prompt for production access and do not offer or perform a test send — neither was asked for, and Step 3 opens an AWS Support case while Step 5 sends real mail. Say in one line that both are available on request. Continue only when the request asked for production access, a send, or the full journey.

Step 3: Request production access

MUST confirm the domain-setup-complete gate passes before submitting. AWS documents that “verifying your domain with SES before requesting production access is a best practice that helps to get your production access request approved faster.” If the user asks to submit first, explain that and complete the domain first.

MUST get explicit consent before submitting. The console form makes the user tick an acknowledgement box; the API has no parameter for it, so submitting via the CLI makes that commitment on the user’s behalf. Say this in one paragraph and wait for a yes:

Submitting this tells AWS you will only send to people who asked for your mail, and that you have a way to handle bounces and complaints. It opens an AWS Support case, and AWS documents that you cannot edit your details until the review completes — there is no API to cancel or withdraw it. Shall I submit it? (You can also fill in the form yourself in the SES console.)

If the user declines, accept it and move on — do NOT re-propose it. Production access is not needed for a first delivered email. Say that plainly, set PA_DECLINED, skip the rest of Step 3 (do not collect MAIL_TYPE or WEBSITE_URL), and go to Step 4’s “Sandbox recipient options” to bind a permitted recipient, then Step 5 — the account is in the sandbox, so that binding is required before the send. Do not raise production access again this session unless the user brings it up.

Two inputs are required and collected here. Ask now if the request did not supply them — never invent either. Explain each in one line, because the user is choosing:

• MAIL_TYPE — TRANSACTIONAL for mail a user’s own action triggers, such as password resets and receipts; MARKETING for mail sent to a list, such as promotions and newsletters.
• WEBSITE_URL — the business site the email relates to; it need not be at the sending domain.

• Do NOT pass UseCaseDescription. The SESv2 API marks that parameter deprecated.
• Optional: --additional-contact-email-addresses (up to 4) and --contact-language EN|JA. AWS uses those contacts for correspondence about this account, so offer only addresses controlled by authorized members of the user’s own team — never an external recipient, a customer address, or a public list.
• Success looks like nothing. The API returns an empty HTTP 200 — no case ID, no status. That is expected, not a failure. Read the status back in Step 4.
• Whenever you present or run this command, tell the user two things: how to check the review status afterwards (aws sesv2 get-account, read Details.ReviewDetails.Status), and that they can already send today — naming all three options from Step 4’s “Sandbox recipient options”, in that numbering.
• A second call while a review is pending returns ConflictException (HTTP 409); there is no API to cancel or withdraw. BadRequestException (HTTP 400) means an input is invalid, not a refusal — see Failure modes.

Step 4: Check the decision

Read the whole response, not a projection — these branches turn on several nested fields:

Read ProductionAccessEnabled at the top level, and Details.ReviewDetails.Status and CaseId if Details.ReviewDetails is present at all — it is optional, and its absence is a branch below.

ProductionAccessEnabled alone decides whether the sandbox applies, so read that field before the review status. While it is false, SKILL.md’s sandbox recipient rule and “Sandbox recipient options” below apply whatever Details.ReviewDetails.Status says, GRANTED included. A GRANTED status does still mean the request has been decided, so skip Step 3 and do not resubmit.

ProductionAccessEnabled: true — and only this field — lifts the sandbox restriction, so “Sandbox recipient options” does not apply. Bind CHOSEN_RECIPIENT from the TEST_RECIPIENT collected in Step 1 if there is one, never from a null; if it was never collected, Step 5 asks. Any address works now, so offer to change it. Then Step 5.

ReviewDetails.Status: PENDING — under review. Do not tell the user to wait, and never that the account will be out of review in 24 hours: AWS documents an initial response within 24 hours, grants inside that window only “If we’re able to do so”, and may take longer. After that window the Support case is where AWS responds — read it as the DENIED branch describes. The account is still in the sandbox, so go to “Sandbox recipient options” below, opening with: “Your request is in. In the meantime you can test everything end to end right now — you just have to send to a recipient AWS already knows about.”

ReviewDetails.Status: DENIED — do not resubmit. Read the Support case at CASE_ID. CaseId is optional, so it may be absent — and the case may have been closed. Either way do not stop at “read the case”: have the user open the SES account dashboard in the console, which shows the production-access state, and re-engage AWS Support with a new case referencing the denial if they want the decision revisited. This is not the end of the journey: the account is still in the sandbox, not switched off. Go to “Sandbox recipient options” below, opening with: “The review came back denied — nothing about sandbox testing is lost.”

ReviewDetails.Status: FAILED — AWS did not receive the request; it is safe to submit again at Step 3. The resubmitted review is PENDING, which returns here.

Details.ReviewDetails absent — no request has been submitted in this Region. If the user wants production access, Step 3 is the next action and it is not a resubmit. If they do not, or PA_DECLINED is set, do not send them back to Step 3 — go to “Sandbox recipient options” below, opening with: “You’re still in the SES sandbox, so the first send has to go to a recipient AWS already knows about.”

Sandbox recipient options

This subsection is state-neutral. It applies whenever ProductionAccessEnabled is false — on all six of these paths: review PENDING; review DENIED; review GRANTED while ProductionAccessEnabled is still false; review FAILED where the user declines to resubmit at Step 3; PA_DECLINED set at Step 3; and Details.ReviewDetails absent. Where a branch above supplies its own opening sentence, use it; the options, numbering and binding rules are identical on every one of the six. No sandbox path reaches Step 5 without binding CHOSEN_RECIPIENT here and reading it back.

Ask which option they want, and record CHOSEN_RECIPIENT_OPTION and the address it resolves to as CHOSEN_RECIPIENT:

Pick whichever fits:

1. Verify the mailbox you want to test with, as its own email identity — recommended. AWS sends a verification message to that address; open it and click the link, which expires 24 hours after the message was sent. This is the option that lets you read the delivered message and check its authentication headers.
2. success@simulator.amazonses.com — the Amazon SES mailbox simulator. Nothing lands in a real inbox, so it is a fast check of the send path only, with no authentication headers to read. It works while the account is in the sandbox, is billed like any other send, and does not count against the daily sending quota (the sending rate still applies).
3. A real mailbox at a domain already verified in this account — only if such a mailbox actually exists. Verifying a domain in SES creates no mailboxes and no MX records, so an address at the domain you just set up receives nothing unless that domain already has real mail hosting. If it does, name that mailbox; no extra verification is needed.

Set CHOSEN_RECIPIENT per the session-state table and read it back before Step 5. Step 5 sends to CHOSEN_RECIPIENT, not the Step 1 answer.

Inputs differ by option. Option 1 needs an address the user can open — if TEST_RECIPIENT was never collected, ask for it in the same message as the option choice, so it stays one question. Option 2 needs no address. Option 3 needs a real mailbox at a verified domain. Never invent an address, never derive one from {DOMAIN}, and never substitute the simulator for an option the user did not choose.

Option 1 is check-then-do. Read the identity before creating it:

• NotFoundException → create it, which sends the verification message: aws sesv2 create-email-identity --email-identity '{TEST_RECIPIENT}' --region '{REGION}'
• Exists with VerifiedForSendingStatus: true → say so in one line and go to Step 5.
• Exists with false → the verification link is outstanding. Do not re-create it.

Then gate the send on the verification completing. The user clicks the link out of band, so read the state back and do not call send-email until it is true:

If still false, wait and re-read; sending first returns MessageRejected, which looks like a generic sandbox restriction and is not one. Bound that wait rather than looping: have the user check that mailbox’s spam folder, and remember that AWS documents the link expiring 24 hours after the message was sent — that window is the escape point, not an interval to poll through. There is no resend here: re-running create-email-identity returns AlreadyExistsException and sends no second message, and SendCustomVerificationEmail is a separate templated feature this skill does not use. An expired link is handled from the SES console, per Failure modes.

Option 3 is check-then-do too — verify the domain rather than trusting the name. The user names the mailbox; confirm the account can send to it with aws sesv2 list-email-identities --region '{REGION}':

• The domain part of the named address must appear in that list as an identity in this Region. If not, this option does not apply: say so and have the user pick option 1 or 2.
• Read that identity’s state before relying on it (aws sesv2 get-email-identity --email-identity '{that-domain}' --region '{REGION}'). An unverified domain identity does not make its addresses permitted recipients.
• Whether a mailbox exists there is not something any API can tell you. Confirm it with the user in words.

While ProductionAccessEnabled is false, SKILL.md’s sandbox recipient rule applies, per Region. If the user asks about limits, answer from the SendQuota values read in Step 1 rather than asserting a figure, and note that AWS counts that quota by recipients, not messages. A MAX_24_HOUR_SEND of -1 means the daily quota is unlimited, so report it that way. Do not raise limits unprompted.

Step 5: Send the first email

A send must have been asked for — Step 2’s scope gate stops a domain-setup-only request.

Apply Step 2’s send prerequisite first, re-reading the identity rather than trusting a carried value — DKIM may have moved since:

If it is not met — DkimAttributes.Status not SUCCESS, or MAIL FROM unresolved with BehaviorOnMxFailure at REJECT_MESSAGE — do not send: name the outstanding field and go back to Step 2. In the sandbox a permitted recipient does not substitute for this; the recipient rule and the send prerequisite are separate gates and both apply.

Then bind the sender and recipient. If {FROM_ADDRESS} is not bound, default it to onboarding@{DOMAIN} and STATE it with Step 1’s override invitation — do not ask. If {CHOSEN_RECIPIENT} is not bound — a domain-setup-only request defers it — ask for it now, in ONE question, at the point of use; in the sandbox it must be bound by Step 4’s “Sandbox recipient options” rather than asked for freely, because an arbitrary address is not a permitted recipient there. Never invent a recipient: the From default is the one derived value this skill permits, because any mailbox at the verified domain is a legal sender.

{FROM_ADDRESS} must be at {DOMAIN} or at another identity verified in this Region, per SKILL.md’s sender invariant; if it is not, ask for an address at {DOMAIN} rather than sending.

MUST ask before sending. A real message is about to reach a real person:

The next command sends a real email from {FROM_ADDRESS} to {CHOSEN_RECIPIENT}. Ready?

Use aws sesv2 send-email, never the v1 form, per SKILL.md’s Critical Rules.

--feedback-forwarding-email-address sets where SES sends bounce and complaint notifications; left off, they go to {FROM_ADDRESS}. If that is not a monitored mailbox, set it to a deliverable address at the verified {DOMAIN} controlled by an authorized member of the user’s own team — bounce notifications carry recipient addresses, so never an external recipient or public list. Omit the flag rather than guessing. SES is billed per recipient — see Amazon SES pricing (opens in a new tab) — so say that before sending.

A returned MessageId means Amazon SES accepted the message — not that it was delivered. Say that plainly, then run the check matching CHOSEN_RECIPIENT_OPTION:

Where raw headers live differs by mail client — in Gmail, More (three vertical dots) then Show original. dmarc=pass appears only if a _dmarc TXT record is published for {DOMAIN} — a precondition, not automatic; if DMARC is missing or shows none, go back to the DMARC step in setting-up-ses-domain-identity.md.

If it has not arrived: check the spam folder first, then see Failure modes. A bounce, if there is one, arrives by email at the feedback-forwarding address.

Step 6: After it arrives — optional extras

Only offer these once the test send has landed. Offer once, act on a yes, do not push. Dedicated IPs and tenants exist for higher volume and for isolating senders — one line each. Do not raise pricing plans.

Failure modes