Overcast is alpha — behaviour and APIs may change between releases. Pin your version and read the changelog before upgrading.

overcast

SES — Simple Email Service

Quick start, what lands in the console Inbox and how to read it, the v1 and v2 sending surface, and the verification, quotas and configuration sets that are skipped.

Send with the v1 or v2 API and the message lands in the console’s Inbox instead of a mailbox. Nothing is delivered off the machine.

Status: ⚠️ Partial

Quick start

export AWS_ENDPOINT_URL=http://localhost:4566

aws ses verify-email-identity --email-address app@example.com
aws ses send-email \
  --from app@example.com \
  --destination ToAddresses=someone@example.com \
  --message 'Subject={Data=Hello},Body={Text={Data=It works}}'

Any credentials work; with none configured, run eval "$(overcast env)" first — see Using AWS SDKs and CLI.

Open http://localhost:4567/inbox to read it.

What lands in the Inbox

Overcast runs an SMTP server on port 1025 (OVERCAST_SMTP_PORT) and captures everything sent through it, plus deliveries that never touch SMTP at all:

SourceAppears as
SES SendEmail, SendRawEmail, SendTemplatedEmailAn email
SNS email / email-json subscriptionsAn email, threaded by publish
SNS sms subscriptions and Publish --phone-numberAn SMS
SNS http / https subscriptionsA captured webhook delivery
Cognito confirmation, invite and reset messagesAn email or an SMS

The same messages are available over HTTP at GET /_overcast/ses/inbox/messages. The buffer holds the most recent 500 messages (OVERCAST_SMTP_INBOX_MAX); set OVERCAST_SMTP_HOST to relay to a real server instead of capturing. A test suite written against LocalStack’s GET /_aws/ses works unchanged: the emails are served there too, in LocalStack’s shape — see Debug endpoints § Compatibility aliases.

What works

AreaBehaviour
Sending (v1)SendEmail, SendRawEmail (raw MIME), SendTemplatedEmail
Sending (v2)SendEmail at POST /v2/email/outbound-emails
TemplatesFull CRUD plus {{key}} substitution on send
Identitiesv1 verify/list/delete and the v2 CreateEmailIdentity family, with inline Tags
Tags (v2)TagResource, UntagResource, ListTagsForResource by identity ARN
ConsoleThe SES page adds and removes identities

Differences from AWS

AreaOn AWSOvercast
DeliveryThe message reaches the recipientCaptured in the Inbox; nothing is sent
Identity verificationA DNS or email round-trip, then Pending → SuccessAuto-verified; GetIdentityVerificationAttributes always says Success
Unverified sendersMessageRejectedAccepted — the sending identity is not checked
Sandbox and quotasEnforced; GetSendQuota reports real limitsUnlimited quota, empty send statistics
DKIM, MAIL FROM, notification topicsConfigurable per identityNot implemented — 501 Not Implemented
Configuration sets and receipt rulesFull APINot implemented — 501 Not Implemented

Gotchas

Note

The console’s SES page manages identities only. Sent mail is in the Inbox, not on that page.

A second Overcast on the same host finds 1025 taken and moves its capture server to an ephemeral port; the Inbox follows, and the startup log says where it went. Only a pinned OVERCAST_SMTP_PORT that is taken leaves capture unavailable — sends then fail naming the variable, and /_overcast/health reports the failed listener. See Running two instances on one host.

Operations

27 of 45 listed operations are implemented. Per-operation status, notes and AWS API links: SES operations.