/amazon-ses

name: amazon-ses
description: "Guides Amazon SES onboarding for domain-based email sending. Covers identity configuration, production access, an optional first test send, and troubleshooting setup, authentication, or sending failures. Use when setting up SES, resuming incomplete onboarding, or leaving the sandbox. Does not cover inbound email or Mail Manager, SMS/voice, WhatsApp, SNS, Pinpoint, or WorkMail."
version: 2

Amazon SES

Overview

> **Recommended**: Use the [AWS MCP Server](https://docs.aws.amazon.com/aws-mcp/latest/userguide/what-is-mcp-server.html) 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

| If the user wants to... | Read | |-------------------------|------| | Get started with SES, set up email sending, send a first or test email, move out of the sandbox, or diagnose `MessageRejected: Email address is not verified` | [SES onboarding: zero to first delivered email](references/onboarding.md) | | Set up a domain for sending, configure email authentication, or troubleshoot DKIM | [Setting up SES domain identity](references/setting-up-ses-domain-identity.md) |

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 r