amazon-ses

Files (3)

• SKILL.md
• onboarding.md · references/
• setting-up-ses-domain-identity.md · references/

SKILL.md (first lines)

# 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 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

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws