- Status: Accepted (decided by the maintainer)
- Date: 2026-11-11
- Amends: ADR 0011 (adds the skip reason
sender_not_verified, the outcome unavailable, and closes the set of unknown reasons), ADR 0030 (unavailable attempts do not count toward the retry limit), ADR 0024 (resolves the event transport and the account-level suppression setting)
ADR 0024 makes Amazon SES the provider of the managed service, with one SES tenant per workspace, two configuration sets, workspace-scoped suppression, and our own sender protection. ADR 0012 fixes how sending works: aws4fetch with retries: 0, tags on every send, unknown resolved only by a Send event within 72 hours, and billing on the Send event. ADR 0018 puts the adapter in adapters/email-ses, using only fetch and WebCrypto so it runs on both targets. Three points were left open: the transport for SES events (SNS or an EventBridge API destination), whether an SES 5xx response is a definite error or unknown, and how a workspace may only send from its own domains.
Facts checked on 2026-11-11 in the AWS documentation (SESv2 SendEmail and MessageTag API reference; SES event publishing, EventBridge destinations, and tenants; EventBridge API destinations, connections, and quotas; SNS signature verification and delivery retries):
POST /v2/email/outbound-emails takes FromEmailAddress, Destination, Content.Simple (subject, text and HTML bodies, and custom Headers), EmailTags, ConfigurationSetName, and TenantName, and returns {"MessageId"}. With TenantName, sending succeeds only if the identity and configuration set are associated with that tenant.
- Tag names and values may contain only ASCII letters, digits,
_, and -, up to 256 characters. Our IDs (prefix_ plus hex, and project slugs) fit; email addresses and dotted values do not.
- Documented errors:
MessageRejected, MailFromDomainNotVerifiedException, AccountSuspendedException, SendingPausedException, LimitExceededException, BadRequestException (all 400), NotFoundException (404), and TooManyRequestsException (429). The documentation does not say whether a 5xx means the message was not accepted.
- SES can accept a message and not send it: a send to an address on the account or tenant suppression list returns a
MessageId and then produces a Permanent bounce with subtype OnAccountSuppressionList or OnTenantSuppressionList. By default all tenants share the account-level suppression list; a tenant can use its own list instead.
- Events carry the send’s tags in
mail.tags as a map from name to an array of strings. Event types: Send, Reject, Bounce, Complaint, Delivery, DeliveryDelay, Rendering Failure, plus Open, Click, and Subscription.
- A configuration set can publish events straight to the EventBridge default event bus. SES tenant status changes are published there too (
Sending Status Enabled, Sending Status Disabled), which ADR 0024 already consumes.
- An EventBridge API destination calls a public HTTPS endpoint with a connection that authorizes by API key header, Basic, or OAuth client credentials. It times out after 5 seconds, retries 401, 409, 429, 5xx, and timeouts for up to 24 hours and 185 attempts by default, and can send what it gives up on to a dead-letter queue. Invocations are limited to 300 per second per Region by default (adjustable); above that they are delayed, not dropped.
- SNS HTTPS subscriptions require verifying an RSA signature against an X.509 certificate fetched from the message, and confirming the subscription by fetching a URL from the message. SNS retries an HTTPS endpoint for about 6 hours by default, and a custom policy for HTTPS cannot retry beyond one hour.
| Choice |
Alternatives |
Why this one |
| Event transport: EventBridge API destination |
SNS HTTPS subscription |
EventBridge is already needed for tenant status events; a header secret instead of an X.509 chain to fetch and parse in the Worker; no subscription handshake; 24 hours of retries instead of 6 |
SES 5xx is unknown |
5xx is a retryable rejection |
AWS does not document that a 5xx means “not accepted”, and ADR 0007 forbids resending on a guess |
| Sender checks against a project-store replica |
A control-plane read on each send; the request-time check only |
No control-plane read on the send path; the replica is needed anyway for the tenant name |
- The
EmailProvider port stays provider-neutral. send(email, tags, context) returns accepted, rejected (retryable or permanent), unavailable, or unknown, and takes a send context { stream: "transactional" | "marketing", providerTenant: string | null }. The SES adapter maps stream to its configuration set and providerTenant to TenantName; core never names either.
- The workspace’s provider tenant and its sending domains live in the control plane and are replicated to each project store of the workspace, the same way as the workspace suppression list (ADR 0024).
claimSend reads them inside its transaction and hands the context to the delivery consumer, so the send path never reads the control plane.
adapters/email-ses calls SESv2 SendEmail with fetch, signed with SigV4 by aws4fetch (retries: 0, ADR 0012), with a 10-second timeout from an AbortSignal. No AWS SDK.
- Each send carries
EmailTags project_id, message_id, and attempt_id. Mail is sent as Content.Simple; the List-Unsubscribe headers go in Headers.
send returns exactly one outcome. The message’s state reason stays the closed set of ADR 0011 (for example queued:provider_retryable, failed:provider_rejected); the adapter’s code below goes in a separate providerReason field on the message.
| SES result |
Outcome |
providerReason |
200 with a MessageId |
accepted |
|
200 without a readable MessageId |
unknown |
unparseable_response |
429 TooManyRequestsException, 400 LimitExceededException or ThrottlingException |
rejected, retryable |
throttled |
| The same codes with the message “Daily message quota exceeded” |
unavailable |
daily_quota_exceeded |
400 SendingPausedException, AccountSuspendedException |
unavailable, with an operator alert |
sending_paused |
401, 403, or a signature or credential error (for example AccessDeniedException, NotAuthorized, RequestExpired, UnrecognizedClientException) |
unavailable, with an operator alert |
provider_auth |
404 NotFoundException (configuration set or tenant missing) |
unavailable, with an operator alert |
provider_configuration |
400 MessageRejected with the message “Sending disabled for ” |
unavailable, with an operator alert |
provider_tenant_paused |
400 MessageRejected with the message “Sending disabled for ” |
unavailable, with an operator alert |
sending_paused |
400 MessageRejected otherwise |
rejected, permanent |
message_rejected |
400 MailFromDomainNotVerifiedException |
rejected, permanent |
mail_from_not_verified |
400 BadRequestException or any other 4xx |
rejected, permanent, with an operator alert |
bad_request |
| 5xx |
unknown |
provider_5xx |
| Timeout, connection error, or reset |
unknown |
timeout or network |
- Amended on 2026-11-12, while building B1, from the AWS documentation checked that day:
- The SES developer guide says both sending limits produce a
ThrottlingException whose message is either “Daily message quota exceeded” or “Maximum sending rate exceeded”. The daily quota lasts for hours, so it is unavailable, not a retryable rejection that would use up a message’s attempts. The text is matched inside the adapter, without regard to case, and never leaves it. If the match ever misses, the daily quota shows up as throttling that exhausts the retry limit; B3 alerts on that case, and the manual smoke test confirms the text before real mail is sent.
- The SESv2 Common Error Types list
ThrottlingException as 400 and the credential errors (AccessDeniedException, ExpiredTokenException, IncompleteSignature, NotAuthorized 401, OptInRequired, UnrecognizedClientException) as 401 or 403; the adapter also treats the codes other AWS services use for the same conditions (RequestExpired, InvalidAccessKeyId, InvalidClientTokenId, SignatureDoesNotMatch, MissingAuthenticationToken) as provider_auth, so an environment condition never fails a message permanently.
- Not documented, left to the manual smoke test: whether SESv2 returns the quota condition as
ThrottlingException or TooManyRequestsException; and which code a send with a TenantName that does not exist, is paused, or is not associated with the identity or configuration set returns. The SendEmail reference describes LimitExceededException as “too many instances of the specified resource type”, not a sending rate; it stays a retryable rejection, bounded by the retry limit.
- Amended on 2026-11-18, after the staging smoke test of 2026-11-17 recorded the tenant errors: a missing tenant is 404
NotFoundException (provider_configuration), and a tenant not associated with the identity or configuration set is 400 AccessDeniedException (provider_auth), both unavailable as the table already said. A tenant whose sending SES or the operator paused is 400 MessageRejected with the message “Sending disabled for ”, which the table read as a permanent rejection, so a pause would have failed every message it touched. A pause is about the sender, not the message, so it is unavailable with provider_tenant_paused: messages wait as queued:provider_unavailable and raise its alert, and they send once the tenant resumes within 24 hours of their first attempt. The adapter matches the text without regard to case, as it does the daily quota, and the text never leaves it. The same text naming any other resource (a configuration set whose sending is disabled is the likely one, not yet recorded) is sending_paused. Any other MessageRejected, such as an unverified sender (recorded), stays permanent. If the match ever misses, a paused tenant fails its messages as failed:provider_rejected without an alert (ADR 0038 alerts on a permanent rejection only for bad_request); routing the Sending Status Disabled event to the operator is then the only signal. The alert’s incident key holds no workspace (ADR 0038), so it names one affected workspace per alert window: two tenants paused in one window raise one alert, and the operator lists every paused tenant at SES.
unavailable is a new, provider-neutral outcome: the provider refused before acceptance for a reason that is not about this message (sending paused, credentials, configuration). recordOutcome decides, using only transitions of ADR 0011:
- if the message’s first attempt was less than 24 hours ago,
sending → queued:provider_unavailable with the usual backoff, and the attempt does not count toward the retry limit of ADR 0030, so one account-wide incident does not use up every message’s attempts;
- otherwise
sending → failed:provider_unavailable.
- The first attempt’s time is a new message field,
firstAttemptedAt, set by the first claimSend and never changed (attemptedAt keeps the latest attempt). No new deadline or wake is needed: the decision is made each time an attempt comes back unavailable. When kill switches exist, the alert also pauses the stream.
- An SES 5xx is
unknown. During an SES incident these messages wait for a Send event and, without one, end as failed:outcome_unknown after 72 hours; the unknown-count alert makes that visible.
- Amended on 2026-11-13, after the plan review that followed A5: the operator alerts above are raised through the project store’s outbox, written in the transaction that records the outcome, never as a side effect inside it. Each occurrence carries an incident key without the project, and the alerting implementation deduplicates by it, so an account-wide SES incident raises one alert, not one per project.
unknown outcomes and accepted sends whose Send event never arrives (an EventBridge misconfiguration) alert too.
- A connection error before the request was sent cannot be told apart from one after it on Workers, so it is
unknown too.
- Credentials and secrets never appear in an outcome, an error message, a step log, or a log line (ADR 0032). The codes above are the only provider detail kept.
- A workspace sends only from its own sending domains, kept in the control plane as
sending_domains(workspace_id, domain, status) and replicated to its project stores. Until the domain management API and our DNS checks (ADR 0024) exist, the operator provisions the rows after verifying the domain in SES and associating it with the workspace’s tenant.
- Two checks:
- When a send approval is requested (ADR 0033): the request is refused with
sender_not_verified.
- In
claimSend, against the replica: a message whose from domain is not a verified sending domain of its workspace becomes skipped:sender_not_verified, which queued → skipped already allows. No provider call is made.
- SES tenant association is a third, independent guard: SES refuses an identity not associated with the workspace’s tenant.
- Amended on 2026-11-13, while building C1:
- The replica holds the provider tenant and the verified domains only. Whatever replicates it leaves out domains in any other status, so the project store needs no status vocabulary of its own.
- A
from domain matches a verified domain exactly, ignoring case. A subdomain is a different domain and needs its own row.
- A project store with no replica fails closed: nothing is verified, so every message it would send becomes
skipped:sender_not_verified. A replica that never arrived must not let a project send from any domain, and a self-hosted installation without a provider tenant has no SES tenant guard behind it. skipped is terminal, so a message skipped this way is not sent later when the replica arrives.
- The replica is written whole by the project command
replaceSenderReplica, so writing the same replica twice changes nothing. Ordering between writes (so a delayed, older replica cannot bring back a removed domain) is left to the replication path; it will change the signature of replace, which is left out until then on purpose.
- The replication path writes the replica on every control-plane write of a workspace’s domains or tenant, and has a resync entry point that writes it for every existing project store. Stores already migrated to schema version 5 (the replica’s migration) and projects inserted into the control plane by SQL (the development seed) get no replica from project creation, and
skipped is terminal, so deploying the check before the replica arrives would drop the queued messages for good. The resync runs before or with the deploy of the check, and the development setup runs it, so the development flow sends.
claimSend checks the sender after the workflow and customer checks, so a stopped workflow or an ineligible customer keeps its own reason.
- Amended on 2026-11-13, after the plan review that followed A5:
- Both checks compare the normalized
from domain (the normalization of ADR 0035: lower case, no trailing dot, IDNs as A-labels), normalized when a version is saved and again in the check, so an IDN from written with U-labels matches its A-label row instead of reading as unverified.
- The approval-time check reads the project’s replica, like
claimSend, not the control plane.
- In cloud mode, a workspace whose replica has no provider tenant cannot send, so no managed send goes out without the SES tenant guard.
- Amended on 2026-11-13, while building the approval-time check (A6):
sender_not_verified is an API error code with HTTP status 422, returned by workflows.activate over REST and MCP alike when a send step’s from domain is not verified in the project’s replica. The message names the send steps, so the caller can fix them. Nothing is written: no approval, no link, and no count toward the daily link cap. A latest version that is already live is not checked again; claimSend still guards its messages.
- A
from may be written with an IDN domain in U-labels. The local part keeps the email rule it had. The published input schema gives from that rule as a pattern, without format: "email", which is ASCII only and would make clients that check formats refuse a U-label domain. Saving a version normalizes the domain and keeps the local part as written, so the stored definition, its hash, and the message’s fromAddress carry the A-label form, and two spellings of the same domain save as the same version. A from whose domain does not normalize (an invalid A-label, a label ending in a hyphen, an IP address) is refused when the version is saved, with validation_error naming the field.
- Approving a pending approval checks the replica again, in the decision’s transaction, because a domain may be removed while the approval waits. If a
from domain is no longer verified, the decision is refused like the other refusals (conflict, 409, with the reason sender_not_verified): the approval stays pending, the workflow is unchanged, and the same link approves once the domain is verified again. Declining is not checked.
- Versions saved before this change may hold a domain that is not normalized. Both checks normalize it again, so they need no migration. Re-saving such a version with the same definition normalizes it into a new version once, which supersedes any approval pending for the old one.
- Account-level suppression is disabled for both configuration sets, and every tenant uses tenant-level suppression. A setup check confirms this. Otherwise one workspace’s bounces would suppress the address for every other workspace.
- Clarified on 2026-11-14, without changing the decision: SES applies a configuration set’s suppression setting before the tenant’s and the account’s. “Account-level suppression is disabled” therefore means each configuration set has
SuppressionScope TENANT with reasons BOUNCE and COMPLAINT. An empty reason list would turn suppression off for the set, and the tenants’ lists would be skipped too. A self-hosted installation without SES tenants has no tenant lists to use, so its configuration sets keep account-level suppression (no override); its workspaces share one operator’s account.
- A Permanent bounce with subtype
OnAccountSuppressionList therefore means misconfiguration. It raises an operator alert and reverses the charge, and it does not add the address to the workspace suppression list, because the bounce came from another workspace’s history.
- Each configuration set publishes Send, Reject, Bounce, Complaint, Delivery, DeliveryDelay, and Rendering Failure to the EventBridge default bus. One rule sends events with source
aws.ses to an API destination at /provider-events/ses, with a dead-letter queue that has a depth alarm and a documented replay (the existing “before launch” item). The same path will carry tenant status events.
- The connection uses API key authorization: a header carries
SES_EVENTS_SECRET. verifyWebhook compares it in constant time and checks that the event’s source is aws.ses and, when SES_ACCOUNT_ID is set, that its account matches. A failed check is 401, and nothing is parsed further or stored. Rotation needs no second secret: EventBridge retries 401 for 24 hours, so events refused while the connection and the Worker secret are updated are delivered again.
- A header secret is weaker than a signature: whoever has it can post events. Every event still needs send-time tags that match a stored message and, once bound, the same provider message ID (Tenant model), so a forged event cannot reach another project’s data.
providerEvents.receive applies events synchronously, grouped per project, as it does today (ADR 0030). A failure is a 5xx that EventBridge retries. The provider-events queue is added only if measured latency approaches the 5-second timeout.
- Deduplication: the provider event ID is the EventBridge event
id, which stays the same across EventBridge retries. SES itself may publish an event more than once with different IDs; those duplicates are absorbed because message transitions never regress and the ledger is unique on (message_id, kind) (ADR 0012).
- Delivery statuses, in the order in which they may replace each other (a later status never gives way to an earlier one):
delayed < delivered < soft_bounced < content_rejected < bounced < complained. soft_bounced ranks after delivered on purpose: a transient bounce is a delivery problem worth keeping visible, so a later delivered event does not replace it. (Changed on 2026-11-15 by the maintainer: soft_bounced now ranks below delivered; see the amendment below.)
| SES event |
Normalized type |
Effect |
| Send |
send |
sending or unknown → accepted; billed (ADR 0012) |
| Delivery |
delivered |
delivery status delivered |
| DeliveryDelay |
delayed |
delivery status delayed |
Bounce, Permanent |
hard_bounce |
delivery status bounced; address added to the workspace suppression list |
Bounce, Permanent, subtype OnTenantSuppressionList |
hard_bounce |
as above, and the charge is reversed |
Bounce, Permanent, subtype OnAccountSuppressionList |
hard_bounce |
delivery status bounced; charge reversed; operator alert; no workspace suppression |
Bounce, Transient or Undetermined |
soft_bounce |
delivery status soft_bounced; no suppression |
| Complaint |
complaint |
delivery status complained; address added to the workspace suppression list |
| Reject |
reject |
delivery status content_rejected; no suppression |
| Rendering Failure |
rendering_failure |
not expected, because we render ourselves; counted by type |
- Amended on 2026-11-15, while building B2:
- The normalized
hard_bounce carries suppressionList, tenant or account, for the two suppression-list subtypes; core never names SES. Both write the reversal ledger row (and, by the maintainer’s amendment below, so do a reject and a global bounce). The operator alert of an account bounce is the condition bounced:account_suppression_list (ADR 0038), written only with the message’s first reversal, so a bounce SES publishes twice alerts once.
- A reversal cancels only an existing charge: billable messages are those with a charge and no reversal (the ledger port’s
billableCount). A suppression-list bounce that arrives before its Send event, or whose Send event is never billed, so never makes billable mail negative. The D1 export of the ledger and budget settlement, when built, apply the same rule.
- A bounce type other than
Permanent (Transient, Undetermined, or one AWS adds later) is soft_bounce, so an unknown type never suppresses.
normalizeEvents returns nothing, and the endpoint answers 200, for SES tenant status events (until the auto-pause applies them, keyed by tenant and region as ADR 0037 says), for detail-types it does not use, and for message events without the three send-time tags, which no stored message can match. A message event of a type it uses that it cannot read is a 400, which EventBridge dead-letters for replay.
verifyWebhook compares HMACs of the presented and the configured secret under the configured one, so the comparison takes the same time whatever the length of either. With the right secret, a source other than aws.ses or another account is refused with 401 like a wrong secret, so events recover once a mistyped SES_ACCOUNT_ID is fixed; a body that is not a JSON object is a 400 from normalizeEvents, dead-lettered for replay instead of retried for a day.
- A Send event after the 72-hour window raises the condition
accepted:late, as ADR 0012 says, besides its accepted:late step log.
- The fixtures are written from the AWS documentation’s example events, not recorded, and a wrong detail-type string would drop its events silently (the EventBridge rule and the adapter share the strings). B4’s deploy gate records the events through the SES mailbox simulator, or confirms the strings of those it cannot produce against a real event or the EventBridge schema registry, and replaces the fixtures before SES is enabled.
- Amended on 2026-11-15 (decided by the maintainer, after the review of B2); this also amends ADR 0012’s rule for which drops are not billable:
- Delivery statuses, in order:
delayed < soft_bounced < delivered < content_rejected < bounced < complained. A transient bounce before or after a delivery never hides it, and a Permanent bounce or a complaint after a delivery still wins. The order stays total, so the result does not depend on the order events arrive in.
- A send the provider accepted but never attempted to deliver is not billed: besides the tenant-list and account-list bounces, a Reject (for example a virus) and a Permanent bounce with subtype
Suppressed (SES’s global suppression list, normalized as suppressionList global) write the reversal row. Suppression does not change: a Suppressed bounce suppresses like any hard bounce, and a Reject does not. Only the account list alerts.
- A Complaint with
complaintSubType OnAccountSuppressionList is SES’s report that it accepted a send and did not attempt it because the address is on the account’s suppression list. Nobody complained, so it normalizes as the account-list bounce does: hard_bounce with suppressionList account, so delivery status bounced, the charge reversed, the bounced:account_suppression_list alert, and no suppression. It never counts as a complaint.
| SES event (amended) |
Normalized type |
Effect |
Bounce, Permanent, subtype Suppressed |
hard_bounce, global |
delivery status bounced; address added to the workspace suppression list; charge reversed |
Complaint, subtype OnAccountSuppressionList |
hard_bounce, account |
as the OnAccountSuppressionList bounce: bounced; charge reversed; operator alert; no suppression |
| Reject |
reject |
delivery status content_rejected; charge reversed; no suppression |
- Open and Click events are not published. Click tracking is ours (ADR 0020), and open tracking is deferred.
EMAIL_PROVIDER selects fake (the default) or ses. With ses, these come from environment variables or platform secrets: SES_REGION, SES_ACCESS_KEY_ID, SES_SECRET_ACCESS_KEY, SES_CONFIGURATION_SET_TRANSACTIONAL, SES_CONFIGURATION_SET_MARKETING, and SES_EVENTS_SECRET; SES_ACCOUNT_ID is optional. A Worker has no startup step, so the configuration is validated when the app is built for a request. A missing value fails every request with a configuration error that names the variable, never its value, and sends nothing. apps/node refuses to start.
- Amended on 2026-11-15 by ADR 0037:
SES_REGION is the default of an allowlist, SES_REGIONS; each workspace’s provider tenant records its Region, and the adapter sends through it.
- The sending credentials need only
ses:SendEmail. Tenant and identity management uses other credentials and never runs on the send path, because the SES management API allows one request per second per account (ADR 0024).
- In cloud mode, a workspace without a provider tenant cannot send. Self-hosted installations may leave it empty and send without
TenantName.
- Specified on 2026-11-16, while building B4, without changing the decision; confirmed by the maintainer on 2026-11-16 (decided by the maintainer):
- “Cannot send” means the delivery consumer makes no provider call for a send context without a provider tenant, and records the attempt as
unavailable with providerReason provider_tenant_missing. The store requeues it as queued:provider_unavailable, the operator alert of an unavailable provider fires, and the message fails as failed:provider_unavailable if no tenant is replicated within 24 hours of its first attempt. A missing tenant is the operator’s setup, not the message’s, so it is not a terminal skip.
- With any provider but
fake, an APP_ORIGIN that is not https: is a configuration error, as ADR 0036 requires.
- While
EMAIL_PROVIDER names another provider, /provider-events/ses answers 503, which EventBridge retries for 24 hours before dead-lettering, instead of the 404 of an unknown provider, which it dead-letters at once. Events sent during a rollout are then delivered once ses is selected within the day, and wait in the dead-letter queue for replay after that. A provider name the Worker cannot wire stays 404. Outside cloud mode, switching a Worker with queued real messages back to fake is not a rollback: the fake provider would accept and bill them; the emergency stop pauses sending at SES or the deliveries queue instead.
- The managed service sends through SES only, enforced in code: in cloud mode, an unset or
fake EMAIL_PROVIDER wires a fake provider that sends nothing, records every send as unavailable with providerReason fake_in_cloud_mode (requeued, alerted, failed after 24 hours), and refuses its webhooks with 401, so no managed message is marked delivered or billed without SES. It is not a configuration error, so the API, one-click unsubscribe, and approval links stay up.
|
Managed |
Self-hosted |
| Provider |
SES, required |
fake or ses; another provider is another adapter behind the same port |
| Provider tenant |
one SES tenant per workspace, required |
optional |
| Sending domains |
provisioned by the operator, later by the domain API |
provisioned by the operator |
| Events |
EventBridge API destination |
the same, in the self-hoster’s AWS account; needs a public HTTPS endpoint |
| Billing on the Send event |
enforced |
recorded, not enforced |
A self-hosted installation that EventBridge cannot reach (behind NAT, for example) receives no events: unknown messages end as failed:outcome_unknown, and bounces and complaints do not reach suppression. The setup docs say so.
- With ADR 0033, real mail can be turned on by configuration. Setup docs list the IAM permission, the configuration sets with account-level suppression disabled, tenant-level suppression, the EventBridge destination, rule, connection, API destination, dead-letter queue and its alarm, and the DNS records, with placeholders only.
- Contract tests use recorded and anonymized SES responses and EventBridge events, and a stubbed
fetch; CI never calls AWS. An EmailProvider contract suite in testing/contracts runs on the fake and the SES adapters. A manual smoke test against the SES mailbox simulator in a sandbox account, which also records new fixtures, is in the setup docs.
- Changes to the message vocabulary in
core/src/messages/states.ts (the single owner of the state machine of ADR 0011): the skip reason sender_not_verified; the queued and failed reason provider_unavailable; the field providerReason; the delivery statuses soft_bounced and content_rejected. unknown reasons become the closed set lease_expired (the sending lease expired), adapter_error (the adapter threw instead of returning an outcome), and provider (the adapter returned unknown: a 5xx, timeout, connection error, or unreadable response), with the adapter’s label in providerReason. B1 makes this change and updates the comment on UnknownReason, which today allows any adapter label; the new field firstAttemptedAt comes with it.
- The
reversal ledger kind is used by suppression-list bounces, so the YAGNI follow-up to remove it in docs/architecture.md is withdrawn; the line is edited after PR #7 merges, to avoid a conflict.
- Resolves the SES event transport left open by ADR 0024 and the SES 5xx question in docs/architecture.md.
- Open:
- Resolving a 5xx
unknown sooner than 72 hours, for example by concluding “not accepted” when Send events for later attempts have arrived and this one has not. It would be a conditional resend under ADR 0007 and needs its own ADR with evidence from operation.
- Long-lived IAM user keys are the only credential a Worker can use without another service; moving to short-lived credentials is a later hardening.
- Bring-your-own SES credentials on the managed service, including how a workspace maps to another SES account (
provider_account_id, ADR 0024).
Amendment (2026-11-19, pending ADR 0046, Proposed): open tracking is no longer deferred, but it is ours (a pixel served by the tracker), so SES Open and Click events stay unpublished.