Amazon Ses

Amazon SES

Overview

Recommended: Use the AWS MCP Server with SES permissions for sandboxed execution and CloudTrail audit logging. Without MCP: All operations use standard AWS CLI syntax (aws sesv2 ...).

Takes a developer who is not an email authentication expert from an empty AWS account to a real, authenticated email in their inbox, and on to production sending if AWS approves the request.

Read the account and identity state before touching anything, and complete only the parts of domain setup that are actually missing. Request production access only after domain setup is complete and the user has given explicit consent. A test send is optional: run it when the user asks for one, to a recipient the account's current state permits.

Routing

Guardrail — where this skill's own files live (MCP vs local install)

This skill can be loaded two ways, and they resolve its own bundled files from different places. Determine how the skill was loaded before reading a reference:

• Loaded through the AWS MCP `retrieve_skill` tool: the skill is not on the local filesystem. You MUST fetch each reference via retrieve_skill with the file parameter (e.g. file="references/onboarding.md"). Do NOT file_read these paths locally — they do not exist on disk.
• Installed locally (e.g. ~/.kiro/skills/amazon-ses/, .kiro/skills/amazon-ses/, or ~/.claude/skills/amazon-ses/): read files from the local skill directory using the relative paths above.

This distinction applies only to the skill's own packaged files. User data and session artifacts are always read from and written to the user's working directory — never fetch or write customer data through retrieve_skill.

Critical Rules

• MUST use the SES v2 API: aws sesv2 ..., never the v1 aws ses ... commands. A v1 command reports no error signalling the wrong API was chosen, so the mistake is silent, and the operations this journey needs — production-access requests, and DKIM plus MAIL FROM attributes in a single identity read — exist only in v2. Models trained on published CLI examples tend to default to the v1 syntax.
• MUST NOT volunteer API version mechanics, internal limit figures, or other plumbing. Explain only what the user has to decide, consent to, pay for, or act on. Surface the rest only when they ask, when their problem turns on it, or when a reference file names the disclosure as required.
• MUST ask for missing inputs in ONE question set rather than one at a time — and MUST NOT ask for inputs the request does not need. Scope the questions to what the user asked for: a request that already names the domain and MAIL FROM subdomain is a complete domain-setup request, so read state and execute rather than stalling for send-time or production-access inputs. If nothing is missing for the chosen scope, ask nothing.
• MUST NOT ask which AWS CLI profile or Region to use while either can still be resolved. Honour --profile only if the user names one. Resolve the Region in this order, taking the first that yields a value: a Region the user named; AWS_REGION; AWS_DEFAULT_REGION; aws configure get region, adding --profile '{PROFILE}' when the user named a profile, since a profile can carry its own Region. That last command reads the CLI configuration files only and does not see the environment, which is why the two environment variables are checked separately and ahead of it. State the resolved Region before any mutation, because SES state is per-Region, and report the account and principal from aws sts get-caller-identity. Two cases, and only these two, are where you do ask: nothing in that chain yields a Region, because every aws sesv2 call fails without one; and aws sts get-caller-identity fails on expired or invalid credentials, in which case ask which account (profile) and Region to use once they are refreshed, because the configured defaults are no longer trustworthy. Fold either into the one question set rather than spending an extra turn on it.
• MUST pass request payloads (change batches and message content) to the CLI as inline JSON strings, never as file:// paths — file:// is AWS-CLI-specific and does not resolve when the CLI is executed through the AWS MCP server.
• MUST read current state before each step and skip steps already satisfied. In particular: never call create-email-identity for an identity that already exists (it returns AlreadyExistsException), and never re-run put-email-identity-dkim-signing-attributes on an identity whose DkimAttributes.Status is SUCCESS, because re-initialising can change its tokens. Gate that call on status, not on whether the published CNAMEs resolve — on a FAILED identity the records often do resolve and are simply not being honoured, which is what FAILED means, so resolving records are not a reason to withhold the recovery. The status-gated recovery paths, and the BYODKIM check that precedes them, are owned by setting-up-ses-domain-identity.md.
• For domain setup, create a domain identity. Create an email-address identity only when the user explicitly chooses verification of that individual address.

Invariants

These hold everywhere in this skill. The reference files apply them, and may add workflow-specific detail on top of them — a reference may state how an invariant is checked at a particular step, or narrow it for that step's state. None of them may contradict or relax what is written here.

• Domain setup complete means all three of these are true in one aws sesv2 get-email-identity response: VerifiedForSendingStatus is true, and DkimAttributes.Status is SUCCESS, and MailFromAttributes.MailFromDomainStatus is SUCCESS. Two of the three is not complete. While MailFromDomainStatus is PENDING, FAILED or TEMPORARY_FAILURE, AWS documents that SES uses the custom MAIL FROM fallback setting: with USE_DEFAULT_VALUE it sends using a subdomain of amazonses.com, so SPF validates but the envelope sender does not align with the From domain and DMARC cannot pass on its SPF leg; with REJECT_MESSAGE SES returns MailFromDomainNotVerified and does not attempt delivery. This is the gate the rest of the skill calls "domain setup complete".
• Sandbox recipient rule. While ProductionAccessEnabled is false, AWS documents that you can only send to verified email addresses and domains, or to the Amazon SES mailbox simulator. That means, in the order this skill always presents them: (1) an address verified as its own email identity, (2) the Amazon SES mailbox simulator, or (3) any address at any verified domain in the account — not only the domain just set up. The restriction is on the recipient, not the sender: a fully verified sending domain does not lift it, and you must never attempt to work around it. Production access is governed by `ProductionAccessEnabled` alone — while it is false, these three options apply whatever Details.ReviewDetails.Status says. When you explain the restriction to a user, you MUST name all three recipient options that work right now, in that same numbering, before proposing production access as the remedy, and you MUST NOT