@kurtbruns/kestrel 1.9.0 → 1.10.0

package/docs/README.md

@@ -1,6 +1,6 @@
-# Set up and run Kestrel
+# Self-hosting Kestrel
 
-These guides deploy and run your own instance of Kestrel, from an empty repository to a newsletter on your own Cloudflare account.
+These pages deploy and run your own instance of Kestrel, from an empty repository to a newsletter on your own Cloudflare account. Writing and sending the newsletter is covered in [Publishing](publishing/README.md).
 
 ## Get started
 
@@ -27,5 +27,4 @@ Each one stands on its own. Pick the ones you need.
 The detail behind the steps, for when you need it.
 
 - [Configuration](reference/01-configuration.md)
-- [Sending-domain DNS](reference/02-sending-domain-dns.md)
-- [Import format](reference/03-import-format.md)
+- [Sending-domain DNS: SPF, DKIM, and DMARC](reference/02-sending-domain-dns.md)

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

@@ -2,7 +2,7 @@
 
 Kestrel sends your posts through Amazon SES, Amazon's email service. SES only delivers the mail: Kestrel keeps your list, each subscriber's consent, and the record of every send. AWS reviews your account before it lets you send to anyone but yourself. This page asks for that early, and you test in the sandbox while you wait.
 
-In this guide, you verify your sending hostname with SES, add a DMARC record, and ask AWS for production access. You also route bounces and complaints to the app through SNS. Then you give the app its AWS credentials, set the provider, and deploy.
+In this guide, you verify your sending hostname with SES and add a DMARC record. You forward readers' replies to your inbox, and ask AWS for production access. You also route bounces and complaints to the app through SNS. Then you give the app its AWS credentials, set the provider, and deploy.
 
 ## Before you begin
 
@@ -42,7 +42,33 @@ DMARC tells inboxes what to do with mail that fails its checks, and sends you re
 
 [Sending-domain DNS](../reference/02-sending-domain-dns.md#dmarc-publish-a-policy-and-collect-reports) explains each record, and when to tighten DMARC.
 
-## 3. (Optional) Set a custom MAIL FROM domain
+## 3. Receive replies at your From address
+
+When a reader replies to a post, or to their confirmation email, the reply goes to your From address, `newsletter@send.example.com`. Nothing receives mail there yet, so the reply bounces. Kestrel only sends mail, so you give the address an inbox yourself. Here you forward it to one you already read, with Cloudflare Email Routing, which is free on every plan.
+
+`send.example.com` receives no other mail, so turning on Email Routing there changes nothing else. Your SES records sit on other names under it. Inboxes check SES's mail for SPF at its return path, not here, so sending is unaffected.
+
+1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Compute → Email Service → Email Routing**.
+
+1. Add `send.example.com` to Email Routing. Cloudflare adds subdomains from your domain's own settings: select `example.com`, then **Settings**, and add `send` under **Subdomains**.
+
+1. Cloudflare adds MX, SPF, and DKIM records for `send.example.com`, and locks them. Wait until they show as added.
+
+1. Under **Destination Addresses**, add the inbox you want replies in. Open the email Cloudflare sends to it, and select **Verify email address**. An address you've already verified with Cloudflare, such as one for [notifications](../guides/03-notifications.md), is listed already.
+
+1. Under **Routing Rules**, select **Create routing rule**. For **Email pattern**, enter `newsletter`, the part of your From address before the `@`, and select `send.example.com`. Set **Action** to **Send to an email**, select your inbox as the **Destination**, and save.
+
+On a subdomain, Email Routing forwards only the addresses you add a rule for, with no catch-all. That's all a From address needs.
+
+- **Automatic replies arrive too.** Out-of-office and other automatic replies go to your From address, so they reach your inbox. Bounces don't: they go to SES's return path, and the app handles them as before.
+- **Your DMARC reports need an inbox too.** Your DMARC record's report address may not receive mail. If so, change the record's `rua` to `mailto:dmarc@send.example.com`, and add a second rule that forwards `dmarc` the same way.
+- **Your answers come from your inbox.** A forwarded reply comes from the reader's own address. When you answer it, your answer goes out from the inbox it was forwarded to, not from `newsletter@send.example.com`.
+
+To answer from the newsletter's own address, give it a real mailbox instead of forwarding it. Point `send.example.com`'s MX records at a mail host you use, such as [Fastmail](https://www.fastmail.help/hc/en-us/articles/360060591133) or [Google Workspace](https://support.google.com/a/answer/140034). Then create `newsletter@send.example.com` there, as the host's docs describe. If you send from it, the host's SPF and DKIM records go on `send.example.com` beside SES's. SES's mail is unaffected, since its SPF is checked at its return path. And if your From address is on a domain that already receives mail, replies already reach it, and you can skip this section.
+
+Some replies ask you to do something, and Kestrel can't see them, so acting on them is yours. In the editor, open **Subscribers**, and use the reader's row menu. Choose **Unsubscribe** for a reader who asks to leave, and **Erase** for one who asks you to delete their data. A reader who never confirmed isn't mailed, so their row offers only **Erase**.
+
+## 4. (Optional) Set a custom MAIL FROM domain
 
 SES sends with its own return path by default, so SPF passes for `amazonses.com` rather than for your hostname. DMARC still passes, through DKIM. A custom MAIL FROM domain makes SPF pass for your hostname too, a second check in your favor.
 
@@ -57,11 +83,11 @@ SES sends with its own return path by default, so SPF passes for `amazonses.com`
 
 1. Wait until SES shows the MAIL FROM domain as **Successful**.
 
-## 4. Request production access
+## 5. Request production access
 
 A new SES account starts in the sandbox. It sends only to addresses you've verified in SES, up to 200 emails a day and one a second. Ask AWS to lift those limits now, and test while you wait.
 
-1. Name your publication first, since AWS may visit your website to review the request. In the editor, open **Settings → Publication identity**, and enter the name and tagline. Until you do, your public pages show the name in your From address. The subscribe form stays closed until section 7 sets the provider.
+1. Name your publication first, since AWS may visit your website to review the request. In the editor, open **Settings → Publication identity**, and enter the name and tagline. Until you do, your public pages show the name in your From address. The subscribe form stays closed until section 8 sets the provider.
 
 1. In SES, open the **Account dashboard**, select **View Get set up page**, and then **Request production access**.
 
@@ -83,9 +109,9 @@ If AWS asks for more detail, reply in the support case. If it denies the request
 
 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.
 
-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 7. The rate decides how fast a send goes out, and [As your list grows](06-go-live.md#as-your-list-grows) says when to ask AWS to raise it.
+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](06-go-live.md#as-your-list-grows) says when to ask AWS to raise it.
 
-## 5. Send bounces and complaints to SNS
+## 6. Send bounces and complaints to SNS
 
 SES reports what happens to each email through SNS, the AWS notification service. A configuration set says which events to report, and an SNS topic carries them to the app.
 
@@ -120,9 +146,9 @@ SES reports what happens to each email through SNS, the AWS notification service
 
     Replace the topic ARN, and both copies of the account ID, with the values from your ARN. Replace `us-east-1` with your region's code, the same one the ARN shows. Choose **Save changes**.
 
-You subscribe the app to the topic in section 8, once it runs on SES.
+You subscribe the app to the topic in section 9, once it runs on SES.
 
-## 6. Create the app's AWS key
+## 7. Create the app's AWS key
 
 The app sends through an IAM user whose key can only send email. That limits the harm if the key ever leaks.
 
@@ -155,7 +181,7 @@ The app sends through an IAM user whose key can only send email. That limits the
 
 1. Copy the access key ID and the secret access key. AWS shows the secret only once.
 
-## 7. Set the provider and deploy
+## 8. Set the provider and deploy
 
 Until now the app has run with no email provider connected, refusing to send. Setting `PROVIDER` connects SES. Store the secrets before you set it. With `PROVIDER` set to `ses` and a required secret missing, the app refuses to run, and sends nothing, until you store it. `/health` and the editor's **A setting needs fixing** page name the missing secret, and reader pages say the newsletter is temporarily unavailable. `SES_CONFIGURATION_SET` is the one optional secret.
 
@@ -171,7 +197,7 @@ Until now the app has run with no email provider connected, refusing to send. Se
     npx wrangler secret put AWS_SECRET_ACCESS_KEY --env production
     ```
 
-1. Store the topic ARN from section 5. The app accepts events only from this topic:
+1. Store the topic ARN from section 6. The app accepts events only from this topic:
 
     ```bash
     npx wrangler secret put SNS_TOPIC_ARN --env production
@@ -214,7 +240,7 @@ Until now the app has run with no email provider connected, refusing to send. Se
     npx wrangler deploy --env production
     ```
 
-## 8. Subscribe the app to the topic
+## 9. Subscribe the app to the topic
 
 SNS delivers events only to a subscriber that has confirmed. The app confirms on its own, once it checks that the request came from your topic.
 
@@ -234,7 +260,7 @@ If it stays **Pending confirmation**, the request never reached the app, or the
 
 - **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.**
-- **The deploy in section 7 finished.**
+- **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.
 
@@ -272,11 +298,25 @@ Kestrel can't tell whether those emails went out. SES's console shows sent messa
 
 1. The SNS subscription shows **Confirmed**.
 
+1. Your From address has somewhere to go. In Cloudflare, your domain's DNS records show the ones Email Routing added for `send`, beside section 1's DKIM records:
+
+    - **Type:** `MX`, **Name:** `send`, three of them, for `route1.mx.cloudflare.net`, `route2.mx.cloudflare.net`, and `route3.mx.cloudflare.net`
+    - **Type:** `TXT`, **Name:** `send`, **Content:** `v=spf1 include:_spf.mx.cloudflare.net ~all`
+    - **Type:** `TXT`, **Name:** `cf2024-1._domainkey.send`, Cloudflare's DKIM key
+
+    The world sees the MX records too:
+
+    ```bash
+    dig +short MX send.example.com
+    ```
+
+    It lists the three `route` servers. Email Routing's **Routing Rules** shows your rule for `newsletter@send.example.com`, and **Destination Addresses** shows your inbox as verified. A reply to your test email in the next step proves the forwarding works.
+
 1. In the editor, **Settings → Email sender** shows Amazon SES and your From address, where it said **No email provider connected** before.
 
 1. In a browser, `https://newsletter.example.com/subscribe` shows the subscribe form, where it said signups aren't open yet.
 
-The test sends in the next step prove the rest. In the sandbox, send them only to the addresses you verified in section 4, and to the SES test addresses that page lists.
+The test sends in the next step prove the rest. In the sandbox, send them only to the addresses you verified in section 5, and to the SES test addresses that page lists.
 
 SES charges for each email it sends, test emails included. [Amazon SES pricing](https://aws.amazon.com/ses/pricing/) lists the rates.
 

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

@@ -2,11 +2,11 @@
 
 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 your list is empty and every email goes only to you.
 
-In this guide, you send yourself a test email and check that it passes authentication. Then you set up your notifications, send a real post to yourself as a subscriber, and unsubscribe. Finally, you check that bounces and complaints reach the app, and read the app's logs.
+In this guide, you send yourself a test email, reply to it, and check that it passes authentication. Then you set up your notifications, send a real post to yourself as a subscriber, and unsubscribe. Finally, you check that bounces and complaints reach the app, and read the app's logs.
 
 ## Before you begin
 
-- Two email addresses you own, such as a personal address and a work address. Some steps use both. While your SES account is in the sandbox, verify both in SES first, as [Connect Amazon SES](04-ses.md#4-request-production-access) describes.
+- Two email addresses you own, such as a personal address and a work address. Some steps use both. While your SES account is in the sandbox, verify both in SES first, as [Connect Amazon SES](04-ses.md#5-request-production-access) describes.
 - A Gmail address, or another mail client that shows a message's original source and an **Unsubscribe** button.
 
 ## 1. Send yourself a test email
@@ -19,6 +19,8 @@ A test email goes through the same code as a real send. If the test looks right,
 
 1. Open the email. It should arrive in your inbox, not in spam. The image loads and the subject reads as you wrote it. Its **View in browser** link opens "Nothing here yet" until the post goes out, and its unsubscribe link opens the page a subscriber sees, marked as a test and showing a sample address. Its button walks through to the confirmation, but a test email unsubscribes no one. Section 5 unsubscribes for real.
 
+1. Reply to it, as a reader would. Reply from an address other than the inbox your From address forwards to, such as your second address. Gmail doesn't show you a message you sent when it comes back to you. Send that address a test email too if you need one. The reply arrives in the inbox you chose in [Connect Amazon SES](04-ses.md#3-receive-replies-at-your-from-address). The app can't see your forwarding, so this is the only proof that readers can reach you. If the reply bounces, check the routing rule and the destination address there.
+
 ## 2. Check that it passes authentication
 
 Inboxes trust mail that passes DKIM and DMARC for the domain it's from. Passing both is the best single sign that your mail reaches the inbox.
@@ -80,7 +82,7 @@ When an address bounces or marks your mail as spam, SES tells the app through SN
 
 1. In the editor, **Subscribers** lists both addresses as **Pending**, each with a **Suppressed** flag. The app never mails a suppressed address again.
 
-If an address has no flag, SES's events aren't reaching the app. Check the configuration set and the SNS subscription in [Connect Amazon SES](04-ses.md#5-send-bounces-and-complaints-to-sns).
+If an address has no flag, SES's events aren't reaching the app. Check the configuration set and the SNS subscription in [Connect Amazon SES](04-ses.md#6-send-bounces-and-complaints-to-sns).
 
 ## 7. Read the logs
 

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

@@ -6,14 +6,14 @@ In this guide, you check your publication's name, add a logo, and share your sub
 
 ## Before you begin
 
-- SES production access, granted in the region the app sends from. [Connect Amazon SES](04-ses.md#4-request-production-access) asks for it.
-- `SES_MAX_SEND_RATE` set to the maximum send rate on the SES **Account dashboard**, and deployed. [Connect Amazon SES](04-ses.md#7-set-the-provider-and-deploy) sets it to `1` for the sandbox.
+- SES production access, granted in the region the app sends from. [Connect Amazon SES](04-ses.md#5-request-production-access) asks for it.
+- `SES_MAX_SEND_RATE` set to the maximum send rate on the SES **Account dashboard**, and deployed. [Connect Amazon SES](04-ses.md#8-set-the-provider-and-deploy) sets it to `1` for the sandbox.
 
 In the sandbox, SES refuses the confirmation email to any address you haven't verified, so those signups fail. A post reaches only the addresses you verified in SES.
 
 ## 1. Name your publication
 
-Your publication's name, tagline, and logo appear on the public pages readers see, and in every email. You named it in [Connect Amazon SES](04-ses.md#4-request-production-access). Check those, and add a logo before anyone sees your pages.
+Your publication's name, tagline, and logo appear on the public pages readers see, and in every email. You named it in [Connect Amazon SES](04-ses.md#5-request-production-access). Check those, and add a logo before anyone sees your pages.
 
 1. In the editor, open **Settings → Publication identity**.
 
@@ -41,7 +41,7 @@ A new instance runs on Cloudflare's free Workers plan. As your list grows, three
 - **How fast a send goes out.** A send goes out a slice at a time, one slice a minute. SES takes one request a second, of up to 50 recipients, and no more recipients a second than your account's maximum send rate. So each request carries one second of that rate, up to 50.
 - **Your database's daily writes.** On the free plan, D1, the database the app runs on, allows 100,000 rows written a day. Past that, it refuses every query until midnight UTC, and the whole app stops: sends, signups, the public pages, and the editor.
 
-It's recommended to move to the $5 Workers Paid plan from about 5,000 subscribers. A send writes about 14 database rows a recipient, delivery receipts included. So one send uses up the free plan's day at about 7,000 recipients, and sooner when an import or anything else writes that day. Workers Paid counts [D1's writes](https://developers.cloudflare.com/d1/platform/pricing/) by the month instead, with 50 million included, and never stops the database for them. On the free plan, the app warns you before a send to more than 5,000 recipients, in the Schedule dialog and on the scheduled post. It never stops you, since your account may already be on Workers Paid.
+It's recommended to move to the $5 Workers Paid plan from about 5,000 subscribers. A send writes about 14 database rows a recipient, delivery receipts included. So one send uses up the free plan's day at about 7,000 recipients, and sooner when an import or anything else writes that day. Workers Paid counts [D1's writes](https://developers.cloudflare.com/d1/platform/pricing/) by the month instead, with 50 million included, and never stops the database for them. On the free plan, the app warns you before a send to more than 5,000 recipients, in the Schedule dialog and on the scheduled post. A smaller send that fires on a day you've imported subscribers gets the same warning on the scheduled post. The app also warns before an import that would use most of a day's writes with the day's earlier imports. It never stops you, since your account may already be on Workers Paid.
 
 The free Workers plan sends four requests a minute. At 14 messages a second, a common starting rate, that's 56 recipients a minute, and 1,000 subscribers take about 18 minutes. At 50 a second or more, it's 200 a minute.
 
@@ -62,4 +62,6 @@ Each of these guides stands on its own. Pick the ones you want.
 - [Connect Claude to the API](../guides/01-connect-claude.md), so Claude can draft, proofread, and schedule posts through the same API the editor uses.
 - [Notifications through Cloudflare's email](../guides/03-notifications.md), so you hear about problems even when your email provider has stopped sending.
 
+If someone else writes the newsletter, point them to the docs' Publishing section, written for them, starting with [Bring your existing list](../publishing/01-your-list.md).
+
 When a new release comes out, [Upgrade to a new release](../guides/07-upgrade.md) shows how to move to it.

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

@@ -75,8 +75,12 @@ CF-Access-Client-Secret headers from your environment with every request.
 Read GET /api/reference first, and use it for every call.
 ```
 
+The reference is also served as Markdown, `GET /api/reference.md`, which reads more easily for Claude than the JSON. So are the docs: `GET /api/docs/publishing.md` lists the publisher's pages, `GET /api/docs/self-hosting.md` this guide's, and each page is at `GET /api/docs/<slug>.md`.
+
 Claude reads the reference, and from there can list your posts, write a draft, and schedule it. The reference lists the body types each route takes. Most take JSON, sent with `Content-Type: application/json`. An image upload takes a multipart form, or the image file itself.
 
+To bring your subscribers over from another service, ask Claude to import your list. Your instance's `/migrate-list` skill reads the format from `GET /api/imports/format` and converts the old service's export to it. It checks Kestrel's plan against its own counts, and asks for your attestation before it imports anyone as a subscriber. [Bring your existing list](../publishing/01-your-list.md) explains what an import does, and the [import format](../publishing/08-import-format.md) describes every column.
+
 ## Check it
 
 1. Ask Claude to call `GET /api/whoami`. The app answers with a program's identity, not yours:

package/docs/guides/03-notifications.md

@@ -21,7 +21,7 @@ Cloudflare's email sends only from a domain set up with Email Routing. Use your
 
 1. Cloudflare adds MX, SPF, and DKIM records for `newsletter.example.com`, and locks them. Wait until they show as added.
 
-Avoid turning on Email Routing for a domain that already receives mail elsewhere, such as `example.com` with Google Workspace. Email Routing takes over that domain's MX records. Avoid `send.example.com` too, since your email provider sends from it.
+Avoid turning on Email Routing for a domain that already receives mail elsewhere, such as `example.com` with Google Workspace. Email Routing takes over that domain's MX records. Don't send notifications from `send.example.com` either, since your email provider sends from it. Email Routing there to forward readers' replies, as [Connect Amazon SES](../get-started/04-ses.md#3-receive-replies-at-your-from-address) sets up, is fine, since it only receives.
 
 ## 2. Verify your address
 

package/docs/publishing/01-your-list.md

@@ -0,0 +1,86 @@
+# Bring your existing list
+
+Almost no one starts a newsletter with an empty list. If your readers are on another service, bring them over before your first post, with the consent they gave there. It's the **Bring your existing list** step on your dashboard, and **Import** starts it. If you're starting fresh, skip this step: new readers join through [Share your subscribe link](09-share-your-subscribe-link.md).
+
+This page covers the file Kestrel reads, what an import does and why, and the limits. It also covers taking your whole list out again at any time, in the same format. The dashboard's **Subscribers → Import** walks you through an import, and Claude reads this same page through the API.
+
+## The file Kestrel reads
+
+Kestrel reads one documented format, `kestrel-subscribers/1`: a CSV file with a header row and one row per address. A row says what your old service recorded about a person, and Kestrel decides what that means here. Five columns decide what happens to a row:
+
+| Column | What it holds |
+| --- | --- |
+| `email` | The address. Kestrel trims it and ignores capitals when it matches. |
+| `status` | `subscribed`, `pending`, `unsubscribed`, or `none` (an address with no consent claim, present only to carry a bounce or a block). |
+| `opt_in` | How consent was collected: `double`, `single`, or `unknown`. |
+| `origin` | Where consent was collected, as a short name such as `sendy` or `mailchimp`. |
+| `subscribed_at` | When they subscribed, with its time zone, such as `2024-03-01T09:30:00Z`. Optional. |
+
+The optional columns carry the rest: a bounce or complaint (`suppression`), when someone confirmed or left, and `evidence`, the old service's own consent details, such as a signup IP or a form name. [Import format](08-import-format.md) describes every column and value.
+
+The import screen's **Download example file (CSV)** gives you `kestrel-import-example.csv`, a few rows that show each case. Open it in a spreadsheet to see the shape, and save your file as CSV UTF-8.
+
+Kestrel never guesses what another service's export means, because a wrong guess about who agreed to be emailed can't be taken back. An export in any other shape is refused, with what's wrong and where. Convert it first, with Claude or by hand.
+
+## A plain list of addresses
+
+If all you have is addresses, a `.txt` file with one address per line works too. After you choose it, you say what the addresses are: **Subscribed** (the default), **Unsubscribed**, or **Bounced**. Every address in the file is that one kind, so a plain list of subscribers and a plain list of bounces are two imports.
+
+A plain list loses what a full CSV carries: how and where each person joined, when, and the evidence. Kestrel records how they joined as unknown. When your old service can export more than addresses, prefer the CSV.
+
+## Let Claude convert your export
+
+Exports from Sendy, Mailchimp, Substack, and other services all differ, and change without notice. If you use Claude Code with your instance, ask it to do the conversion:
+
+```
+Please import my Sendy subscribers from ~/Downloads/sendy-export.csv into the newsletter.
+```
+
+Claude's `/migrate-list` skill reads Kestrel's format from your instance and asks you what anything ambiguous in the export means. It converts a few rows for you to check, then checks Kestrel's plan against its own counts. It asks for your attestation before it imports anyone as a subscriber. [Connect Claude to the API](../guides/01-connect-claude.md) sets Claude up.
+
+If a scheduled post would reach the people the import adds, Claude stops and asks you to finish in the dashboard: choose the converted file Claude left in your working folder under **Subscribers → Import**, and the same plan appears for you to confirm.
+
+## What an import does
+
+Nothing changes when you choose a file. Kestrel plans the import first and shows you what it would do to every row. You see who is added as a subscriber, who is recorded as having left, and who is suppressed, and which rows are repeats, invalid, or left out. You can download the rows that won't be imported as subscribers, to check them against your file. Only when you press **Import** does anything change, and then the import applies whole, or not at all. If a reader's consent changed between your plan and the import, for example someone unsubscribed or confirmed, their row follows your list as it stands then, and the result lists each row that turned out differently from the plan you saw. An import sends no email.
+
+To import anyone as a subscriber, you confirm that everyone you're importing as subscribed opted in to receive your publication, and that the list isn't purchased, rented, or scraped. If you're unsure about some people, take them out of the file before importing. Kestrel keeps your attestation with the import's record.
+
+If a post is scheduled, it goes to the list as it stands when it sends, so the people an import adds would receive it. The plan names each such post and how many more people it would reach, and you acknowledge each one before importing.
+
+If your list or its scheduled posts changed since the plan in a way the plan rests on, such as another import, Kestrel plans your file again and shows you the new plan as things stand now, before anything happens.
+
+## Why your old service's record is honored
+
+Kestrel normally confirms every new subscriber with double opt-in: they click a link in an email before they get any posts. Asking your whole list to confirm again would lose readers who already said yes, and would mail every one of them a request they didn't expect. So an import carries over what your old service recorded instead: the consent each person gave there, how it was collected, and your word for it.
+
+Kestrel holds a few lines that an import can't cross:
+
+- **Someone who left stays gone.** An address that unsubscribed here is never subscribed again by an import, whatever the file says. Only that reader can come back, by confirming here.
+- **A bounce, a block, or a do-not-contact marker here always wins.** An import never lifts a suppression, so an address known to fail is never mailed. An address you erased keeps only a do-not-contact marker, and an import never records a subscriber for it again, not even as one who left.
+- **A reader's newer choice stands.** If someone confirmed here after your old service says they left, they stay subscribed.
+- **Repeats are folded together,** and when one row says subscribed and another says unsubscribed, unsubscribed wins.
+
+In the subscriber list, imported subscribers are **Confirmed** and receive your posts. The **How they joined** column says they were imported, with the service and the opt-in method your file gave, such as "Imported · Sendy, single opt-in". Only someone who confirmed through Kestrel itself reads as "Double opt-in". Choose **View subscriber** from a subscriber's ⋯ menu to see the evidence.
+
+## Limits
+
+- **Rows.** One import takes up to 10,000 rows on Workers Paid, or 1,000 on the free plan's limits. The import screen says which applies to you. Split a larger list into several files, and import them one at a time.
+- **Daily database writes on the free plan.** Cloudflare's free plan allows a fixed number of database writes a day, and stops your newsletter until midnight UTC once they're used up. Bringing in a large list, in one file or several, and sending to it on the same day can use them up. So when the day's imports would use most of the day's writes, the plan warns you and suggests importing the file the next day, by UTC, and a post scheduled for a day imports have written warns you too, suggesting it go out the next day. Neither warning stops anything.
+- **When to move to Workers Paid.** From about 5,000 subscribers, it's recommended to move to the $5 Workers Paid plan, which has no daily limit on writes. Whoever runs your Kestrel makes the change, as [Go live](../get-started/06-go-live.md#as-your-list-grows) describes.
+
+## When readers reply
+
+Kestrel only sends mail. A reader who replies to a post writes to your From address, so replies reach you once that address forwards to an inbox you read. Whoever runs your Kestrel sets that up outside Kestrel.
+
+When a reader replies asking to be taken off the list, carrying it out is up to you, since Kestrel never sees the reply. Find them under **Subscribers**, and choose **Unsubscribe** from their ⋯ menu. It takes effect at once. **Unsubscribe** is there for confirmed readers; one who never confirmed gets no posts, and **Erase** removes them.
+
+When a reader asks you to delete their data, choose **Erase** from their ⋯ menu instead. It removes the subscriber and how they joined, and can't be undone. Past send records show an erased recipient in their place. Kestrel keeps only a do-not-contact marker, or the bounce, complaint, or block the address already had, so the address is never mailed again. The reader can still rejoin by subscribing and confirming themselves.
+
+## Taking your list out
+
+**Subscribers → Export** downloads your whole list as one CSV in the same format: every subscriber with their state, how they joined and the evidence, and every bounced, complained, blocked, or erased address. It's yours to keep as a backup, or to import into another Kestrel, which carries the list over as it is. A value a spreadsheet would run as a formula is written as text, so the file is safe to open.
+
+Claude can read the same export a page at a time through the API, at `GET /api/subscribers/export`.
+
+Next, [Write your first post](04-write-a-post.md).

package/docs/publishing/02-sending-rules.md

@@ -0,0 +1,35 @@
+# Sending rules
+
+Email law asks a few things of every newsletter. Kestrel handles the ones a sending app can, and the rest are yours, since they depend on what you write and whom you write to.
+
+This page covers what Kestrel handles, what you handle, and how to act on a reader's request to leave or be deleted. It describes US law (CAN-SPAM) unless it says otherwise. It's general information, not legal advice. When your situation is unclear, ask a lawyer.
+
+## What Kestrel handles
+
+- **Consent.** Kestrel mails only people who confirmed they want your newsletter. Someone who subscribes gets an email with a link, and only once they confirm do they receive posts. People you import come with your old service's record of their consent, and your word for it ([Bring your existing list](01-your-list.md#why-your-old-services-record-is-honored)).
+- **Unsubscribing.** Every email has an unsubscribe link, and the one-click unsubscribe header that Gmail and Yahoo ask bulk senders for. It takes effect at once. US law allows up to 10 business days.
+- **Bounces and complaints.** An address that bounces, or a reader who marks your email as spam, is never mailed again. So a bad address can't keep hurting your sending reputation.
+- **Sender authentication.** Your emails are signed with DKIM for your own domain, and SPF and DMARC records in its DNS vouch for them. Whoever runs your Kestrel sets these up, and mailbox providers now expect them.
+
+## What you handle
+
+- **An honest From name and subject line.** The From name should say who the email is from, and the subject should match what's inside. Whoever runs your Kestrel sets the From name and address.
+- **Marking ads as ads.** When an email is an advertisement, say so clearly. In a newsletter that's mostly writing, labeling a sponsor's section is enough.
+- **A mailing address, when an email is commercial.** Most newsletters don't need one. [When to provide a mailing address](03-name-your-publication.md#when-to-provide-a-mailing-address) says when you do, beside where you add one.
+- **Requests readers send you.** A reader who replies to a post writes to your From address. Replies reach you once that address forwards to an inbox you read, which whoever runs your Kestrel sets up. Kestrel never sees a reply, so carrying out what a reader asks is up to you.
+
+## When a reader asks to leave or to be deleted
+
+Kestrel offers readers no form for deleting their data, so they ask you. In many places the law gives a reader that right. The European Union's GDPR, for example, may apply if you have readers there.
+
+- **Say how to reach you.** Your privacy notice, wherever you publish it, should say how readers ask you about their data. Replying to any post works once replies reach your inbox.
+- **To stop the email,** find a confirmed reader under **Subscribers**, and choose **Unsubscribe** from their ⋯ menu. It records that they asked, and they can rejoin by subscribing again. A reader who never confirmed gets no posts, so **Erase** is the choice for them.
+- **To stop mailing someone on your own judgment,** not at their request, choose **Block** instead. It stops every email to the address whatever its status, and **Unblock** undoes it.
+- **To delete their data,** choose **Erase** from the same menu. It removes the subscriber and how they joined, and can't be undone. Past send records show an erased recipient in their place. Kestrel keeps the address only so it's never mailed again, as [Bring your existing list](01-your-list.md#when-readers-reply) explains.
+- **Act promptly.** Under the [GDPR](https://eur-lex.europa.eu/eli/reg/2016/679/oj), you answer within a month in most cases (Article 12). The right to have data deleted is Article 17, and Article 13 asks you to tell readers about it when they sign up.
+
+## Outside the US
+
+Other countries have their own rules, and they often ask more. Canada's anti-spam law (CASL) usually counts more email as commercial, and asks for a mailing address in it ([Government of Canada guidance](https://ised-isde.canada.ca/site/canada-anti-spam-legislation/en)). The GDPR covers how you keep readers' data. If many of your readers live outside the US, check the rules where they live.
+
+The FTC's [CAN-SPAM compliance guide](https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business) is the plain-language source for the US rules on this page.

package/docs/publishing/03-name-your-publication.md

@@ -0,0 +1,106 @@
+# Name your publication
+
+Give your newsletter a name and a look before your first post. Readers see your name, tagline, and logo in every email and on every public page. It's the first step of **Set up your publication** on your dashboard.
+
+You set them under **Settings → Publication identity**. Every email takes its look from one template, which works as it comes and which you can edit on the **Template** page. This page also covers the optional mailing address, what a change does to scheduled posts, and who sets the From name and address.
+
+## Name, tagline, and logo
+
+All three are optional, and you can change them at any time under **Settings → Publication identity**. The name and tagline save with **Save changes** in the bar at the bottom of the page. The logo saves the moment you pick it.
+
+- **Name.** Left blank, your publication uses the From name of your emails instead. If that has no name either, your publication goes unnamed, and every page reads whole without one.
+- **Tagline.** A short line under the name.
+- **Logo.** A PNG, JPEG, WebP, or GIF image. Kestrel shows it square everywhere, so a wider or taller image is cropped to its center square. Pick one at least 256 × 256 px. **Replace** swaps it, and **Remove** takes it away.
+
+Sent emails never change. An email already sent, and its archive page, keep the logo and name they went out with.
+
+## Where each part appears
+
+Your identity shows in four places:
+
+- **In your emails,** wherever your template prints it. The built-in template signs off each post with your logo, name, and tagline. The sample email under **Settings → Email template** shows which parts your template prints.
+- **On the public pages readers see.** Your home page, your archive, and each post's page carry your identity. So do the pages for subscribing, confirming, and unsubscribing. Your logo is the browser tab's icon. **Settings → Reader pages** shows each of these pages as a reader gets it.
+- **In the confirmation email** a new subscriber gets, which opens with your logo, name, and tagline.
+- **In the dashboard.** The top of the sidebar shows your logo, name, and tagline.
+
+A post's page shows your publication as it is now at the top, and the sign-off as it was sent.
+
+## When to provide a mailing address
+
+**Probably not, if your newsletter is mostly your own writing. Yes, if you use it to sell.** The address is optional, and you can add it or remove it at any time.
+
+US law (CAN-SPAM) requires a postal address in commercial email. That's email whose primary purpose is to advertise or promote a product or service, at any volume. In its [2008 rule](https://www.ftc.gov/sites/default/files/documents/federal_register_notices/definitions-and-implementation-under-can-spam-act-16-cfr-part-316/080521canspamact.pdf), the FTC treats a newsletter someone subscribed to as a "transactional or relationship" message instead. That holds when it's mainly content, even with ads mixed in. A subscription that's purely advertising, like a catalog, stays commercial.
+
+An email whose primary purpose is selling is a different matter. The FTC's [primary-purpose test](https://www.ecfr.gov/current/title-16/chapter-I/subchapter-C/part-316/section-316.3) looks at what the email says and what its subject line suggests. So you probably need an address in:
+
+- An email that's mainly selling, such as a launch, a sale, a paid course, or event tickets.
+- A post that's mostly sponsor content or promotions.
+- A mixed email whose subject line reads like an ad.
+
+A nonprofit isn't exempt as a kind of sender. What the email says decides it. Canada's anti-spam law (CASL) usually counts more email as commercial, and asks for a mailing address in it too ([Government of Canada guidance](https://ised-isde.canada.ca/site/canada-anti-spam-legislation/en)). Gmail and Yahoo don't ask for one: their [rules for bulk senders](https://support.google.com/a/answer/14229414) are authentication, one-click unsubscribe, and a low spam-complaint rate.
+
+**What counts.** A street address, a USPS P.O. box, or a private mailbox registered with the Postal Service. You never have to publish a home address.
+
+**Adding it.** Under **Settings → Publication identity**, choose **Add a mailing address**. The built-in template and both starting templates print it in the footer as soon as it's set, and print nothing while it isn't. They keep it off each post's public page, so your address isn't on the web.
+
+If you've added an address and your template doesn't include `{{ .Publication.Address }}`, Kestrel saves your change and warns you. A line under the address says so in Settings, and the **Template** page says so when you save. If you typed your address into the template yourself, or don't need one, you can ignore the warning.
+
+This is general information, not legal advice. The FTC's [CAN-SPAM compliance guide](https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business) is the plain-language source, and [Sending rules](02-sending-rules.md) covers the rest of what the law asks of a newsletter.
+
+## The email template
+
+The template is the layout every post is sent in: HTML with a style block, and variables Kestrel fills in when it sends. There is one template, used by every post. Choose **Template** in the sidebar, or **Edit template →** under **Settings → Email template**.
+
+You start from a built-in default. **Start from example** offers two starting templates to replace what's in the editor:
+
+- **Signed:** your post, then your logo, name, and tagline as a sign-off.
+- **Plain:** just your post and the footer links.
+
+Both put the unsubscribe link, a View in browser link, and your mailing address in the footer, and both end with "Powered by Kestrel". From there, edit the HTML as you like, then press **Save changes**. **Discard** throws your edits away.
+
+### Variables
+
+A variable is replaced with its value in each email. Type it exactly as shown, or it renders as empty. The **Variables** list at the bottom of the **Template** page says what each one holds.
+
+| Variable | What it holds |
+| --- | --- |
+| `{{ .Post.Body }}` | Your post, rendered from Markdown. Required. |
+| `{{ .Post.Subject }}` | The post's subject line. |
+| `{{ .Publication.Name }}` | Your publication's name. |
+| `{{ .Publication.Tagline }}` | Your tagline. |
+| `{{ .Publication.Logo }}` | Your logo as an image, or nothing when no logo is set. |
+| `{{ .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.ViewInBrowserURL }}` | The post's public page. |
+
+Kestrel won't save a template without `{{ .Post.Body }}` or `{{ .Email.UnsubscribeURL }}`. Every email has to carry the post and a way to leave. The two **Required** pills above the editor turn green or red as your template gains or loses them.
+
+### Email-only parts
+
+Wrap part of the template in `{{ if .IsEmail }}` and `{{ end }}` to keep it off each post's public page. The starting templates wrap the unsubscribe link, the View in browser link, and the mailing address this way. To show your address on the web too, move it outside the wrapped part.
+
+### Test the template
+
+The sample email at the top of the **Template** page shows the layout with sample content. Mail apps each draw email their own way, so send yourself a test to see it in a real inbox.
+
+**Send test email** sends a sample post through your saved template, to the addresses you choose. Your default test recipients, from **Settings → Default test recipients**, fill in first. With unsaved edits, the button reads **Save & send test**, since a test always uses the saved template.
+
+## Changes and scheduled posts
+
+When you schedule a post, Kestrel makes its email then, with your template and identity as they stand. So when you change the template, or a part of your identity the template prints, Kestrel makes each scheduled post's email again. Nothing changes until you confirm.
+
+When you save, a dialog lists the scheduled posts by subject and send time. Each email's look changes, while its content and send time stay the same. **Save and apply** goes ahead, and **Cancel** leaves your edits unsaved. A logo upload or removal asks the same way.
+
+Afterwards, each of those posts says its look changed since your last test. The mark shows in the editor and on the dashboard until you send a fresh test. Send one, since your earlier test no longer shows what goes out. [Scheduling and sending](05-scheduling-and-sending.md) covers tests of a scheduled post.
+
+- **Changing a part the template doesn't print** asks nothing, since it doesn't change any email.
+- **A post about to send** blocks the change. Kestrel says when you can try again, once that post has gone out.
+- **Posts already sending or sent** never change.
+
+## Who sets the From name and address
+
+Whoever runs your Kestrel sets the From name and address your emails come from. You can't change them in the dashboard, and **Settings → Email sender** shows them read-only. [Connect Amazon SES](../get-started/04-ses.md#8-set-the-provider-and-deploy) covers setting them.
+
+Next, [Check your setup](10-check-your-setup.md).

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

@@ -0,0 +1,98 @@
+# Write your first post
+
+You write a post in Markdown, in the editor. Kestrel saves it as you type and shows you the exact email under **Preview**. A test sends that same email to any inbox you name.
+
+This page covers the subject and slug, the Markdown Kestrel reads, images, and saving. It also covers sharing a post with Claude or another tab, the preview, and test emails. It stops where scheduling starts.
+
+## Start a post
+
+**New post**, on the Dashboard or on **Drafts**, creates a draft and opens it in the editor. A draft stays under **Drafts** until you schedule it, and you can edit it as often as you like until then.
+
+To remove a draft, choose **Delete draft** from its ⋯ menu under **Drafts**. Its saved versions and images go with it, and it can't be undone.
+
+## The subject and the slug
+
+The **Subject** is the email's subject line. It also names the post in your lists and sets its web address. A post needs a subject before you can schedule it.
+
+The **Slug** is the last part of the post's public address. Every post you send gets a permanent page in your publication's archive, and every email links to it. With the default setup, a post with the slug `spring-update` lives at `newsletter.example.com/archive/spring-update`. Whoever runs your Kestrel chose the part before the slug, as [Configuration](../reference/01-configuration.md#archive_base_path) describes.
+
+While **Auto-generate from subject** is checked, the slug follows the subject, so "Spring update" becomes `spring-update`. Type a slug of your own to set it by hand, and it stops following the subject. Clear the field, or check the box again, to have it follow the subject.
+
+A slug uses lowercase letters, numbers, and hyphens, and Kestrel converts what you type to that form. No two posts share a slug, drafts included. When the one a post would take is already held, Kestrel adds a number, such as `spring-update-2`. The field shows the slug the post really has, so it can update a moment after you change the subject.
+
+A draft's slug can change until you schedule it, and a test email sent before a change links to the old address. Once the post is scheduled, its address never moves. **Web version ↗** shows the post's public page as it will look, and the address it will have.
+
+## Markdown
+
+Kestrel reads Markdown in GitHub's flavor and turns it into the body of your email template. The toolbar covers the common cases: **Heading**, **Bold**, **Italic**, **Quote**, **Code**, **Link**, **Bulleted list**, **Numbered list**, and **Indent**. ⌘B, ⌘I, and ⌘K work too.
+
+Tables and strikethrough work as well, since they're part of GitHub's Markdown. How a mail client draws them varies, and so does code, so check anything unusual in a test email.
+
+A few things work differently in an email:
+
+- **Line breaks.** A single line break inside a paragraph doesn't start a new line. Leave a blank line between paragraphs.
+- **HTML.** You can write HTML where Markdown falls short. Kestrel removes scripts, `<style>` blocks, forms, and event handlers, since no email needs them. Style a piece with an inline `style` attribute instead.
+- **The inbox preview.** The snippet a mail client shows beside the subject comes from the start of your post. There's no separate field for it, so make the opening lines count.
+- **The plain-text version.** Every email also carries a plain-text version made from the same post. A link becomes its text followed by its address, and an image becomes its alt text.
+
+## Images
+
+To add an image, paste it, drop it on the composer, or click **Paste, drop, or click to add images** below it. Kestrel uploads the file to the post and inserts a reference by its file name, such as `![cover.jpg](cover.jpg)`. The reference is only the name, never an address to paste.
+
+The words in square brackets are the image's alt text, which screen readers read aloud and many mail clients show while images are blocked. Kestrel starts it as the file name, so replace that with a short description: `![A stack of paperbacks on a windowsill](cover.jpg)`.
+
+- **Formats.** PNG, JPEG, WebP, or GIF. SVG isn't accepted, since most email apps don't show it.
+- **Size.** Up to 5 MB per image. Kestrel doesn't shrink the file, and every reader downloads it, so a smaller file opens faster. An image wider than the email's column is shown at the column's width.
+- **Warnings.** The preview and each test warn you about an image with no alt text, or a reference to a file the post doesn't have.
+
+Images are public, so any mail client and your archive page can load them. You can add or replace images only while the post is a draft. Uploading a file with the same name as an earlier one replaces it. Once a post is scheduled its images are fixed, and a sent post's images stay, so its emails and archive page keep showing them. Deleting a draft deletes its images.
+
+## Saving and versions
+
+The editor saves on its own, after a short pause in your typing and never more than half a minute late. **Save draft**, or ⌘S, saves at once.
+
+Beside **Save draft**, the save cue says where you stand: Unsaved, Saving…, or Saved. If a save fails, the cue turns red with "Not saved:" and the reason, until a save succeeds. After a dropped connection the editor tries again on its own.
+
+Every save keeps a whole version of the post. The editor doesn't show that history, but Claude can read it, as [Working with Claude](07-working-with-claude.md) describes.
+
+## When someone else edits the same post
+
+Kestrel never lets one save silently overwrite another. That matters when the same post is open in a second tab or browser, or Claude is editing it for you.
+
+When another writer saves a newer version, a banner says so and names who, with Claude's saves shown as "Claude". It appears while you're still writing, not only when you save. Saving pauses until you choose:
+
+- **Reload** loads their version, and discards your unsaved edits.
+- **Keep editing** keeps yours, and your next save replaces their version.
+
+Both choices lose something, so read what changed before you pick. If the post is scheduled elsewhere, the banner says it can no longer be edited here. If it's deleted elsewhere, the editor says so and returns to **Drafts**.
+
+## Preview
+
+**Preview** shows the post as the email, made by the same code that makes your test emails and the send itself. It saves your latest edits first, so what you see is the post as it stands. Any warnings, such as a missing subject or alt text, show beneath it.
+
+Three views show the post, each for one purpose:
+
+- **Preview** is the email, for a quick look at layout.
+- **Send test email** is the email in a real inbox, where rendering finally counts.
+- **Web version ↗** is the post's public archive page, before it's public.
+
+Inside the preview, the email's "view in browser" link opens the web version, since the public page doesn't exist until the post sends. Mail clients each draw email a little differently, so trust a test over the preview.
+
+## Test emails
+
+**Send test email** opens a dialog that takes one or more addresses, one per line. Each gets its own copy of the email, and nobody on your list receives anything. The addresses in **Settings → Default test recipients** fill the dialog for you.
+
+A test is the real email. It saves your draft first, then sends it through the same template and code as the send to your list. So a clean test means a clean send. Once a post is scheduled, a test sends the exact copy that will go out.
+
+When some addresses don't get the test, the dialog stays open with only those left, and says why. **Send test** again tries just those, so no one gets a second copy.
+
+A few links in a test behave differently from the real send:
+
+- **Unsubscribe.** A test carries an unsubscribe link and the one-click unsubscribe header, so you can check both. Neither unsubscribes anyone. The link opens the page a subscriber sees, marked as a test and showing a sample address.
+- **View in browser.** The link points at the post's public address, which shows a page saying the post appears there once it's sent. It works once the send starts.
+
+A test needs an email provider. Until whoever runs your Kestrel connects one, the editor lets you write and preview but not send tests. [Connect Amazon SES](../get-started/04-ses.md) is their step.
+
+## Next
+
+When the test looks right, [Scheduling and sending](05-scheduling-and-sending.md) covers putting the post on the schedule. On a new publication, finish setting up first: [Share your subscribe link](09-share-your-subscribe-link.md).