@kurtbruns/kestrel 1.18.0 → 1.20.0

package/docs/publishing/06-troubleshooting.md

@@ -1,18 +1,34 @@
 # Troubleshooting
 
-When something needs you, Kestrel says so in a line on the send's page, under **Sent**. The top of the dashboard shows it too. Red needs you to act, and amber is worth a look. The line says what happened, what to do, and who does it. This page covers what the screen can't: the fixes made outside Kestrel, and the decisions that are yours.
-
-**Set a notifications address, so a problem reaches you without your watching.** Set it under **Settings → Notifications**, in **Send notifications to**. With none set, Kestrel emails you nothing. [Notifications](06-troubleshooting.md#notifications), below, lists what you're told.
+When something needs you, Kestrel says so in a line on the send's page, under **Sent**. The top of the dashboard shows it too. Red needs you to act, and amber is worth a look. The line says what happened and what to do. This page covers what the screen can't: the fixes made outside Kestrel, and the decisions that are yours.
+
+**Set a notifications address, so a problem reaches you without your watching.** Set it under **Settings → Notifications**, in **Send notifications to**: type an address and choose **Add inbox**. Add the address of whoever runs your instance too, and both of you are told. With none set, Kestrel emails you nothing. [Notifications](#notifications), below, lists what you're told.
+
+| Symptom | Where the fix is |
+| --- | --- |
+| [A send is held or waiting](#a-send-is-held-or-waiting) | Usually outside Kestrel |
+| [Someone was mailed twice, or not at all](#someone-was-mailed-twice-or-not-at-all) | In Kestrel |
+| [A reader says they never got a post](#a-reader-says-they-never-got-a-post) | In Kestrel |
+| [A send still reads Settling](#a-send-still-reads-settling) | Nothing to fix, unless no receipts come at all |
+| [A test doesn't arrive](#a-test-doesnt-arrive) | Outside Kestrel |
+| [Signups aren't open yet, or are paused](#signups-arent-open-yet-or-are-paused) | In Kestrel, or outside it |
+| [The dashboard names a problem with your Amazon SES account](#a-problem-with-amazon-ses) | Outside Kestrel |
+| [An address bounced or complained](#an-address-bounced-or-complained) | Nothing to fix, unless you lift a suppression |
+| [A warning says to move to Workers Paid](../guides/09-as-your-list-grows.md) | Outside Kestrel |
+| [An import is refused](#an-import-is-refused) | In your file |
+| [Claude can't connect](#claude-cant-connect) | Usually outside Kestrel |
 
 ## A send is held or waiting
 
-Nothing is lost. A problem with your email provider never marks anyone unsent or mails anyone twice. The send waits where it is, and carries on once the problem is fixed. The send's line names the fix. When that fix is outside Kestrel, whoever runs your instance makes it, and it's one of these:
+Nothing is lost. A problem with your email provider never marks anyone unsent or mails anyone twice. The send waits where it is, and carries on once the problem is fixed. The send's line names the fix. When that fix is outside Kestrel, it's one of these:
 
 - **Amazon SES refuses your account or the send.** The line carries SES's words and the fix, almost always in the SES console. [Connect Amazon SES](../get-started/05-ses.md) sets up each piece SES checks: the sending domain, the AWS key, and the configuration set. [Request production access](../get-started/06-production-access.md) lifts the sandbox. When SES refuses your account, any other post that comes due meanwhile waits with it. When it refuses only this send's email, other posts go out as usual. While SES takes some readers and refuses the rest, as while a daily quota frees up, those it takes are sent. The line stays until SES takes everyone.
 - **SES keeps refusing for its sending rate.** Kestrel is sending faster than your SES account allows. **Settings → Email sender** shows the **Send rate** and where it comes from. If `SES_MAX_SEND_RATE` sets it, lower it to the maximum send rate on the SES console's account dashboard, or remove it, then deploy, as [Configuration](../reference/01-configuration.md#vars) describes. If it's Kestrel's default, the app can't read your account: allow its key `ses:GetAccount`, as [Connect Amazon SES](../get-started/05-ses.md#5-create-the-apps-aws-key) shows.
 - **No email provider is connected.** Connect one, as [Connect Amazon SES](../get-started/05-ses.md) describes, and the send goes out at its next retry.
 - **A send missed its time, or nothing has gone out for a while.** The part of Kestrel that sends has stopped, or keeps failing on this send. Check the Worker's Cron Trigger, as [Configuration](../reference/01-configuration.md#bindings-and-triggers) describes, and read the app's logs, as [Read the logs](../get-started/07-verify.md#7-read-the-logs) describes. If another send is going out at the same time, this one may only be waiting its turn.
 
+If someone else set up Kestrel for you, pass this along to them.
+
 ## Someone was mailed twice, or not at all
 
 Kestrel never mails a reader twice on its own. When it can't tell whether your provider took some emails, it stops and asks you: the send's page shows **Resolve…**. Choose **Assume not sent** unless you know otherwise, since it's the safe default: those readers may miss this post, but get your next one. Choose **Assume sent** only when you know they got it, such as from a reader who tells you so. Either choice mails no one.
@@ -27,17 +43,38 @@ Under **Subscribers**, search for their address and open their row. Their page l
 
 That's normal. **Delivered** counts only the emails your provider confirmed reached the reader's mail server. Confirmations can lag by days, so the counts keep rising after a send finishes. Some are never confirmed at all, so a send can read **Settling** for good, as long as some receipts have come.
 
-When none come, the send's page says so an hour after it went out. Your provider's reports aren't reaching Kestrel, so its bounces suppress no one and its complaints unsubscribe no one. Your next post mails those addresses again. Look for `webhook.refused` errors in the app's logs, as [Read the logs](../get-started/07-verify.md#7-read-the-logs) describes. Each names the SNS topic that reached Kestrel and the one it expects. Then check the subscription, as [Connect Amazon SES](../get-started/05-ses.md#7-subscribe-the-app-to-the-topic) describes.
+When none come, the send's page says so an hour after it went out. Your provider's reports aren't reaching Kestrel, so its bounces suppress no one and its complaints unsubscribe no one. Your next post mails those addresses again. Look for `webhook.refused` errors in the app's logs, as [Read the logs](../get-started/07-verify.md#7-read-the-logs) describes. Each names the SNS topic that reached Kestrel and the one it expects. Then check the subscription, as [Connect Amazon SES](../get-started/05-ses.md#7-subscribe-the-app-to-the-topic) describes. If someone else set up Kestrel for you, pass this along to them.
 
 ## A test doesn't arrive
 
-While Amazon SES is in its sandbox, it mails only addresses verified in SES. Verify the address you test with in the SES console, or [request production access](../get-started/06-production-access.md). When the test's line says the provider didn't answer, check the inbox before you send it again, since the first may have arrived. A test SES refuses for your account has the same fix as [a send it refuses](06-troubleshooting.md#a-send-is-held-or-waiting).
+While Amazon SES is in its sandbox, it mails only addresses verified in SES. Verify the address you test with in the SES console, or [request production access](../get-started/06-production-access.md). When the test's line says the provider didn't answer, check the inbox before you send it again, since the first may have arrived. A test SES refuses for your account has the same fix as [a send it refuses](#a-send-is-held-or-waiting). If someone else set up Kestrel for you, pass this along to them.
+
+## Signups aren't open yet, or are paused
+
+Your subscribe page takes signups only while email is working, so a reader is never told a link is coming when none can go. Every visitor gets the same page, whatever address they enter.
+
+- "Signups aren’t open yet" means SES hasn't sent an email for your publication yet. Send one from **Template → Send test email**, to an address verified in SES while it's in the sandbox. Once SES takes it, signups open. Before an email provider is connected, the page says the same, and [Connect Amazon SES](../get-started/05-ses.md) is the fix.
+- "Signups are paused" means SES is refusing your email, every email including confirmations and tests. The dashboard's **Email isn’t going out** line gives SES's words and the fix, as for [a problem with Amazon SES](#a-problem-with-amazon-ses). Then send a test email: once SES takes one, signups reopen.
+
+Kestrel notices a refusal when an email meets it, or within about ten minutes from its check of your SES account. A refusal the check found lifts on its own within about ten minutes of the fix; one an email met lifts when a test email goes through. A reader who signed up just as it started may have been told a link was coming, and can sign up again once signups reopen.
 
-## Your list outgrows Workers Free
+If someone else set up Kestrel for you, pass this along to them.
 
-Upgrade the Cloudflare account to Workers Paid, and set `SUBREQUEST_BUDGET` so Kestrel sends faster, as [As your list grows](../guides/09-as-your-list-grows.md) describes. Kestrel warns you before a send that could use up the free plan's daily database writes, which stops the app until midnight UTC. [Bring your existing list](01-your-list.md#limits) explains the limits.
+## A problem with Amazon SES
 
-## Bounces and complaints
+**Settings → Email sender** and the top of the dashboard name a problem with your Amazon SES account within about ten minutes, without sending anything. Red means no email can go out until it's fixed, tests and confirmations included. Amber is worth a look. Each line links the step that fixes it:
+
+- **The configuration set is missing, or its sending is off.** The set Kestrel sends with, the one `SES_CONFIGURATION_SET` names or the sending identity's default if that secret isn't set, isn't in your region, or its sending is turned off. Correct the name, or create the set, as [Connect Amazon SES](../get-started/05-ses.md#4-send-bounces-and-complaints-to-the-app) shows. Turn a set's sending back on in the SES console, under its configuration sets.
+- **SES rejects the AWS key.** The key ID is unknown, the secret doesn't match it, or the AWS account isn't signed up for SES. Store the key's ID and secret again, or create a new key, as [Connect Amazon SES](../get-started/05-ses.md#5-create-the-apps-aws-key) shows.
+- **The sender isn't verified.** SES has no verified identity for the From address in your region. Verify the sending hostname, as [Connect Amazon SES](../get-started/05-ses.md#1-verify-your-sending-hostname) shows.
+- **Sending is turned off for the account.** AWS documents turning it back on only with the AWS CLI, naming your region: `aws sesv2 put-account-sending-attributes --sending-enabled --region us-east-1`.
+- **AWS paused the account, or is reviewing it.** AWS does this when the account's bounce or complaint rate runs high. While it reviews, SES still sends, and the line is amber. Once it pauses sending, the line is red. Either way, AWS's email to the AWS account says what it needs: answer it in AWS Support, and check the addresses on your recent sends' records.
+
+The app needs to read each of these. If its key isn't allowed to, the line says nothing rather than guessing. The policy in [Connect Amazon SES](../get-started/05-ses.md#5-create-the-apps-aws-key) allows all of it.
+
+If someone else set up Kestrel for you, pass this along to them.
+
+## An address bounced or complained
 
 Kestrel acts on these for you, so a bad address can't keep hurting your sending reputation:
 
@@ -57,28 +94,40 @@ Nothing on your list changes. Kestrel refuses a file it can't read with certaint
 
 ## Claude can't connect
 
-Most failures are in your instance's Cloudflare Access setup, made by whoever runs your instance. [Connect Claude](08-connect-claude.md) covers connecting it. When that fails:
+[Connect Claude](08-connect-claude.md) covers connecting it. Most failures are in your instance's Cloudflare Access setup, and [Allow Claude to connect](../guides/01-allow-claude.md#check-it) lists their fixes. When connecting fails:
 
-- **Claude says it couldn't connect, or the sign-in failed.** Your instance's Access application needs Managed OAuth set up as [Turn on Managed OAuth](../guides/01-allow-claude.md#1-turn-on-managed-oauth) describes, including Claude's sign-in address for Claude Desktop and claude.ai. Check that the connector's address is your publication's address followed by `/api/mcp`, and that your instance is deployed, not running on your own computer.
-- `kestrel login` says your instance "doesn't offer a sign-in for programs". Managed OAuth is off. Turn it on, as the same section describes.
-- `kestrel login` or `kestrel api` reports a `401`. Access signed you in, but Kestrel refused the sign-in. If you set `ACCESS_ALLOWED_EMAILS`, check that it includes the address you signed in with. If either names `access_unidentified`, it's the next problem. If `kestrel api` says your sign-in has ended, sign in again as [Connect Claude](08-connect-claude.md#claude-code) describes.
-- **"Access let you in, but didn't say who you are".** Your login carried neither an email nor a service token. Some other kind of Access policy let it through, such as a certificate or device rule, or a login method that gives no email. Kestrel accepts only an Allow policy on people's emails and a Service Auth policy on a service token. Sign out, then sign in through the policy that lets you in by email. Whoever runs your instance removes the other policy from its Access application, or changes it to one of those two kinds. A script that gets this needs a service token under a Service Auth policy, as [Allow the token in](../guides/02-automate.md#2-allow-the-token-in) describes.
+- **Claude says it couldn't connect, or the sign-in failed.** Check that the connector's address is your publication's address followed by `/api/mcp`, and that your instance is deployed, not running on your own computer. If both are right, your instance's Access setup needs the fix.
+- Signing in shows `invalid_target`, or `kestrel login` says your instance "doesn't offer a sign-in for programs". Your instance's Access setup needs the fix.
+- `kestrel login` or `kestrel api` reports a `401`. Access signed you in, but Kestrel refused the sign-in, and your instance's Access setup needs the fix. If either names `access_unidentified`, it's the "Access let you in" problem below. If `kestrel api` says your sign-in has ended, sign in again as [Connect Claude](08-connect-claude.md#claude-code) describes.
+- `kestrel api` says it couldn't renew your sign-in because its Access team answered 404 (not found). First check which instance it called: when you don't name one, it prints a line naming it before "the only instance you're signed in to", which may not be the one you meant. Name yours with `--url`. If it is yours, the Access team domain was most likely renamed or removed since you signed in. Sign in again with `npx kestrel login` and your instance's address, which finds the team it uses now.
+- **"Access let you in, but didn't say who you are".** Your login carried neither an email nor a service token. Sign out, then sign in through the policy that lets you in by email. If you have no such policy, your instance's Access setup needs the fix.
 - **Claude's changes read "via the API".** Claude called the API some way other than `kestrel api`, which names Claude Code. Your instance's instructions for Claude Code have it use `kestrel api` once they're brought up to date, as [Install the release](../guides/07-upgrade.md#2-install-the-release) describes. Changes reading "a service token" mean Claude still uses one, and [Connect Claude](08-connect-claude.md#claude-code) signs it in as you instead.
 
-## Cloudflare won't save the Access application
+If someone else set up Kestrel for you, pass this along to them.
+
+## Where to look
+
+When a line doesn't settle it, these say the most about what happened:
 
-Whoever sets up your instance can meet this in [Lock the dashboard with Access](../get-started/03-access.md#2-create-the-access-application). Saving the application fails with an error naming `use_clientless_isolation_app_launcher_url`, saying it needs private destinations. The form has an empty private hostname or IP row beside the two public hostnames. Remove that row, and save again.
+- The top of the dashboard: what needs someone now, in Kestrel's own words.
+- The send's page, under **Sent**: what happened on that send, when it next retries, and its record of each reader.
+- **Settings → Email sender**: the state of your Amazon SES account, and your **Send rate**.
+- **Settings → Notifications**: **Last notification** says whether the last one was delivered, or why not.
+- A subscriber's page, under **Subscribers**: every send they were in, and what happened on each.
+- The app's logs, in your instance's Cloudflare account: [Read the logs](../get-started/07-verify.md#7-read-the-logs) describes them. If someone else set up Kestrel for you, pass this along to them.
 
 ## Notifications
 
 With an address set, Kestrel emails you:
 
-- when a send finishes, with how many emails were accepted, unsent, and skipped
-- when your provider refuses your account or a send, or no provider is connected
+- when a send finishes, with how many emails your provider accepted, and how late it went out if it did
+- when no one's email was accepted for a finished send, since it can't be sent again
+- when email isn't going out and signups are paused: once when it starts, and once more if a post is held after an email that named none
+- when your provider refuses a send or hits a limit, or no provider is connected
 - when the SES sandbox refuses a signup's confirmation, at most once a day
-- when a send stops going out with nothing to explain it, waits for you to resolve it, or misses its time
-- when a service token imports a list, since no one saw it happen (an import you make yourself, or through Claude, sends nothing)
+- when a send stops going out with nothing to explain it, waits for you to resolve it, or doesn't go out on time
+- when your provider has sent no receipts for six hours after a send, once until a receipt arrives
 
-Each links to the page it's about, and is sent once while the problem lasts. A bounce spike shows on the dashboard but isn't emailed. **Send a test notification** checks that one arrives.
+Each says whether anyone has to act, and how. If the fix needs whoever set up your instance, you can forward it as it stands. Each goes to every address set, links to the page it's about, and is sent once while the problem lasts. A reader's address in your provider's words shows only as its domain, and in full on the send's page. If one address can't be reached, the others still get it, and **Last notification** names the one that failed. A bounce spike shows on the dashboard but isn't emailed. **Send a test notification** checks that one arrives.
 
 By default, notifications go through your newsletter's own email provider. So when that provider refuses your account, the notification about it can't reach you either. You can send them another way, as [Notifications through Cloudflare's email](../guides/03-notifications.md) describes.

package/docs/publishing/08-connect-claude.md

@@ -14,7 +14,7 @@ How you connect depends on where you talk to Claude:
 1. In Claude, go to **Customize → Connectors**, select **Add**, then **Add custom connector**.
 1. Name it, and enter your publication's address followed by `/api/mcp`, such as `https://newsletter.example.com/api/mcp`.
 1. Under **OAuth client**, choose **Register automatically**.
-1. Select **Add**, then sign in the way you do for the dashboard, and approve the sign-in.
+1. Select **Add**, then **Connect**. Sign in the way you do for the dashboard if asked, and choose **Allow**.
 
 On a Team or Enterprise plan, an Owner of your Claude organization adds the connector under **Organization settings → Connectors** instead, and you then select **Connect** on it. Anthropic's [custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) has the details.
 

package/docs/publishing/09-share-your-subscribe-link.md

@@ -2,7 +2,9 @@
 
 Your publication's subscribe page is at `/subscribe` on your publication's address, such as `https://newsletter.example.com/subscribe`. Copy it from the dashboard's checklist or **Settings → Ways to subscribe**, and share it wherever your readers are. A reader joins only once they confirm by email.
 
-**Signups open only once an email provider is connected.** Until then, the page says the newsletter isn't taking subscribers yet, and the dashboard says so too. You can share the link anyway, and it opens once email is connected ([Connect Amazon SES](../get-started/05-ses.md)).
+**Signups open only once email is working.** Until an email provider is connected and has sent an email, such as a test from **Template → Send test email**, the page says the newsletter isn't taking subscribers yet. If your provider starts refusing your email, the page says signups are paused, and the dashboard says what to fix. Either way every visitor gets the same page and nothing is saved. You can share the link anyway, and it opens once email works ([Connect Amazon SES](../get-started/05-ses.md)).
+
+**On Amazon SES, share it once AWS grants production access.** Until then, SES mails only addresses verified in it, so a reader who signs up never gets their confirmation email. The dashboard's checklist and an empty **Subscribers** list say so, and link [Request production access](../get-started/06-production-access.md). Importing your list is safe meanwhile, since an import sends no email.
 
 ## How a reader joins
 

package/docs/publishing/10-check-your-setup.md

@@ -1,25 +1,29 @@
 # Check your setup
 
-Before your readers get anything, check three things yourself: your email arrives and replies reach you, subscribing works, and problems will reach you.
+Three checks before your readers get anything: is email getting out, will you hear about problems, and what will your readers get. The dashboard's setup steps tick each one off from what Kestrel sees, so you, and Claude, can tell what's left.
 
-**Email has to be connected first.** Until it is, nothing can be sent, and the dashboard's checklist shows **Connect Amazon SES** in place of this step, as [Connect Amazon SES](../get-started/05-ses.md) describes.
+**Email has to be connected first.** Until it is, nothing can be sent, and **Send a test email** waits on the dashboard's **Connect Amazon SES** step, which [Connect Amazon SES](../get-started/05-ses.md) covers.
 
-**Until AWS grants production access, Amazon SES mails only addresses verified in SES.** So test with a verified address, and hold the subscribe link until then. The checklist adds **Request production access** after this step, and checks it off once AWS grants it, as [Request production access](../get-started/06-production-access.md) describes.
+**Until AWS grants production access, Amazon SES mails only addresses verified in SES.** So test with a verified address, and hold the subscribe link until then. The dashboard's **Request production access** step says where AWS's review stands, and [Request production access](../get-started/06-production-access.md) covers the request.
 
-## 1. Send yourself a test
+## 1. Send a test email
 
-Choose **Template** in the sidebar, then **Send test email**, and send a sample post to your own inboxes. When it arrives, check:
+Choose **Template** in the sidebar, then **Send test email**, and send a sample post to your own inboxes. This is the test that proves email gets out: signups stay closed until SES takes an email, and the step is checked off once it does. When it arrives, check:
 
 - **The From name and address,** which readers see first. They're set when your instance is deployed.
 - **Where it lands:** the inbox, Promotions, or spam. If it lands in spam, check your sending domain's records, as [Sending-domain DNS](../reference/02-sending-domain-dns.md) describes.
 - **A reply.** Reply to the test, and check that it reaches your inbox. Kestrel never sees replies, so this depends on [forwarding your From address](../get-started/05-ses.md#8-receive-replies-at-your-from-address).
 
-## 2. Subscribe yourself
+If SES refuses the test, the dashboard says why in red above the steps, with what to check. Send another test once it's fixed.
 
-Open your subscribe page from **Settings → Ways to subscribe**, subscribe with a personal address, and confirm. You see what a new reader sees, and you appear under **Subscribers** as **Confirmed**.
+## 2. Get notified
+
+Under **Settings → Notifications**, add your address under **Send notifications to** with **Add inbox**, save, and choose **Send a test notification**. It goes to each address. If someone else runs your instance, add their address too, so a problem reaches both of you. Kestrel then emails you when a send finishes or needs you, as [Notifications](06-troubleshooting.md#notifications) lists. The step is checked off once an address is saved and the last notification arrived. If the last notification didn't arrive, the dashboard says so above the steps, with the channel's words.
 
-## 3. Set your notifications address
+## 3. See what your readers get
+
+Open your subscribe page from **Settings → Ways to subscribe**, subscribe with a personal address, and confirm. You see what a new reader sees, and you appear under **Subscribers** as **Confirmed**.
 
-Under **Settings → Notifications**, fill in **Send notifications to**, save, and choose **Send a test notification**. Kestrel then emails you when a send finishes or needs you, as [Notifications](06-troubleshooting.md#notifications) lists.
+Then, once your first post is scheduled, **Send a test email for your first post** from its page. Scheduling makes the exact email your list will get, so this test is what goes out, and the step is checked off once it's sent. A test sent from a draft is a preview and doesn't count, and a change to your template or publication identity re-makes the scheduled email, so the step opens again until you test the new one. [Write and send a post](04-write-a-post.md) covers scheduling.
 
 **If you're bringing more than about 1,000 subscribers, upgrade to Cloudflare's Workers Paid plan before you import.** [Bring your existing list](01-your-list.md#limits) explains why.

package/docs/publishing/11-email-template.md

@@ -26,7 +26,7 @@ A variable is replaced with its value in each email. Type it exactly as shown, o
 | `{{ .Publication.LogoURL }}` | Your logo's address, or empty. |
 | `{{ .Publication.Address }}` | Your mailing address, or empty. |
 | `{{ .Email.SentTo }}` | The address this email was sent to. |
-| `{{ .Email.UnsubscribeURL }}` | This reader's one-click unsubscribe link. Required. |
+| `{{ .Email.UnsubscribeURL }}` | This reader's unsubscribe link. Required. |
 | `{{ .Email.ViewInBrowserURL }}` | The post's own web link, which opens its page once it's sent, in your archive or not. |
 
 ## Test it

package/docs/publishing/README.md

@@ -4,12 +4,17 @@ These pages get you publishing in the dashboard, and cover the decisions to make
 
 ## Set up your publication
 
-These are the steps to set up your publication. If you're starting without a list, skip importing one.
+These are the dashboard's setup steps, in its order. Each is checked off from what Kestrel can see, which Claude reads too, except sharing your link, which Kestrel can't see. Connecting Amazon SES and requesting production access are for whoever runs your Kestrel instance, in [Connect Amazon SES](../get-started/05-ses.md) and [Request production access](../get-started/06-production-access.md). If you're starting without a list, skip importing one. Setup ends when your first post goes out to the archive, and an email-only send doesn't count.
 
+1. Connect Amazon SES
+1. [Send a test email](10-check-your-setup.md)
 1. [Name your publication](03-name-your-publication.md)
-1. [Check your setup](10-check-your-setup.md)
+1. Get notified
+1. Request production access
 1. [Bring your existing list](01-your-list.md)
-1. [Write and send a post](04-write-a-post.md)
+1. [Write your first post](04-write-a-post.md)
+1. Schedule your first post
+1. Send a test email for your first post
 1. [Share your subscribe link](09-share-your-subscribe-link.md)
 
 ## Go further

package/docs/reference/01-configuration.md

@@ -68,7 +68,7 @@ Vars go in the environment block's `vars`. Every value is a string.
 
 - `FROM_ADDRESS` required with a real provider
 
-    The `From:` of every email, and the identity your provider authenticates. Refused unless it's an email address, optionally with a display name in front, like `Name <address>`, and never on `example.com`, unless `PROVIDER` is `fake`.
+    The `From:` of every email, and the identity your provider authenticates. Refused unless it's an email address, optionally with a display name in front, like `Name <address>`, and never on `example.com`, unless `PROVIDER` is `fake`. With Amazon SES, when no identity covering it is verified for sending in `AWS_REGION`, **Settings → Email sender** says so in red within about ten minutes, without sending anything.
 
     It isn't the publication's name, tagline, or logo. You set those in the editor, under **Settings → Publication identity**. Until you do, the From address's display name stands in for the name, and with neither, the emails and reader pages show no name at all.
 
@@ -138,11 +138,11 @@ Store each with `npx wrangler secret put NAME --env production`, which prompts f
 
 - `ACCESS_ALLOWED_EMAILS` optional
 
-    A comma-separated list of the people allowed to sign in. Without it, the app lets in anyone the Access policy allows, so it keeps the editor limited to named people if the policy is widened later. It applies to people only. A service token, the credential a script uses, carries no email, so the Access policy alone decides whether it gets in.
+    A comma-separated list of the people allowed to sign in, such as `you@example.com, publisher@example.com`. Spaces and capital letters don't matter. Without it, the app lets in anyone the Access policy allows, so it keeps the editor limited to named people if the policy is widened later. It applies to people only. A service token, the credential a script uses, carries no email, so the Access policy alone decides whether it gets in.
 
 - `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` required with SES
 
-    The IAM user's access key, which sends through SES.
+    The IAM user's access key, which sends through SES. When SES rejects it, because the key ID is unknown, the secret doesn't match it, or the AWS account isn't signed up for SES, **Settings → Email sender** says so in red within about ten minutes, without sending anything.
 
 - `SNS_TOPIC_ARN` required with SES
 
@@ -150,7 +150,7 @@ Store each with `npx wrangler secret put NAME --env production`, which prompts f
 
 - `SES_CONFIGURATION_SET` optional, recommended with SES
 
-    The configuration set named on every email, so SES reports bounces and complaints. A name SES can't find in the region holds every list send until it's fixed.
+    The configuration set named on every email, so SES reports bounces and complaints. A name SES can't find in the region holds every list send until it's fixed. **Settings → Email sender** says so in red within about ten minutes, without sending anything, and does the same when the set's sending is turned off, as long as the app's key may call `ses:GetConfigurationSet`.
 
 - `DEV_AUTH_SECRET` never on a deployed environment
 
@@ -196,7 +196,7 @@ Wrangler doesn't carry bindings or vars over from the top level of `wrangler.jso
 
 ## What the app refuses
 
-The app checks its configuration on every request. It refuses to run on one that would do the wrong thing quietly, and each setting above says what it refuses. In local development, `SIMULATE_SENDS` must also be off (`off`, `0`, `false`, `no`, or empty), `not-connected` to run as a deployment with no email provider yet, or the provider a local send models: `ses` or `generic` (also `1`, `on`, `true`, or `yes`), optionally followed by `:none` for no injected failures or `:realistic`, the default. `SIMULATE_ACCOUNT` must be off, or, beside `SIMULATE_SENDS=ses`, the SES account state local development stands in for: `sandbox`, `pending`, `denied`, `production`, or `permission`, optionally followed by `:unrouted`. Case doesn't matter. A deployed instance ignores both.
+The app checks its configuration on every request. It refuses to run on one that would do the wrong thing quietly, and each setting above says what it refuses. In local development, `SIMULATE_SENDS` must also be off (`off`, `0`, `false`, `no`, or empty), `not-connected` to run as a deployment with no email provider yet, or the provider a local send models: `ses` or `generic` (also `1`, `on`, `true`, or `yes`), optionally followed by `:none` for no injected failures or `:realistic`, the default, and, for `ses`, by `:refuse=` and a cause SES refuses every email for (`credentials`, `opt_in`, `configuration`, `sender`, `mail_from`, `paused`, `set_paused`, `suspended`, or `unsupported`), as in `ses:refuse=configuration`. `SIMULATE_ACCOUNT` must be off, or, beside `SIMULATE_SENDS=ses`, the SES account state local development stands in for: `sandbox`, `pending`, `denied`, `production`, or `permission`, optionally followed by `:unrouted` or by one account problem, which shows its warning: `:set_missing`, `:set_paused`, `:key_rejected`, `:sending_disabled`, `:shutdown`, `:sender_unverified`, or `:probation`, as in `production:set_missing`. Case doesn't matter. A deployed instance ignores both.
 
 Until it's fixed, no sends go out, and each place says what its reader can act on:
 

package/migrations/0016_held_receipts.sql

@@ -0,0 +1,26 @@
+-- 0016_held_receipts: receipts that name a message the record has not yet learned (SPEC §10).
+--
+-- The send loop writes a recipient's provider message id when the provider answers the batch,
+-- and the provider can report a bounce, complaint, or delivery for that message before then. A
+-- receipt that names a message no delivery row holds yet, for an address with a recipient still
+-- in flight, is kept here (`provider_id`, the address, the event and its words, when it arrived,
+-- and `delivery_id`, the in-flight recipient it waits for) and applied to the record by the
+-- sweep once a row holds that id, or once the publisher resolves that recipient as sent; it
+-- lands on no other row. One that has waited a day is discarded. The list
+-- already acted on it when it arrived, so nothing here suppresses or unsubscribes anyone.
+--
+-- What can't be recovered: nothing. The table starts empty.
+
+CREATE TABLE held_receipts (
+  id          INTEGER PRIMARY KEY,
+  provider_id TEXT NOT NULL,
+  email       TEXT NOT NULL,
+  event       TEXT NOT NULL CHECK (event IN ('delivered', 'bounced', 'complained')),
+  detail      TEXT,
+  hard        INTEGER CHECK (hard IN (0, 1)),
+  at          INTEGER NOT NULL,
+  delivery_id INTEGER NOT NULL
+) STRICT;
+
+-- Erasure discards an address's held receipts by address.
+CREATE INDEX idx_held_receipts_email ON held_receipts (email);

package/migrations/0017_provider_account_rejected.sql

@@ -0,0 +1,24 @@
+-- 0017_provider_account_rejected: an account check whose key SES rejects (SPEC §13).
+--
+-- The account check used to file a key SES doesn't know, a secret that doesn't match, and an
+-- account not signed up for SES as `unreachable`, the same as no answer, so a dead key read
+-- as "can't tell" and was found only by sending. It is now its own outcome, `rejected`.
+-- `provider_account.outcome`'s CHECK doesn't admit it and a STRICT table's CHECK can't be
+-- altered, so the table is rebuilt with `rejected` added, its one row carried over.
+--
+-- What can't be recovered: nothing. The row is copied as it was.
+
+CREATE TABLE provider_account_next (
+  id           INTEGER PRIMARY KEY CHECK (id = 1),
+  attempted_at INTEGER NOT NULL,
+  outcome      TEXT NOT NULL CHECK (outcome IN ('ok', 'permission', 'rejected', 'unreachable')),
+  checked_at   INTEGER,
+  answer       TEXT CHECK (answer IS NULL OR json_valid(answer)),
+  CHECK ((checked_at IS NULL) = (answer IS NULL))
+) STRICT;
+
+INSERT INTO provider_account_next (id, attempted_at, outcome, checked_at, answer)
+  SELECT id, attempted_at, outcome, checked_at, answer FROM provider_account;
+
+DROP TABLE provider_account;
+ALTER TABLE provider_account_next RENAME TO provider_account;

package/migrations/0018_notify_addresses.sql

@@ -0,0 +1,13 @@
+-- 0018_notify_addresses: notifications go to one or more addresses (SPEC §8).
+--
+-- Each address is its own delivery: `sent_to` holds the addresses a notification has reached,
+-- as a JSON array, so a try after one address failed goes only to the ones still missing it,
+-- never again to one that got it. Every row starts with none: one still pending reached no
+-- address, since it had only the one, and one that is closed is never tried again.
+--
+-- The saved address itself needs no migration: the settings blob is read through code, which
+-- takes a stored single address as a list of that one (`src/db/settings.ts`).
+--
+-- What can't be recovered: nothing. The column is added to every row.
+
+ALTER TABLE notifications ADD COLUMN sent_to TEXT NOT NULL DEFAULT '[]' CHECK (json_valid(sent_to));

package/migrations/0019_sending.sql

@@ -0,0 +1,67 @@
+-- 0019_sending: whether email is getting out (SPEC §13).
+--
+-- One row, written whenever the provider answers a test, a confirmation, a list send, or a
+-- notification, and by the account check: `unproven` until the provider takes an email,
+-- `working` while the last one it was asked to take it took, `refusing` while it refuses the
+-- account for a reason that won't clear on its own. `since` is when it entered that state.
+-- The last email taken (`last_accepted_at`, and what it was, `last_accepted_by`) is kept
+-- across a refusal, so the editor can say when the provider last took one. A refusal keeps
+-- its cause, what found it, and the provider's words, never a reader's address. Every write
+-- carries when the provider gave its answer (`observed_at` keeps the newest applied), and none
+-- replaces a newer one: a sweep that met a refusal before the operator's fix can't undo the
+-- test that proved it.
+--
+-- `check_contradicted` lists the causes the account check found that an email the provider
+-- took has since contradicted: a reading that stays wrong while email goes out, such as a
+-- sender verified through another account's sending authorization, pauses signups once and
+-- not again. A clean reading empties it.
+--
+-- The row starts as `working` when the app's own records show email went out: a send the
+-- provider took a recipient of, or a subscriber who confirmed through a link this instance
+-- mailed. So an instance that was live before this release keeps its signups open. A test
+-- leaves no record and so counts for nothing here; the next one sets it. A delivered
+-- notification counts for nothing either, since it may have gone through Cloudflare's email
+-- rather than the provider. The provider's own 24-hour count is never read: it is zero on a
+-- quiet day.
+--
+-- What can't be recovered: nothing. The table is new.
+
+CREATE TABLE sending (
+  id               INTEGER PRIMARY KEY CHECK (id = 1),
+  state            TEXT NOT NULL CHECK (state IN ('unproven', 'working', 'refusing')),
+  since            INTEGER NOT NULL,
+  observed_at      INTEGER NOT NULL,
+  last_accepted_at INTEGER,
+  last_accepted_by TEXT CHECK (last_accepted_by IN ('test', 'confirmation', 'list', 'notification')),
+  refusal_cause    TEXT
+                     CHECK (refusal_cause IN ('credentials', 'opt_in', 'configuration', 'sending_pool', 'sender',
+                                              'mail_from', 'paused', 'set_paused', 'suspended', 'unsupported')),
+  refusal_found_by TEXT
+                     CHECK (refusal_found_by IN ('test', 'confirmation', 'list', 'notification', 'account_check')),
+  refusal_error    TEXT,
+  refusal_at       INTEGER,
+  check_contradicted TEXT NOT NULL DEFAULT '[]' CHECK (json_valid(check_contradicted)),
+  CHECK ((last_accepted_at IS NULL) = (last_accepted_by IS NULL)),
+  CHECK ((state = 'refusing') = (refusal_cause IS NOT NULL)),
+  CHECK ((refusal_cause IS NULL) = (refusal_found_by IS NULL)),
+  CHECK ((refusal_cause IS NULL) = (refusal_at IS NULL)),
+  CHECK (state <> 'working' OR last_accepted_at IS NOT NULL)
+) STRICT;
+
+INSERT INTO sending (id, state, since, observed_at, last_accepted_at, last_accepted_by)
+  SELECT 1,
+         CASE WHEN at IS NULL THEN 'unproven' ELSE 'working' END,
+         COALESCE(at, CAST(unixepoch('subsec') * 1000 AS INTEGER)),
+         COALESCE(at, 0),
+         at,
+         CASE WHEN at IS NULL THEN NULL ELSE by END
+  FROM (
+    SELECT at, by FROM (
+      SELECT MAX(updated_at) AS at, 'list' AS by FROM deliveries WHERE status = 'accepted'
+      UNION ALL
+      SELECT MAX(confirm_sent_at), 'confirmation' FROM subscribers
+        WHERE status = 'confirmed' AND confirm_sent_at IS NOT NULL AND import_id IS NULL
+    )
+    ORDER BY at IS NULL, at DESC
+    LIMIT 1
+  );

package/migrations/0020_notifications_not_sending.sql

@@ -0,0 +1,40 @@
+-- 0020_notifications_not_sending: tell the publisher when email isn't going out (SPEC §8).
+--
+-- When the provider refuses the account outside a send, or the account check finds a refusal
+-- before anything is sent, nobody is there to see it, so the publisher hears of it through the
+-- notifications they already get, as a `not_sending` notice with no send and no import, at
+-- most one a UTC day: its episode is the day's start, and the partial unique index keeps one
+-- row a day, as the `sandbox` notice does. `notifications.kind`'s CHECK doesn't admit it and a
+-- STRICT table's CHECK can't be altered, so the table is rebuilt with `not_sending` added,
+-- every row and column carried over, `sent_to` and its check included, so a notification that
+-- has reached some of its addresses never mails them again.
+--
+-- What can't be recovered: nothing. Every row is copied as it was.
+
+CREATE TABLE notifications_next (
+  send_id    TEXT REFERENCES sends (id),       -- null for a test, an import notice, and an account notice
+  import_id  TEXT REFERENCES imports (id),     -- set only for an import notice
+  kind       TEXT NOT NULL
+               CHECK (kind IN ('finished', 'refused', 'stuck', 'wedged', 'missed', 'test', 'import', 'sandbox', 'not_sending')),
+  episode    INTEGER NOT NULL DEFAULT 0,
+  status     TEXT NOT NULL DEFAULT 'pending'
+               CHECK (status IN ('pending', 'sent', 'failed', 'unaddressed', 'cleared')),
+  attempts   INTEGER NOT NULL DEFAULT 0,
+  error      TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  sent_to    TEXT NOT NULL DEFAULT '[]' CHECK (json_valid(sent_to)),
+  UNIQUE (send_id, kind, episode),
+  UNIQUE (import_id),
+  CHECK ((send_id IS NULL) = (kind IN ('test', 'import', 'sandbox', 'not_sending'))),
+  CHECK ((import_id IS NULL) = (kind <> 'import'))
+) STRICT;
+
+INSERT INTO notifications_next (send_id, import_id, kind, episode, status, attempts, error, created_at, updated_at, sent_to)
+  SELECT send_id, import_id, kind, episode, status, attempts, error, created_at, updated_at, sent_to FROM notifications;
+
+DROP TABLE notifications;
+ALTER TABLE notifications_next RENAME TO notifications;
+CREATE INDEX idx_notifications_status ON notifications (status, created_at);
+CREATE UNIQUE INDEX idx_notifications_sandbox_day ON notifications (episode) WHERE kind = 'sandbox';
+CREATE UNIQUE INDEX idx_notifications_not_sending_day ON notifications (episode) WHERE kind = 'not_sending';

package/migrations/0021_notifications_outage_receipts.sql

@@ -0,0 +1,46 @@
+-- 0021_notifications_outage_receipts: one outage, at most two emails, and a notice of silence (SPEC §8).
+--
+-- `not_sending` is now one notice for each stretch email is refusing rather than one a UTC day:
+-- its episode is when the refusal began. A second kind, `not_sending_held`, keyed the same way,
+-- is the one further email when a post is first held after that notice named none, so a unique
+-- index on each kind's episode is what holds an outage to two. `no_receipts` is a send's notice
+-- that the provider's receipts may not be reaching the app. The publisher is no longer told of
+-- an import, so a pending `import` notice is closed as cleared rather than sent; the kind stays
+-- admitted, with the column it reads, since the rows already recorded keep their history and the
+-- settings surface may still show the latest. A STRICT table's CHECK can't be altered, so the
+-- table is rebuilt, every row and column carried over.
+--
+-- What can't be recovered: nothing but the pending import notices, which were only ever going
+-- to tell of an import already on the record.
+
+CREATE TABLE notifications_next (
+  send_id    TEXT REFERENCES sends (id),       -- null for a test, an import notice, and an account notice
+  import_id  TEXT REFERENCES imports (id),     -- set only for an import notice
+  kind       TEXT NOT NULL
+               CHECK (kind IN ('finished', 'refused', 'stuck', 'wedged', 'missed', 'no_receipts', 'test', 'import', 'sandbox', 'not_sending', 'not_sending_held')),
+  episode    INTEGER NOT NULL DEFAULT 0,
+  status     TEXT NOT NULL DEFAULT 'pending'
+               CHECK (status IN ('pending', 'sent', 'failed', 'unaddressed', 'cleared')),
+  attempts   INTEGER NOT NULL DEFAULT 0,
+  error      TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  sent_to    TEXT NOT NULL DEFAULT '[]' CHECK (json_valid(sent_to)),
+  UNIQUE (send_id, kind, episode),
+  UNIQUE (import_id),
+  CHECK ((send_id IS NULL) = (kind IN ('test', 'import', 'sandbox', 'not_sending', 'not_sending_held'))),
+  CHECK ((import_id IS NULL) = (kind <> 'import'))
+) STRICT;
+
+INSERT INTO notifications_next (send_id, import_id, kind, episode, status, attempts, error, created_at, updated_at, sent_to)
+  SELECT send_id, import_id, kind, episode,
+         CASE WHEN kind = 'import' AND status = 'pending' THEN 'cleared' ELSE status END,
+         attempts, error, created_at, updated_at, sent_to
+    FROM notifications;
+
+DROP TABLE notifications;
+ALTER TABLE notifications_next RENAME TO notifications;
+CREATE INDEX idx_notifications_status ON notifications (status, created_at);
+CREATE UNIQUE INDEX idx_notifications_sandbox_day ON notifications (episode) WHERE kind = 'sandbox';
+CREATE UNIQUE INDEX idx_notifications_not_sending ON notifications (episode) WHERE kind = 'not_sending';
+CREATE UNIQUE INDEX idx_notifications_not_sending_held ON notifications (episode) WHERE kind = 'not_sending_held';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurtbruns/kestrel",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "type": "module",
   "description": "An open-source, self-hosted newsletter app where you own the list and the archive. Work in the editor, or just ask Claude. Runs on Cloudflare Workers.",
   "license": "MIT",

package/packages/kestrel/lib/api.mjs

@@ -52,7 +52,7 @@ const USAGE = `Usage: kestrel api <method> <path> [options]
   --data <json|@file|->         the request body: inline, from a file, or from stdin
   --type <media type>           the body's type (default application/json)
   --form <name=value>           a multipart field, repeatable; name=@file attaches a file
-  --url <url>                   the instance (default: KESTREL_URL, else your one sign-in)
+  --url <url>                   the instance (default: KESTREL_URL, else the only one you're signed in to)
   --local                       this directory's dev server, started by kestrel dev
   --client <name>               your own script's Kestrel-Client name (default ${DEFAULT_CLIENT});
                                 never editor, which only the editor names itself
@@ -182,8 +182,15 @@ export function parseApiArgs(argv) {
 /**
  * Which instance a call goes to: `--url`, then `KESTREL_URL`, then the one instance this
  * person is signed in to. Several sign-ins and nothing naming one is a refusal, not a guess.
+ * The one sign-in is named on stderr through `say`, since nothing in the command named it and
+ * a person in another instance's folder should see the mismatch; stdout stays the answer's.
  */
-export function chooseInstance({ url, env = process.env, signIns }) {
+export function chooseInstance({
+  url,
+  env = process.env,
+  signIns,
+  say = (line) => process.stderr.write(`${line}\n`),
+}) {
   if (url) {
     return instanceOrigin(url);
   }
@@ -192,6 +199,9 @@ export function chooseInstance({ url, env = process.env, signIns }) {
   }
   const origins = Object.keys(signIns);
   if (origins.length === 1) {
+    say(
+      `kestrel api: calling ${origins[0]}, the only instance you're signed in to. Pass --url to call a different one.`,
+    );
     return origins[0];
   }
   if (origins.length === 0) {
@@ -280,9 +290,24 @@ export async function accessToken(origin, { force = false, env = process.env } =
       writeSignInHeld(origin, { ...now, ...fields }, env);
       return fields.access_token;
     } catch (err) {
-      if (err instanceof SignInError && err.oauthError === "invalid_grant") {
+      if (!(err instanceof SignInError)) {
+        throw err;
+      }
+      if (err.oauthError === "invalid_grant") {
         throw new SignInError(ended);
       }
+      // The token endpoint saved at sign-in wasn't found; signing in again discovers where the
+      // instance signs in now. It says what happened, not why: a renamed team domain and a
+      // moved endpoint both answer 404.
+      if (err.status === 404) {
+        const team = new URL(now.token_endpoint).host;
+        throw new SignInError(
+          `Couldn't renew your sign-in to ${origin}: its Access team, ${team}, answered 404 (not found). Run \`npx kestrel login ${origin}\` again.`,
+        );
+      }
+      if (err.status) {
+        throw new SignInError(`Access refused the token request for ${origin} (${err.detail}).`);
+      }
       throw err;
     }
   }, env);