@kurtbruns/kestrel 1.11.0 → 1.12.0

package/docs/get-started/04-ses.md

@@ -107,7 +107,11 @@ If AWS asks for more detail, reply in the support case. If it denies the request
 - Bounces and complaints reach the app through SNS, and it stops mailing those addresses automatically.
 - How many subscribers the newsletter expects, and how often it sends.
 
-Your account stays in the sandbox until AWS grants access, so don't go live before then. In the sandbox, a signup from any address you haven't verified fails, and a post reaches only your verified addresses.
+Your account stays in the sandbox until AWS grants access, so don't go live before then. In the sandbox, SES refuses mail to any address you haven't verified:
+
+- A signup from an unverified address gets no confirmation email. The app emails the publisher about it, at most once a day.
+- A post goes to your verified addresses and then waits, with the line "The provider is refusing the account" and SES's words. No reader is marked unsent. Once AWS grants access, the post goes to the rest at its next retry, mailing no one twice.
+- A daily quota refusal in the sandbox (200 emails a day) means the same thing: request production access rather than a higher quota.
 
 When AWS grants access, the **Account dashboard** shows your daily quota and your maximum send rate. You set the rate in the app in section 8. The rate decides how fast a send goes out, and [As your list grows](../guides/09-as-your-list-grows.md) says when to ask AWS to raise it.
 
@@ -256,10 +260,26 @@ SNS delivers events only to a subscriber that has confirmed. The app confirms on
 
 1. Reload the subscription. Its status changes to **Confirmed**, with nothing for you to click.
 
+1. Give SNS longer to retry. By default it retries a failed delivery 3 times over about a minute, then discards the event, so a bounce that arrives while the app is briefly down or mid-deploy is lost, and the address gets your next post. Open the topic, choose **Edit**, and expand **Delivery policy (HTTP/S)**. Clear **Use the default delivery policy**, set these, and choose **Save changes**:
+
+    | Field | Value |
+    | --- | --- |
+    | Number of retries | `13` |
+    | Retries without delay | `0` |
+    | Minimum delay | `20` |
+    | Minimum delay retries | `2` |
+    | Maximum delay | `300` |
+    | Maximum delay retries | `6` |
+    | Retry-backoff function | Exponential |
+
+    SNS then keeps trying for most of an hour, the longest it allows. It never retries an event the app refused. The app refuses only an event it can't verify came from your topic, and logs an error when one claims to be from SNS.
+
+1. **(Optional)** Keep what SNS still can't deliver. On the subscription, choose **Edit**, and set a **Redrive policy (dead-letter queue)** to an SQS queue of your own. SNS then moves an event there instead of discarding it, where you can read it later. [Amazon SNS dead-letter queues](https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html) covers the queue and its permissions.
+
 If it stays **Pending confirmation**, the request never reached the app, or the app refused it. Check, in this order:
 
 - **Access covers `/webhooks/ses`.** If your Access application covers more than `/dashboard` and `/api`, SNS gets the login page instead of the app. Remove that path from your Access application, so only `dashboard` and `api` remain.
-- **`SNS_TOPIC_ARN` matches the topic's ARN.**
+- **`SNS_TOPIC_ARN` matches the topic's ARN.** If it doesn't, the app's logs show a `webhook.refused` error naming both.
 - **The deploy in section 8 finished.**
 
 Once you've fixed the cause, select the subscription, and choose **Request confirmation**. SNS sends the request again, and the app confirms it. SNS doesn't let you delete a subscription while it's pending, and removes it on its own after 48 hours.

package/docs/get-started/05-verify.md

@@ -2,7 +2,7 @@
 
 Some things only show up with real email: whether inboxes trust your mail, how it looks in a real mail client, and whether bounces and unsubscribes come back to the app. Check them now, while the list is empty and every email goes only to you.
 
-In this guide, you send yourself a test email, reply to it, and check that it passes authentication. Then you set up notifications, send a real post to yourself as a subscriber, and unsubscribe. Finally, you check that bounces and complaints reach the app, read the app's logs, and check that SES can send to anyone.
+In this guide, you send yourself a test email, reply to it, and check that it passes authentication. Then you set up notifications, send a real post to yourself as a subscriber, and unsubscribe. Finally, you check that bounces and complaints reach the app, read the app's logs, check that SES can send to anyone, and clean up the test subscribers.
 
 ## Before you begin
 
@@ -59,10 +59,14 @@ This is a real send, to a list of one. It proves the whole path: subscribing, co
 
 1. Open the post, select **Schedule**, and then **Send now**. Every send waits at least five minutes before it goes out, so you can cancel a mistake.
 
-1. Cancel the send, to see that canceling stops it. Then select **Send now** again, and let it go.
+1. Uncheck **Include in archive**. The post still goes to subscribers, but it's sent as email only: it isn't in the public archive or on the home page. That way the test proves the send without becoming the publication's first archived post, and the dashboard keeps its **Finish setting up** steps for the publisher.
+
+1. Cancel the send, to see that canceling stops it. Then select **Schedule** and **Send now** again, check that **Include in archive** is still unchecked, and let it go.
 
 1. When the send finishes, the post arrives at your second address. A notification arrives at your first, with the subject `Sent:` and the post's title.
 
+If you verified this instance before Email only existed, the test post is in the archive. Open it under **Sent**, and select **Remove from archive…**.
+
 ## 5. Unsubscribe
 
 Every email carries an unsubscribe link, and a header that lets mail clients show their own **Unsubscribe** button. Both work in one step, with no login.
@@ -108,6 +112,18 @@ The app writes a log line for each thing it does, and Cloudflare keeps them for
 
 If the dashboard still says sandbox, AWS hasn't answered yet. Every other section works in the sandbox, so come back to this one when it does.
 
+## 9. Clean up the test subscribers
+
+The checks leave test addresses on the list. Erase them, so the publisher starts with only real readers.
+
+1. In the editor, open **Subscribers**.
+
+1. Erase `bounce@simulator.amazonses.com` and `complaint@simulator.amazonses.com`. Open each one's menu (⋯), and select **Erase**.
+
+1. Erase your second address too, if it won't be a reader.
+
+Erasing keeps a do-not-contact marker, but the person can subscribe again through the subscribe page. Erasing your own address doesn't lock you out.
+
 When every section gives the result it describes, your instance is ready for subscribers.
 
 Next, [go live](06-go-live.md).

package/docs/get-started/06-go-live.md

@@ -4,7 +4,7 @@ At this point, your instance should be deployed, verified, and out of the SES sa
 
 ## Start publishing
 
-The rest happens in the editor, at `https://newsletter.example.com/dashboard/`. The Publishing docs walk through it in the order of the dashboard's setup checklist, starting with [Name your publication](../publishing/03-name-your-publication.md). The checklist itself shows only until the first post exists, so the test post from [Verify it works](05-verify.md) has already hidden it.
+The rest happens in the editor, at `https://newsletter.example.com/dashboard/`. The Publishing docs walk through it in the order of the dashboard's setup checklist, starting with [Name your publication](../publishing/03-name-your-publication.md).
 
 If someone else is the publisher, let them sign in first:
 

package/docs/guides/01-connect-claude.md

@@ -86,9 +86,11 @@ To bring subscribers over from another service, ask Claude to import the list, a
 1. Ask Claude to call `GET /api/whoami`. The app answers with a program's identity, not yours:
 
     ```
-    {"principal":{"kind":"service"},"auth":{"mode":"access"}}
+    {"principal":{"kind":"service","tokenId":"e367c0ffee5eb4.access"},"auth":{"mode":"access"}}
     ```
 
+    The `tokenId` is the Client ID Zero Trust shows beside `kestrel-claude`. If it's a different one, Claude Code is using another token.
+
 1. Ask Claude to list the posts. It answers with the posts the editor shows.
 
 1. Open a draft in the editor, and ask Claude to change a word in it. The editor shows that the draft was changed elsewhere, last edited by **Claude**.

package/docs/publishing/04-write-a-post.md

@@ -13,11 +13,11 @@ A few things to know as you write:
 - **A blank line starts a new paragraph.** In an email, a single line break doesn't.
 - **The opening lines** are the preview a mail client shows beside the subject.
 - **Images** go in by paste or drop, and Kestrel inserts a reference by file name, such as `![cover.jpg](cover.jpg)`. Replace the words in brackets with a short description. PNG, JPEG, WebP, or GIF, up to 5 MB each.
-- **The subject** sets the post's slug, the end of its permanent archive address, such as `newsletter.example.com/archive/spring-update`. The slug is fixed once you schedule.
+- **Where it will go** is in **Post settings**, at the top right: whether it's in your archive, and its address, such as `newsletter.example.com/archive/spring-update`, whose slug follows the subject (below).
 
 ## Test it
 
-**Send test email** sends the real email, through the same template and code as the send, to the addresses you name. **Settings → Default test recipients** fills them in for you. Nobody on your list gets anything, and a test's unsubscribe link unsubscribes no one.
+**Send test email** sends the real email, through the same template and code as the send, to the addresses you name. **Settings → Default test recipients** fills them in for you. Nobody on your list gets anything, nothing appears in your archive, and a test's unsubscribe link unsubscribes no one.
 
 Mail clients each draw email a little differently, so trust a test over **Preview**, especially for tables, code, and HTML. A test needs an email provider, which [Connect Amazon SES](../get-started/04-ses.md) sets up.
 
@@ -33,9 +33,23 @@ Changing your template, or a publication detail it shows, re-makes the email of
 
 **Send now →**, under the time picker, is for a post you've already reviewed. It still waits out the window, scheduling the post for the minimum lead from now.
 
+### Post settings
+
+**Post settings**, at the top right of the editor, holds two choices. Neither is part of the email, so both stay open while the post is scheduled. Nothing changes until you select **Save**.
+
+**Include in archive** is checked unless you uncheck it. Unchecked, the post goes to your list as usual but is sent as email only: it stays off your public archive and your home page, and its archive address shows nothing. Use that for a post meant for the inbox: a correction to an earlier email, a short-lived notice, or a test. The editor marks such a post **Email only**.
+
+**Archive address** is where the post's page will be in your archive. Only the last part, the slug, is yours to type; it follows the subject until you do. Each post's address is its own: if you type one another post has, or one with spaces or capitals, Kestrel says so and keeps the address as it was. If another post already has the address your subject would give, Kestrel adds a number (`spring-update-2`) and tells you, so you can choose another. The address is fixed once the post starts sending.
+
+The Schedule, Send now, and Edit schedule dialogs show the same settings under the time, so you can still change them there. A change made in a dialog applies when you schedule, send, or save, and canceling leaves the post as it was. Once a post is scheduled, its banner names where it's going.
+
+Every email links its web version through the post's own **unlisted link**, which never changes. It opens the archive page while the post is in your archive, and the page itself while it's email only. Anyone with the email can open it, but nothing lists it, and search engines are asked not to.
+
+A sent post's page under **Sent** shows its address with **Remove from archive…** or **Add to archive…**. Both ask first. Removing a post takes its archive address down, so links people shared stop working, but the address stays the post's: add it back and those links work again. Neither changes what was sent.
+
 ### Changing your mind
 
-**Cancel**, on the post's banner or its card under **Sent**, makes the post a draft again at once. Edit it, test again, and schedule it again. **Reschedule** moves the send time without unlocking the post, and your tests still count. You can do either until the send time.
+**Cancel**, on the post's banner or its card under **Sent**, makes the post a draft again at once. Edit it, test again, and schedule it again. **Edit schedule** changes the send time, whether the post is in your archive, or both, without unlocking the post, and your tests still count. You can do either until the send time.
 
 ### Who receives it
 
@@ -50,6 +64,6 @@ So a recipient count shown before the send is a snapshot. An import that adds su
 
 ### When it sends
 
-At the send time, the post moves to its send page under **Sent**, where you can watch it go out. From then it can't be edited, canceled, or moved. Its archive page goes up at the same moment, showing exactly the copy that was sent, so every email's "view in browser" link works. Whatever interrupts a send, such as your provider's daily quota running out, it waits and resumes where it stopped. No reader gets the same post twice.
+At the send time, the post moves to its send page under **Sent**, where you can watch it go out. From then it can't be edited, canceled, or moved. Its page goes up at the same moment, showing exactly the copy that was sent, so every email's "view in browser" link works. Whatever interrupts a send, such as your provider's daily quota running out, it waits and resumes where it stopped. No reader gets the same post twice.
 
 If a send needs your attention, the send page and the dashboard say so. [Troubleshooting](06-troubleshooting.md) covers each case.

package/docs/publishing/06-troubleshooting.md

@@ -6,17 +6,21 @@ When a send needs you, its page and the dashboard's health block say so in a red
 
 ## A send is waiting or held
 
-A problem with your email provider never marks anyone unsent. The send waits where it is, and carries on from there once the problem clears.
+A problem with your email provider never marks anyone unsent. The send waits where it is, and carries on from there once the problem clears. "No one has been marked unsent because of this" means this problem: readers whose own email failed earlier stay unsent.
 
-- **"The provider is refusing the account".** Your provider won't take mail from your account, and its own words follow, with the fix they point to. The fix is almost always in your Amazon SES account or Kestrel's deployment, and the message names it. A spent daily sending quota frees up within a day, and you can ask AWS for a higher one, as [As your list grows](../guides/09-as-your-list-grows.md) describes.
+- **"The provider is refusing the account".** Your provider won't take mail from your account, and its own words follow, with the fix and who makes it. The fix is almost always in your Amazon SES account or Kestrel's deployment, made by whoever runs it. [What SES refuses, and the fix](#what-ses-refuses-and-the-fix), below, lists each one. Any other post that comes due meanwhile waits with it, without asking SES, and you're told once. While a quota frees up a few at a time, or while the SES sandbox takes only your verified addresses, SES takes some readers on each retry and refuses the rest: those it takes are sent, and the line stays, with the time it began, until SES takes everyone it's asked to.
+- **"The provider is refusing this send".** SES refuses this post's email itself, or a batch of it as invalid, rather than your account. Its words follow. Other posts go out as usual. If SES's words name a reader's address, remove that subscriber: the send skips them and carries on at its next retry. If SES refuses the email itself, the email can't change once its send has started, so whoever runs the deployment asks AWS Support why, quoting SES's words.
 - **"No email provider is connected".** The send is held until one is connected ([Connect Amazon SES](../get-started/04-ses.md)), and goes out once it is.
-- **"The provider is unavailable".** An outage or a rate limit on the provider's side. The send retries on its own, so there's nothing to do.
-- **"Still sending … after it started".** A send is taking longer than expected, and may be retrying. If the line stays, read the app's logs, as [Read the logs](../get-started/05-verify.md#7-read-the-logs) describes.
+- **"The provider is unavailable".** An outage or a rate limit on the provider's side. The send reads **Backing off** and says when it next retries, spacing its retries out up to an hour apart while the outage lasts, so there's nothing to do. Any other post that comes due meanwhile waits with it.
+- **"The provider keeps refusing for its sending rate".** An amber line. SES has refused the first request of several retries in a row for its sending rate, which a short burst never does, so Kestrel is set to send faster than your SES account allows. Whoever runs the deployment sets `SES_MAX_SEND_RATE` to the **Maximum send rate** on the SES console's **Account dashboard** (1 a second in the sandbox), and deploys, as [Connect Amazon SES](../get-started/04-ses.md#8-set-the-provider-and-deploy) describes. The send retries on its own meanwhile.
+- **"Nothing has gone out for …".** A send has handed off no one for half an hour, with no retry or provider problem to explain it. The part of Kestrel that sends has stopped or keeps failing on this send, or another send going out at the same time is taking all of its turn. A large send going out slowly never shows this. If another send is going out, this one picks up once it finishes. Read the app's logs, as [Read the logs](../get-started/05-verify.md#7-read-the-logs) describes, and check the Worker's trigger, as [`triggers.crons`](../reference/01-configuration.md#triggerscrons) describes. The send carries on from where it stopped once it runs again, mailing no one twice.
 - **"The fire time passed … and the send has not started".** The Cloudflare Cron Trigger that starts sends on time isn't running. The send goes out as soon as it runs again. Check the Worker's trigger, as [`triggers.crons`](../reference/01-configuration.md#triggerscrons) describes.
 - **"The provider never answered for …".** Rarely, Kestrel can't tell whether your provider took some emails, and sending again could mail those readers twice. **Resolve…** on the send's page asks you to decide. **Assume not sent** is the safe default: those readers may miss this post, but get your next one. Choose **Assume sent** only when you know they got it.
 
 ## Before a send
 
+- **A test says "The provider refused it".** Your provider didn't take the test, and its own words follow, with the fix where Kestrel knows it. Sending again gets the same answer until that's fixed. While Amazon SES is in its sandbox, it sends only to addresses verified in SES, so verify the address you test with in the SES console, or request production access, as [Connect Amazon SES](../get-started/04-ses.md#5-request-production-access) describes. Words about the account, such as a key or the sending domain, point at the same fix as [a send the provider refuses](06-troubleshooting.md#a-send-is-waiting-or-held).
+- **A test says "The provider didn't answer, so the test may have arrived".** Kestrel can't tell whether your provider took it. Check the inbox before you send again, since a second test may arrive twice.
 - **"The template or publication details changed this email's look after your last test".** Send a new test of the post, since your last one no longer shows what goes out.
 - **The daily database writes warning.** On Cloudflare's free Workers plan, a large send may use up the day's writes, and then the app stops working until midnight UTC. [Bring your existing list](01-your-list.md#limits) explains the limit, and when to upgrade to Workers Paid.
 
@@ -31,9 +35,33 @@ A send's page becomes its permanent record once it finishes. Its counts cover ev
 | **Complained** | The reader marked the email as spam. |
 | **Unsent** | Kestrel couldn't hand the email to your provider. |
 
-Delivered always means confirmed, not just accepted by your provider. Confirmations can lag by days, so counts keep rising after a send finishes. Some emails are never confirmed at all, so a send can read **Settling** for good, which is normal.
+Delivered always means confirmed, not just accepted by your provider. Confirmations can lag by days, so counts keep rising after a send finishes. Some emails are never confirmed at all, so a send can read **Settling** for good, which is normal, as long as some receipts have come.
 
-**Unsent recipients** are still on your list, and get your next post. A recipient is unsent when their own email kept failing, with the provider's words on the row, or when you chose **Assume not sent**.
+**"No delivery receipt has arrived for any of …".** An hour after a send went out, Kestrel has heard back about none of its readers. Your provider's reports probably aren't reaching Kestrel, so its bounces and complaints suppress no one, and your next post mails those addresses again. Look for `webhook.refused` errors in the app's logs, as [Read the logs](../get-started/05-verify.md#7-read-the-logs) describes. It names the SNS topic that reached Kestrel and the one it expects. Then check the subscription in [Connect Amazon SES](../get-started/04-ses.md#9-subscribe-the-app-to-the-topic). The line goes as soon as a receipt arrives.
+
+**Unsent recipients** are still on your list, and get your next post. A recipient is unsent when their own email kept failing, or their address isn't one SES accepts, with the provider's words on the row, or when you chose **Assume not sent**.
+
+### What SES refuses, and the fix
+
+When SES refuses your account or a send, the red line carries SES's words and the fix. Almost every fix is made by whoever runs the deployment, in the SES console or the deployment's settings.
+
+| SES says | What it means | The fix |
+| --- | --- | --- |
+| Email address is not verified, naming a reader | The SES account is still in the sandbox, which mails only verified addresses. | Request production access on the SES console's **Account dashboard**, as [Connect Amazon SES](../get-started/04-ses.md#5-request-production-access) describes. Signups fail until then, and you're emailed about it once a day. |
+| Email address is not verified, naming your From address or its domain | The sending identity isn't verified in this SES region. | Verify the From address or its domain in SES, in the region the deployment sends from. |
+| Mail FROM domain is not verified | SES can't read the custom MAIL FROM domain's MX record. | Check that record in DNS, or set the identity's **Behavior on MX failure** to use the default MAIL FROM domain. |
+| Daily message quota exceeded | The 24-hour sending quota is spent. It frees up on its own. | In the sandbox (200 a day), request production access. Otherwise, ask AWS for a higher quota, as [As your list grows](../guides/09-as-your-list-grows.md) describes. |
+| Sending paused (account) | AWS paused the account under review, or sending was turned off by hand. | Follow AWS's email to the AWS account's address, or turn sending back on. |
+| Sending paused (configuration set) | Sending is turned off on the configuration set, by hand or by an alarm. | Turn sending back on for that set. |
+| Account suspended | AWS shut down the account's sending. | Only AWS can lift it: open a case with AWS Support. |
+| An access key, signature, or permission error | The deployment's SES key is wrong, expired, or lacks permission. | Replace the key, or give it `ses:SendEmail` and `ses:SendBulkEmail`. |
+| A subscription is needed (OptInRequired) | The AWS account isn't signed up for SES. | Enable SES for the account, or settle its activation or billing with AWS. |
+| Configuration set does not exist | `SES_CONFIGURATION_SET` names a set that isn't in this region. | Fix the name, or create the set. |
+| Sending pool not found | The configuration set uses a dedicated IP pool that doesn't exist. | Pick an existing pool in the set's sending options, or remove it. |
+| The message was rejected | SES refuses this email itself. | Ask AWS Support why. Other posts go out as usual. |
+| The request is invalid | SES refused a batch of this send. | If SES's words name a reader's address, remove that subscriber. |
+
+A server error from SES may come after SES already took the emails, so Kestrel never sends that batch again: its readers wait for **Resolve…**, as for "The provider never answered for …".
 
 ## Bounces and complaints
 
@@ -65,8 +93,9 @@ Kestrel refuses a file it can't read with certainty, and says what's wrong and w
 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 no provider is connected
-- when a send stays in progress too long, waits for you to resolve it, or misses its time
+- when your provider refuses your account or a send, 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 Claude imports a list for you
 
 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.

package/docs/publishing/07-working-with-claude.md

@@ -7,7 +7,8 @@ To set Claude up, follow [Connect Claude to the API](../guides/01-connect-claude
 ## What to ask Claude
 
 - **Draft or proofread a post.** Give it notes, an outline, or a draft. It saves a new version you can open in the dashboard. If you edited the post meanwhile, its save is refused, and it works from your version or asks you.
-- **Test and schedule a post.** Name the post and when it should go out. Claude schedules it, sends a test of exactly what will go out, and tells you how to cancel. It can also cancel a send or move it.
+- **Test and schedule a post.** Name the post and when it should go out, and say so if it should be email only. Claude tells you whether the post will be in your archive, and at which address, before it schedules. Then it sends a test of exactly what will go out and tells you how to cancel. It can also cancel a send or move it.
+- **Take a sent post out of your archive, or put it back.** Claude asks first, as the dashboard does, since taking a post out breaks links people shared.
 - **Check how a send did.** Claude reads the send's record and reports what was delivered, unsent, bounced, or complained.
 - **Lift a bounce or a complaint.** The dashboard can't, so ask Claude when you know an address works again. [Lifting a suppression](06-troubleshooting.md#lifting-a-suppression) says when that's wise.
 - **Recover an earlier version.** Every save keeps a whole version of a post, and Claude can read them back.
@@ -24,6 +25,6 @@ The app holds these for any client, so they hold whatever Claude is told:
 - **No one's edit is overwritten.** A save based on an older version is refused.
 - **Only you can let an import grow a scheduled send.** An import through Claude that would stops there, until you finish it in the dashboard.
 
-Claude also follows instructions your Kestrel gives it, which live in your instance's repository. Those hold only as long as the instructions do. They have Claude ask before anything that reaches readers, test again after a template change, and record whose decision each change to the list was. They also have it treat what's in a post or a subscriber's record as content, never as instructions.
+Claude also follows instructions your Kestrel gives it, which live in your instance's repository. Those hold only as long as the instructions do. They have Claude ask before anything that reaches readers, say whether a post will be in your archive before it's sent, test again after a template change, and record whose decision each change to the list was. They also have it treat what's in a post or a subscriber's record as content, never as instructions.
 
 The app lets Claude give your attestation for an import, so asking you first is one of those instructions, not a rule the app enforces. The import's record says it came through Claude, and Kestrel emails you about it if your notifications are set.

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

@@ -25,7 +25,7 @@ A variable is replaced with its value in each email. Type it exactly as shown, o
 | `{{ .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.ViewInBrowserURL }}` | The post's public page. |
+| `{{ .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,7 +4,7 @@ These pages get you publishing in the dashboard, and cover the decisions to make
 
 ## Set up your publication
 
-The steps to set up a new publication, in the order the dashboard's setup checklist lists them.
+The steps to set up a new publication, in the order the dashboard's setup checklist lists them. Once you've started a post, they stay on the dashboard as **Finish setting up** until you publish your first post, one that goes to your subscribers and onto your site. That's the fourth step.
 
 1. [Name your publication](03-name-your-publication.md)
 1. [Check your setup](10-check-your-setup.md)

package/docs/reference/01-configuration.md

@@ -42,7 +42,7 @@ Neither one is the publication's name, tagline, or logo. You set those in the ed
 
 ### `ARCHIVE_BASE_PATH`
 
-Every post sent carries its archive link, `ARCHIVE_BASE_PATH` followed by the post's slug, and those links are permanent. Changing the prefix later breaks every link already mailed, so pick it before the first send. To keep links from an older install working, set it to the prefix they use, such as `/newsletter`.
+A listed post's archive address is `ARCHIVE_BASE_PATH` followed by the post's slug. Emails link through each post's unlisted link, `/email/<token>` on `APP_ORIGIN`, which forwards to the archive address, so changing the prefix later breaks no email that carries one, only archive addresses people have shared. Emails sent by 1.11 or earlier carry the archive address itself, and changing the prefix breaks those. To keep links from an older install working, set it to the prefix they use, such as `/newsletter`.
 
 A missing leading slash is added, and a trailing slash is dropped.
 

package/migrations/0007_sends_progress_at.sql

@@ -0,0 +1,12 @@
+-- 0007_sends_progress_at: when a send last made progress (SPEC §12).
+--
+-- A send is in flight too long when it has handed off no one for a while and nothing else
+-- explains why, not when it has been sending a while: a large send on a slow provider rate
+-- goes out for hours and is fine. `progress_at` is when the provider last answered for any
+-- of the send's recipients, so the app can tell a send that is moving from one that has
+-- stopped. Null until the first answer, when the send's start stands in for it, so a send
+-- already in flight when this runs reads as it did (src/db/sends.ts, SEND_IDLE_SINCE).
+--
+-- Adding a nullable column writes no rows, so this costs nothing to apply at any size.
+
+ALTER TABLE sends ADD COLUMN progress_at INTEGER;

package/migrations/0008_notifications_sandbox.sql

@@ -0,0 +1,35 @@
+-- 0008_notifications_sandbox: tell the publisher when the SES sandbox refuses a signup's
+-- confirmation (SPEC §7, §8).
+--
+-- While the SES account is in the sandbox, SES refuses mail to any address not verified in
+-- it, so a reader who signs up is told a link is on its way and none arrives. The publisher
+-- hears of it through the notifications they already get, as a `sandbox` 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 however many signups SES refuses. `notifications.kind`'s
+-- CHECK doesn't admit it and a STRICT table's CHECK can't be altered, so the table is rebuilt
+-- with `sandbox` added, every row and column carried over.
+CREATE TABLE notifications_next (
+  send_id    TEXT REFERENCES sends (id),       -- null for a test, an import notice, and a sandbox 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')),
+  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,
+  UNIQUE (send_id, kind, episode),
+  UNIQUE (import_id),
+  CHECK ((send_id IS NULL) = (kind IN ('test', 'import', 'sandbox'))),
+  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)
+  SELECT send_id, import_id, kind, episode, status, attempts, error, created_at, updated_at 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';

package/migrations/0009_post_email_only.sql

@@ -0,0 +1,12 @@
+-- 0009_post_email_only: whether a post is listed in the public archive (SPEC §5).
+--
+-- A post is in the archive (0, the default) or email only (1): mailed exactly as a listed
+-- post is, but left out of the archive index and the landing page; 0008 decides what its
+-- archive address answers. The listing belongs to the post, not to a send,
+-- because it is not part of the frozen render: changing it never re-makes a scheduled send's
+-- email or touches a sent one (I3), and it can be changed after the post is sent.
+--
+-- Every existing post reads as in the archive, so an upgrade lists exactly what it listed
+-- before. Adding a column with a constant default rewrites no rows.
+
+ALTER TABLE posts ADD COLUMN email_only INTEGER NOT NULL DEFAULT 0 CHECK (email_only IN (0, 1));

package/migrations/0010_unlisted_links.sql

@@ -0,0 +1,43 @@
+-- 0010_unlisted_links: every post gets its own unlisted link, and every send records which
+-- address its email carries (SPEC §5).
+--
+-- Every email's "view in browser" link used to be the post's archive address,
+-- `/archive/<slug>`. That made an email-only post's page guessable from its subject, and tied
+-- every email ever sent to the archive's base path. Now each post has an unlisted link,
+-- `/email/<token>` on the app's own origin, which every test and send carries instead, and the
+-- archive address answers only while the post is listed.
+--
+-- posts.unlisted_token: 128 bits of randomness, made with the post and never changed, written as
+-- 32 hex digits in four groups of eight joined by hyphens, so a reader can keep their place in it.
+-- A column added to an existing table can't take a per-row default, so existing posts are
+-- given theirs here, and a trigger gives one to every post inserted without it, so no way of
+-- inserting a post leaves it without a link. The unique index keeps every link a post's own.
+--
+-- sends.web_link: which address the send's email carries as its "view in browser" link,
+-- `unlisted` from this release on, or `archive` for a send frozen before it. The column defaults
+-- to `archive`, which every existing send takes, and this release's Worker names `unlisted` on
+-- every send it freezes: a send frozen by the previous release's Worker while it still serves,
+-- between this migration and the deploy or after a rollback, carries its archive address, and
+-- the default records it so. A post whose
+-- published send carries `archive` keeps its archive address answering whatever its listing,
+-- since every copy of that email links there. A re-make freezes a new copy, so it moves a
+-- scheduled send to `unlisted`.
+--
+-- Slugs keep the rule they have had since 0001: every post's is unique, drafts included.
+
+ALTER TABLE posts ADD COLUMN unlisted_token TEXT;
+UPDATE posts SET unlisted_token = lower(hex(randomblob(16)));
+UPDATE posts SET unlisted_token = substr(unlisted_token, 1, 8) || '-' || substr(unlisted_token, 9, 8)
+  || '-' || substr(unlisted_token, 17, 8) || '-' || substr(unlisted_token, 25, 8);
+CREATE UNIQUE INDEX idx_posts_unlisted_token ON posts (unlisted_token);
+
+CREATE TRIGGER posts_unlisted_token AFTER INSERT ON posts
+  WHEN NEW.unlisted_token IS NULL
+BEGIN
+  UPDATE posts SET unlisted_token = lower(hex(randomblob(16))) WHERE id = NEW.id;
+  UPDATE posts SET unlisted_token = substr(unlisted_token, 1, 8) || '-' || substr(unlisted_token, 9, 8)
+    || '-' || substr(unlisted_token, 17, 8) || '-' || substr(unlisted_token, 25, 8) WHERE id = NEW.id;
+END;
+
+ALTER TABLE sends ADD COLUMN web_link TEXT NOT NULL DEFAULT 'archive'
+  CHECK (web_link IN ('unlisted', 'archive'));

package/migrations/0011_sends_render_warnings.sql

@@ -0,0 +1,13 @@
+-- 0011_sends_render_warnings: what the render said about a send's frozen copy (SPEC §5, §6).
+--
+-- The render answers its email with warnings, such as an image the post references but never
+-- uploaded. A draft's preview and test show them from a live render, but once the post was
+-- scheduled the instruments read the frozen copy and had nothing to say, so a test of a copy
+-- missing its image answered clean. The freeze and the re-make now store the warnings their
+-- render gave, as a JSON array of strings, beside the copy they describe.
+--
+-- A send frozen before this column existed reads as `[]`: its render's warnings were never
+-- kept, and rendering it again could disagree with the bytes it holds. Adding a column with a
+-- constant default rewrites no rows.
+
+ALTER TABLE sends ADD COLUMN render_warnings TEXT NOT NULL DEFAULT '[]';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurtbruns/kestrel",
-  "version": "1.11.0",
+  "version": "1.12.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/template/claude/CLAUDE.md

@@ -28,8 +28,11 @@ Deploying, migrating the production database, and anything that sends mail or ch
 - **Read `GET /api/reference` first,** and use it for every call: each route's method, path, body types, and an example.
 - **Save a post against the revision you read.** Send its `current_revision` back as `base_revision`, or as `If-Match` with the post's `ETag`. On `stale_revision`, someone else changed the post (the refusal's `author` says who): read it again and re-apply your change to the newer revision, or ask. Never overwrite their edit.
 - **Act on a send from its `actions`,** which list only what the server would accept on it now. An act is safe to repeat, and every answer and every refusal carries the send as it now stands: read that before telling the publisher what happened or deciding again.
-- **Schedule only when the publisher asks, then send a test.** Once a post is scheduled, a test sends the frozen copy, exactly what will fire, to one address per call: one to each of `testRecipients` from `GET /api/settings`, or ask. Tell them when the send fires and how to cancel it. A template or identity change re-makes scheduled sends, so test again after one.
-- **Until AWS has granted SES production access, never help share the subscribe link or send to anyone but the addresses verified in SES.** The sandbox refuses every other recipient, so their signups fail and a send marks them unsent. You can't see the sandbox state yourself: ask the publisher whether AWS granted access. Point to the guide's Go live page, whose Before you begin needs production access first.
+- **Schedule only when the publisher asks, then send a test.** Once a post is scheduled, a test sends the frozen copy, exactly what will fire, to one address per call: one to each of `testRecipients` from `GET /api/settings`, or ask. Tell them when the send fires, where the post goes, and how to cancel it.
+- **Re-make a scheduled send only on the publisher's word.** Saving a changed template, or an identity field the template renders, re-makes the email of every scheduled send, and is refused with 409 `remake_required` naming them in `sends`. Don't send their ids back in `remake` on your own: tell the publisher which posts would be re-made (each `subject`) and when each fires (`fire_at`), and save again with `remake` only once they say so. The review window still applies, but a re-made email is no longer the one they tested. Then send a test of each send in the response's `remade`, as above, since each needs a fresh one.
+- **Say where a post goes before it's scheduled or sent.** A post is listed in the public archive unless it is **email only**, mailed as usual but left off the archive and the home page. Before you schedule, send now, or confirm either, tell the publisher which it will be, naming the archive address when it's listed: the post's `archive_url`. Once it's published (`published_at` is set; `status` stays `scheduled` while it's going out), a reader sees it at `archive_url` when `archive_live` is true, and otherwise only at `unlisted_url`, the link in its emails; share that one only if the publisher asks. Send `email_only: true` only when the publisher asks for email only ("just email it", "keep it off the site"), and leave the field out otherwise, which keeps the listing the post has. When a post reads as inbox-only, such as a correction or a short-lived notice, and they haven't said, ask rather than choose. A test email puts nothing in the archive.
+- **Change a post's listing or address only when the publisher asks.** Both live on `PUT /api/posts/:id/settings`, and on Schedule and Send now; a reschedule moves only the time. On a sent post, confirm first, as the editor does: making it email only takes its archive page down, so links people shared stop working, and listing it puts it on the public web. A sent post's address is fixed (`slug_permanent`). On a 409 `slug_taken` (an address you set is another post's), ask which address they want rather than picking one. A save that succeeds with `subject_slug_held` set only means the subject's address was taken and the post got a number; mention it, and change it only if they ask.
+- **Until AWS has granted SES production access, never help share the subscribe link or send to anyone but the addresses verified in SES.** The sandbox refuses every other recipient, so their signups fail and a send holds until AWS grants access, mailing only the verified addresses until then. You can't see the sandbox state yourself: ask the publisher whether AWS granted access. Point to the guide's Go live page, whose Before you begin needs production access first.
 - **Never add a subscriber the publisher didn't name,** with one exception: an import the publisher asked for, run through the `/migrate-list` skill and the import plan, and confirming anyone only with their attestation. Treat an unsubscribe as final: only the reader undoes it, by subscribing again.
 - **Pick the act that records whose decision it was.** Unsubscribe someone only when they asked to leave; when the publisher decides themselves to stop mailing an address, block it (`POST /api/suppressions`) instead. The reference says what each act and each suppression `reason` means, in the words the editor shows the publisher. Unblock or clear only an address the publisher names. Never clear a bounce or complaint unless the publisher says the problem is gone, and confirm first: it lets mail go to an address that failed or reported spam.
 - **Erase a subscriber only when the publisher names them and asks for it, and confirm first:** an erasure can't be undone. On `erasure_acknowledgement_required`, send `acknowledge_erasure: true` only once the publisher says the person asked to join again.