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 describe the restriction as "each recipient must be individually verified": a verified domain covers every address at that domain.
• The sender must be verified too, in every account state. AWS documents that after an account moves into production "you still have to verify all identities that you use as 'From', 'Source', 'Sender', or 'Return-Path' addresses." So MessageRejected: Email address is not verified has two causes: an unpermitted recipient in the sandbox, and an unverified sending identity in any state. Read the address named in the error before choosing a fix, and check that the From address is at a domain or address verified in this Region.
• A verified sender is the SES service minimum; this skill's journey asks for more. SES itself will accept a send from an identity that is verified for sending even when DKIM has not reached SUCCESS. This skill deliberately does not stop there: its goal is a delivered, authenticated first email, so it requires DkimAttributes.Status: SUCCESS before it claims domain setup or authentication is complete, and before it sends. That stricter bar is stated once, as the send prerequisite in onboarding.md's domain-verification step, and every send path applies it. The two are not in conflict — one is what the service enforces, the other is what this journey promises the user.
• Validate every substituted value, then quote it for its context. A value interpolated directly into a shell command is single-quoted; a value placed inside inline JSON is JSON-encoded (double quotes, per JSON rules), and only the whole JSON blob is single-quoted for the shell — never shell-quote an individual value inside JSON. This applies to every user-supplied value this skill substitutes — DOMAIN, the MAIL FROM subdomain, FROM_ADDRESS, TEST_RECIPIENT, CHOSEN_RECIPIENT, MAIL_TYPE, WEBSITE_URL, REGION, PROFILE — not only the DNS names. Reject any value containing a single or double quote, a backtick, $, ;, a backslash, or whitespace, and ask the user to re-provide it; never escape a rejected value into shape. Per-value shapes: DOMAIN and the MAIL FROM subdomain — DNS labels only, letters, digits, hyphens and dots; From address and every recipient value, TEST_RECIPIENT and CHOSEN_RECIPIENT alike — a single address with one @, and reject a comma-separated list (put multiple recipients in the ToAddresses array instead); MAIL_TYPE — exactly TRANSACTIONAL or MARKETING; WEBSITE_URL — an http/https URL of 1–1000 characters, which need not be at the verified domain, since any business site the mail relates to is acceptable to AWS, so the question set may offer https://{DOMAIN} as a suggested default only; REGION — an AWS Region code; PROFILE — a CLI profile name. A CHOSEN_RECIPIENT bound from an option the skill supplies rather than the user — the mailbox simulator address — is validated the same way. JSON-encode any user-supplied subject or body text with a serialiser rather than pasting it between quotes.

IAM Permissions

Grant only the actions the workflow being run actually calls, and nothing more — never ses:* or *FullAccess. Each reference file has a Required IAM actions section listing exactly what it calls; use that list, not a wildcard.

Scope per-identity actions to the identity each call actually acts on:

• arn:aws:ses:{region}:{account-id}:identity/{domain} for domain operations.
• arn:aws:ses:{region}:{account-id}:identity/{address} for an email-address identity — the identity used for sandbox recipient verification, and equally the From identity when the sender is a separately verified email address rather than an address at the domain. A policy scoped only to the domain denies those calls. Reads are scoped the same way: the ses:GetEmailIdentity statement must carry the ARN of every identity actually read, which includes a recipient address identity and — for sandbox recipient option 3 — the exact identity ARN of the other verified domain the user names. A policy scoped only to the sending domain denies that read, which reads as a broken permission rather than as a missing recipient. A send is authorized by the identity that covers its From address, so scope ses:SendEmail to whichever identity that is; the three cases are listed in onboarding.md's Required IAM actions.
• Route 53 zone actions (route53:GetHostedZone, route53:ListResourceRecordSets, route53:ChangeResourceRecordSets) to arn:aws:route53:::hostedzone/{hosted_zone_id}, using the bare zone ID — list-hosted-zones-by-name returns /hostedzone/Z123ABC, so strip that prefix before building the ARN or the result is double-prefixed and matches nothing. The zone reads are needed whenever the agent checks whether Route 53 hosts the domain; only route53:ChangeResourceRecordSets is conditional on the user approving a write.

Only genuinely account-level and list actions (sts:GetCallerIdentity, ses:GetAccount, ses:ListEmailIdentities, route53:ListHostedZonesByName, route53:TestDNSAnswer) have no resource-level scoping and must be granted on *. Grant ses:PutAccountDetails deliberately, because it changes account-wide sending posture.

Security Considerations

• Ephemeral credentials. Use IAM roles with STS — never long-lived access keys.
• Consent gates. Opening a production-access review and sending a real message both commit the user in ways no API can undo, and a Route 53 change can affect live traffic. Each gate — the production-access consent gate, the send confirmation, and the DNS-write permission — is owned by the reference file that performs the action; never proceed past one because this file summarises it.
• Delivery TLS is opportunistic by default. AWS documents that SES always attempts a secure connection to the receiving mail server and sends the message unencrypted if it cannot establish one, and that requiring TLS means setting a configuration set's TlsPolicy to REQUIRE — a configuration-set workflow outside this skill's scope.
• Validate and quote every user-supplied value before it enters a shell command or inline JSON. The rules and character sets are under Invariants above.
• Never place message bodies or recipient lists in logs.
• Never hardcode credentials, endpoints, or secrets in examples. Store any application credentials in AWS Secrets Manager or Parameter Store.
• Enable CloudTrail for SES API call auditing, and alarm on repeated AccessDeniedException and unusual send volume. Encrypt the trail's log files with an AWS KMS key (SSE-KMS) and restrict access to the trail's S3 bucket and CloudWatch Logs group, and encrypt that log group with a KMS key (--kms-key-id on create-log-group) — SES CloudTrail entries carry email addresses, domain names, and account details.

Additional Resources

• Request production access
• SES Domain Verification
• DKIM in SES
• Custom MAIL FROM
• DMARC Authentication
• SESv2 API Reference