frontpage-host 0.2.10 → 0.2.12

package/AGENTS.md

@@ -255,6 +255,8 @@ frontpage doctor --json
 
 ## People groups, stages, rules, and imports
 
+New owner-added and CSV-imported contacts default to allowed for marketing. Explicit unknown/not_allowed choices and saved refusals, unsubscribes and delivery restrictions still apply. Imports keep their accepted policy on retry. `mail people --json` returns a specific `reasonCode` for unavailable recipients.
+
 Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `attachments`, `import`, and `company`. Use `frontpage mail campaign` for one-off group/stage/list audiences in Emails. Every editor action is available through these commands or `frontpage people workspace OPERATION --file payload.json`. Full operations and examples: [PEOPLE.md](./PEOPLE.md); public guide: https://frontpage.host/developers/people. Automated emails select a saved template or series. Campaigns use their own drafts.
 
 
@@ -273,3 +275,7 @@ Currency is owned by Payments and read by Store, Offerings and invoices. Offerin
 Customer Inbox setup: enable website chat through Inbox settings; Frontpage public sites load it without a file edit or publish. Other websites use the explicit widget snippet. `get website` reports managed addresses/public availability. Website knowledge is default-on, read-only public retrieval; `websiteKnowledge.enabled:false` disables it. Source toggles, attention filtering and receipt cursors use the documented versioned resources.
 
 Customer Inbox team guidance: administrators may set `guidanceEmail` through the versioned settings write. The owner toolbar has the same setting. Teammates reply as the configured mailbox; no teammate account or separate mailbox activation is needed. Do not set it to the public Inbox address. Conversation management uses close/reopen; do not use read/trash/restore.
+
+## Emails workspace workflows
+
+See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.

package/MAIL.md

@@ -0,0 +1,87 @@
+# Emails: authoring, recipients and delivery
+
+Use `frontpage help mail --json` for command discovery. The existing CLI binary and API namespace stay in place. Site roles and the CLI plan gate still apply. A viewer can read; an editor or owner can change email settings and content. These commands never grant platform admin rights or change a platform kill switch.
+
+## Save an email and its series together
+
+`frontpage mail save --file save.json --site YOUR_SITE --json` calls `POST /api/v1/sites/YOUR_SITE/mail/save`.
+
+```json
+{
+  "requestKey": "a-stable-key-for-this-save",
+  "document": {
+    "kind": "template",
+    "name": "Welcome",
+    "subject": "Welcome, {{first_name}}",
+    "preheader": "Here is your next step.",
+    "blocks": [{ "type": "paragraph", "text": "Thanks for joining us." }],
+    "variables": []
+  },
+  "series": { "name": "Welcome series", "steps": [] },
+  "append": true,
+  "delayMinutes": 1440
+}
+```
+
+This creates a shared template and an Off series with one step. It sends nothing and enrolls no one. The first step always has zero delay. Later step delays accept integer minutes from 0 through 525600; a series has at most 12 steps.
+
+For an existing record, supply `id` and `expectedUpdatedAt` from `mail template get` / `mail email get` / `mail series get`. To edit an existing shared template from a series, send both the complete `document` and complete pending `series` in one save, omitting `append`. **Save & return saves both**, including pending names, steps, removals and waits. To add a new step, send a new template plus the source series and `append:true`.
+
+The response reports `complete:true` and the saved records. Keep the exact payload and requestKey after a lost response. Repeating it returns the saved IDs without adding another template or step. Do not reuse a key for different content. A 409 means the saved version changed: retain the draft, read the current records, review the changes, and use a new key for the revised save. A failed transaction saves neither half. Subject, preview text, name and valid content are required. Saving never activates a series or sends email. Queued emails keep their saved content.
+
+The workspace's Back button returns to the source series and keeps unfinished work. A test sends only to the signed-in account in the workspace, and does not complete a step task. CLI test recipients remain explicit and subject to the existing test restrictions.
+
+## Campaign recipients
+
+Include `audience` with a one_off document in the same `mail save` request. Supported keys are `personIds`, `groupIds`, `stageIds`, `filters`, and `addresses`. Use `audience:null` to clear the saved selection. Addresses normalize to lower case. Saving addresses never creates CRM people or records consent. Recipient-only edits count as changes and save with the campaign.
+
+For an audience-only change, the existing `mail campaign audience --id DOCUMENT_ID --file audience.json` remains supported. Its JSON is `{"audience":{"personIds":["PERSON_ID"]}}`, or `{"audience":null}` to clear. Saved selection is intent; final send review resolves groups and filters again, checks permission and delivery restrictions, and freezes the actual recipients and content. Started campaigns cannot be edited or sent twice with a new key. Read `PEOPLE.md` for preview/send review and stable send keys.
+
+## People directory and enrollment
+
+```bash
+frontpage mail people --sort newest --page 1 --site YOUR_SITE --json
+frontpage mail people --q alex --source signup --availability eligible --sort name --page 1 --site YOUR_SITE --json
+frontpage mail people --selected PERSON_ID,OTHER_PERSON_ID --selected-only --page 1 --site YOUR_SITE --json
+```
+
+Sort values: `newest`, `oldest`, `name`. Added order uses the CRM record's added date, not recent activity or the first historical event. Source values: form, booking, signup, payment, order. Availability: all, eligible, restricted. The response includes 20 rows per numbered page, total, added date, source and availability. Every query stays inside the authorized site. Search and availability apply before paging.
+
+Use existing `frontpage people workspace series.preview --file preview.json` then `series.enrol --file batch.json` for reviewed CRM enrollment. Preview input: `{ "seriesId":"SERIES_ID", "personIds":["PERSON_ID"] }`. Each returned batch contains personIds and reviewToken; commit with those fields, seriesId and a stable requestKey. Reuse each batch's key after a network error. Receipts preserve partial outcomes. Enrollment saves immediately and never requires Save series afterward. Existing enrollment is deduplicated across all states; completed/cancelled people do not restart.
+
+- **Off:** eligible people wait at step 1. Enrollment creates no queued message, first-template snapshot, due date or allowance reservation. No sender readiness or send meter is needed to record waiting people.
+- **On:** the first email becomes ready, subject to normal permission, sender, kill switch, send window and allowance checks.
+- **Turning Off:** pending series messages stop before provider handoff. A message already accepted by the provider cannot be recalled.
+- **Turning On again:** new waiting people begin at step 1. Started people resume their next unsent step with its saved due date; an overdue step can send on the next pass. Each later wait starts after successful provider acceptance. Off time never skips a new person's first email or causes all later steps to send at once.
+
+`mail series activate SERIES_ID` sets status active (On); `mail series pause SERIES_ID` sets paused (Off). Stored draft and paused both display Off. `mail series get/list` includes enrolledCount (waiting + current in progress/paused; excludes completed/cancelled) and waitingCount. `mail enrolments list` shows progress; cancel remains available while Off. The direct `mail send series` command also enrolls while Off and returns accepted enrollment IDs with no sends. Empty sends is not a delivery claim.
+
+Selections with IDs use a read-only `POST /api/v1/sites/YOUR_SITE/mail/people` body to avoid URL limits. Ordinary directory queries use GET. Both call the same scoped query; neither writes CRM records.
+
+## Settings and suppressions
+
+```bash
+frontpage mail settings set --header-align center --window-start 540 --window-end 1020 --hourly-cap 100 --site YOUR_SITE
+frontpage mail settings set --file settings.json --site YOUR_SITE --json
+```
+
+The settings JSON accepts exactly replyTo, postalLine, fromName, timezone, sendWindowStart, sendWindowEnd, hourlyCap and headerAlign. Omitted fields stay unchanged. Null clears replyTo, postalLine, fromName or hourlyCap. Window values are integer minutes after midnight (0–1439), hourlyCap is null or 1–1000, timezone is an IANA time zone, and headerAlign is left/center/right. A business postal address is still required for actual marketing sends. `--hourly-cap null` clears that cap. A settings save, content edit, read, cancellation or switch Off does not depend on the send meter.
+
+`mail suppress list|add|rm` uses the existing site suppression service. Adding stops that site's marketing campaigns/series and cancels active enrollments. Transactional receipts and support replies follow separate rules. Removing a suppression does not restore consent, resubscribe someone or restart cancelled series.
+
+## Sent history
+
+```bash
+frontpage mail sends list --q alex --status delivered --type campaign --page 1 --limit 20 --site YOUR_SITE --json
+frontpage mail sends get SEND_ID --site YOUR_SITE --json
+```
+
+Types: campaign, series, confirmation, template, test, inline. Search matches recipient/subject across all permitted rows. Status uses the stored ledger value (pending/claimed are queued). Count and numbered pages use the same site/filter scope, ordered by creation time then ID. Existing cursor pagination remains available; use either cursor or page. `createdAt` is queue creation, not delivery time. Details expose saved content, current status/error, attempts and source availability; preview sender/brand details use current settings. Deleted source records do not delete history. No resend/requeue action is added.
+
+## Internal agent parity
+
+The owner agent uses the same services through save_mail_editor, get_mail_people, get_mail_send, update_mail_series, set_mail_series_steps, set_mail_settings and the existing send/preview/enrollment tools. remove_mail_suppression matches the CLI's existing authorized removal. Discuss and Build register the same Email capabilities. Tool schemas and runtime instructions describe complete saves, Off enrollment, waiting/resume timing, all settings/null resets, history filters and retry handling. The agent never takes site authority from model input.
+
+Hosted developer guides and article bodies must be updated through the supported Frontpage CLI, using current base revisions. Never edit a customer site's Git branch or invent a second API version for this cutover.
+
+The people directory returns `reasonCode`: `allowed`, `permission_missing`, `not_allowed`, `unsubscribed`, `delivery_restricted`, or `no_active_email`. These explain the shared marketing permission decision; selecting people never changes it. New owner additions and CSV imports default to allowed. Explicit refusals, unsubscribes and delivery restrictions still block sending.

package/PEOPLE.md

@@ -235,7 +235,7 @@ The simple editor offers Purchases, Activity, and Contact details. Existing adva
 | set\_follow\_up            | minutes                         | Set a follow-up after this many minutes.                        |
 | clear\_follow\_up          | —                               | Clear the person’s follow-up.                                   |
 | send\_template             | templateId                      | Send a saved template if eligible.                              |
-| start\_series              | seriesId                        | Start an active series with saved steps.                        |
+| start\_series              | seriesId                        | Enroll in a saved series. Off waits at step 1; On starts sending.                        |
 | cancel\_series             | seriesId                        | Stop this group’s enrollment; requires a group/stage trigger.   |
 
 A rule accepts 1–10 actions. Add/remove/move actions target manual groups; automatic groups use conditions and owner exceptions. `fromStageIds` prevents a late event from resetting someone who has moved further through the funnel.
@@ -301,7 +301,7 @@ Timed rules use minutes: 2880 is two days. They run through the worker, not a br
 
 ## Attach an email to a group or stage
 
-Use one action, **Attach an email**, then choose a saved email template or an active series. An attachment creates a normal editable rule on group entry or stage entry. Campaigns are one-off emails and cannot be selected for automation.
+Use one action, **Attach an email**, then choose a saved email template or a series with saved steps. An Off series enrolls people waiting at step 1; turning it On starts them. An attachment creates a normal editable rule on group entry or stage entry. Campaigns are one-off emails and cannot be selected for automation.
 
 Save a reusable template as `welcome.json`:
 
@@ -347,7 +347,7 @@ Permission belongs to the email address and site. Groups and stages never grant
 | Entry point | New contact | Existing contact |
 | --- | --- | --- |
 | Owner UI, `people add`, public API `POST /people`, agent `add_person` | `allowed` by default, recorded as an owner assertion | Omitted choice preserves the saved decision. Explicit choices can fill unknown permission; add cannot reverse a recorded refusal, mailing-list unsubscribe or suppression. |
-| CSV import | Unknown unless an explicit list-wide choice or row value supplies permission | List-wide choices leave existing decisions alone. Row values can record permission, but cannot reverse a refusal, unsubscribe or suppression. |
+| CSV import | Allowed by default; an explicit list-wide choice or row value can select otherwise | List-wide choices leave existing decisions alone. Row values can record permission, but cannot reverse a refusal, unsubscribe or suppression. |
 | Forms, orders, bookings and account events | Unknown unless a supported subscriber signup records agreement | Preserve saved permission; purchases and signup timestamps are not email agreement. |
 | Group, stage, name, phone, note and follow-up changes | No permission change | No permission change. Changing an email does not transfer an old address's grant; a recorded refusal stays in effect. |
 
@@ -441,7 +441,7 @@ Alex Rivera,alex@example.com,,
 Phone customer,,+12025550199,
 ```
 
-Map exact header names in `mapping.json`. The permission column is optional. `yes`/`true` records an owner assertion and `no`/`false` records refusal. A supplied row value takes priority over the list-wide choice; duplicate rows keep a negative decision. Set top-level `emailPermission` to `allowed`, `unknown`, or `not_allowed` for new people whose row has no permission value. Omission defaults to unknown. List-wide choices never change existing decisions. Imports preserve saved refusals, unsubscribe and suppression. Changing the list choice requires a new request key.
+Map exact header names in `mapping.json`. The permission column is optional. `yes`/`true` records an owner assertion and `no`/`false` records refusal. A supplied row value takes priority over the list-wide choice; duplicate rows keep a negative decision. Set top-level `emailPermission` to `allowed`, `unknown`, or `not_allowed` for new people whose row has no permission value. Omission defaults to allowed for new imports. The accepted import stores its effective policy, so retries keep the original choice. List-wide choices never change existing decisions. Imports preserve saved refusals, unsubscribe and suppression. Changing the list choice requires a new request key.
 
 ```
 {
@@ -454,7 +454,7 @@ Map exact header names in `mapping.json`. The permission column is optional. `ye
   "groupIds": [
     "GROUP_ID"
   ],
-  "emailPermission": "unknown"
+  "emailPermission": "allowed"
 }
 ```
 
@@ -645,6 +645,6 @@ frontpage people workspace series.preview --site YOUR_SITE --data '{"seriesId":"
 
 To enrol, copy each returned batch's `personIds` and `reviewToken` into `series.enrol`, adding `seriesId` and a unique stable `requestKey`. Preview returns batches of five; the service accepts at most 25 per request. Reuse the original payload and key after a lost response. Results distinguish enrolled, already enrolled, skipped and failed. A new preview uses new keys. Never enrol or send without the user's explicit instruction.
 
-Manual series starts use selected person IDs, an active series and the normal queue. Confirmation queues its first email; saved delays schedule later steps. The review lists permission exclusions and remaining allowance. It never activates a paused series or restarts an existing enrolment, including one bound to a person whose email changed. Delivery rechecks saved restrictions. Contact groups and permission stay unchanged.
+Manual series enrollment uses selected person IDs and saved steps. Off records real enrollment waiting at step 1, without a send, snapshot, timer or allowance reservation; no second Save series is needed. On starts the first email subject to sender, permission, send window and allowance checks. Turning On resumes existing people at their next unsent step with its due date intact; later waits start after successful sends. Review returns status, exclusions and nullable remainingAllowance (null while Off). It never activates a series or restarts existing, completed or cancelled enrollment, including a person whose email changed. Delivery rechecks saved restrictions. Contact groups and permission stay unchanged. Campaign recipient intent also supports explicit addresses and null to clear; saving never sends or grants consent.
 
 People supplies first-name and unsubscribe values. If content uses order, booking or other caller-only variables, edit the independent campaign or choose another series. Do not invent values or send empty required context.

package/README.md

@@ -90,3 +90,7 @@ frontpage store items get camp-hat --site my-site --json
 ```
 
 A whole stock count of `0` means sold out; `unlimited` sends JSON null. Omit stock on update to keep it. To rename existing option types, pass an `optionNames` list with the same number of names through `items update --file`. To return to one default SKU, pass `{"optionNames":[]}`. The existing first live variant supplies the regular price, sale price (including no sale), and stock (including unlimited). Inspect the live variants first and read back the result; other live variants are archived. Use `variants add` to turn options on. Do not recreate the product.
+
+## Emails workspace workflows
+
+See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.

package/dist/commands/mail.js

@@ -4,12 +4,13 @@ import { resolveSlug } from "../site.js";
 import { CliHttpError, EXIT_OK, EXIT_USAGE, exitCodeForError, v1Delete, v1Get, v1Patch, v1Post, v1Put, } from "../http/client.js";
 import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.js";
 import { emitErr, emitOk, isJson } from "../runtime.js";
-const USAGE = "Usage: frontpage mail settings|email|template|series|send|sends|enrolments|suppress … [--site <slug>] [--json]";
+const USAGE = "Usage: frontpage mail settings|email|template|series|save|people|send|sends|enrolments|suppress … [--site <slug>] [--json]";
 const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function requireId(work, kind) {
     const fromFlag = takeFlag(work, "--id");
     const positional = work.find((a) => !a.startsWith("-"));
-    const raw = fromFlag ?? (positional ? work.splice(work.indexOf(positional), 1)[0] : undefined);
+    const raw = fromFlag ??
+        (positional ? work.splice(work.indexOf(positional), 1)[0] : undefined);
     if (!raw || !ID_RE.test(raw)) {
         throw new CliHttpError(`${kind} not found.`, EXIT_USAGE, 404, "not_found");
     }
@@ -35,7 +36,10 @@ function parseVars(pairs) {
     return vars;
 }
 function parseRecipients(work) {
-    const tos = takeAll(work, "--to").flatMap((v) => v.split(",").map((s) => s.trim()).filter(Boolean));
+    const tos = takeAll(work, "--to").flatMap((v) => v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean));
     const name = takeFlag(work, "--name");
     const vars = parseVars(takeAll(work, "--var"));
     if (tos.length === 0) {
@@ -83,6 +87,45 @@ export async function runMail(args) {
         if (group === "campaign")
             return await runCampaign(slug, rest.slice(1));
         const base = `/api/v1/sites/${encodeURIComponent(slug)}/mail`;
+        if (group === "save") {
+            const work = rest.slice(1), file = takeFlag(work, "--file");
+            assertNoUnknownFlags(work, "mail");
+            if (!file)
+                throw new CliHttpError("Use mail save --file save.json. Keep its requestKey and payload unchanged for retries.", EXIT_USAGE, 0, "bad_request");
+            const data = await v1Post(`${base}/save`, await readJsonFile(file));
+            if (isJson())
+                emitOk("mail", data);
+            else
+                console.log("Email and series changes saved.");
+            return EXIT_OK;
+        }
+        if (group === "people") {
+            const work = rest.slice(1), params = new URLSearchParams();
+            for (const flag of [
+                "q",
+                "source",
+                "sort",
+                "availability",
+                "page",
+                "selected",
+            ]) {
+                const value = takeFlag(work, `--${flag}`);
+                if (value !== undefined)
+                    params.set(flag, value);
+            }
+            if (hasFlag(work, "--selected-only"))
+                params.set("selectedOnly", "true");
+            assertNoUnknownFlags(work, "mail");
+            const data = params.has("selected")
+                ? await v1Post(`${base}/people`, Object.fromEntries(params))
+                : await v1Get(`${base}/people?${params}`);
+            if (isJson())
+                emitOk("mail", data);
+            else
+                for (const p of (data.people ?? []))
+                    console.log(`${p.id}  ${p.email ?? ""}  ${p.eligible ? "eligible" : (p.reasonCode ?? "restricted").replaceAll("_", " ")}`);
+            return EXIT_OK;
+        }
         if (group === "settings") {
             const sub = rest[1] ?? "get";
             const work = rest.slice(2);
@@ -102,12 +145,29 @@ export async function runMail(args) {
                 const replyTo = takeFlag(work, "--reply-to");
                 const fromName = takeFlag(work, "--from-name");
                 const timezone = takeFlag(work, "--timezone");
+                const file = takeFlag(work, "--file"), headerAlign = takeFlag(work, "--header-align"), start = takeFlag(work, "--window-start"), end = takeFlag(work, "--window-end"), cap = takeFlag(work, "--hourly-cap");
+                const extra = file ? await readJsonFile(file) : {};
+                if (headerAlign !== undefined)
+                    extra.headerAlign = headerAlign;
+                if (start !== undefined)
+                    extra.sendWindowStart = Number(start);
+                if (end !== undefined)
+                    extra.sendWindowEnd = Number(end);
+                if (cap !== undefined) {
+                    if (cap !== "null" &&
+                        (!Number.isInteger(Number(cap)) ||
+                            Number(cap) < 1 ||
+                            Number(cap) > 1000))
+                        throw new CliHttpError("Hourly cap must be an integer from 1 to 1000, or null.", EXIT_USAGE, 0, "bad_request");
+                    extra.hourlyCap = cap === "null" ? null : Number(cap);
+                }
                 assertNoUnknownFlags(work, "mail");
                 const data = await v1Patch(`${base}/settings`, {
-                    postalLine: postal,
-                    replyTo,
-                    fromName,
-                    timezone,
+                    ...extra,
+                    ...(postal !== undefined ? { postalLine: postal } : {}),
+                    ...(replyTo !== undefined ? { replyTo } : {}),
+                    ...(fromName !== undefined ? { fromName } : {}),
+                    ...(timezone !== undefined ? { timezone } : {}),
                 });
                 if (isJson())
                     emitOk("mail", data);
@@ -222,7 +282,8 @@ export async function runMail(args) {
                 if (isJson())
                     emitOk("mail", data);
                 else
-                    console.log((data.preview ?? {}).subject ?? "Preview ready.");
+                    console.log((data.preview ?? {}).subject ??
+                        "Preview ready.");
                 return EXIT_OK;
             }
         }
@@ -256,7 +317,9 @@ export async function runMail(args) {
                 assertNoUnknownFlags(work, "mail");
                 if (!name)
                     throw new CliHttpError("Usage: frontpage mail series create --name …", EXIT_USAGE, 0, "bad_request");
-                const data = await v1Post(`${base}/series`, { name });
+                const data = await v1Post(`${base}/series`, {
+                    name,
+                });
                 if (isJson())
                     emitOk("mail", data);
                 else
@@ -310,7 +373,11 @@ export async function runMail(args) {
                 let steps = [];
                 if (file) {
                     const body = await readJsonFile(file);
-                    steps = Array.isArray(body.steps) ? body.steps : Array.isArray(body) ? body : [];
+                    steps = Array.isArray(body.steps)
+                        ? body.steps
+                        : Array.isArray(body)
+                            ? body
+                            : [];
                 }
                 else {
                     steps = stepFlags.map(parseStepFlag);
@@ -350,8 +417,14 @@ export async function runMail(args) {
                 const id = requireId(restKind, kind === "series" ? "Series" : "Document");
                 const recipients = parseRecipients(restKind);
                 assertNoUnknownFlags(restKind, "mail");
-                const path = kind === "series" ? `${base}/series/${id}/send` : `${base}/${kind === "email" ? "emails" : "templates"}/${id}/send`;
-                const data = await v1Post(path, { recipients, wait, test });
+                const path = kind === "series"
+                    ? `${base}/series/${id}/send`
+                    : `${base}/${kind === "email" ? "emails" : "templates"}/${id}/send`;
+                const data = await v1Post(path, {
+                    recipients,
+                    wait,
+                    test,
+                });
                 if (isJson())
                     emitOk("mail", data);
                 else
@@ -365,10 +438,16 @@ export async function runMail(args) {
             const work = rest.slice(2);
             if (sub === "list") {
                 const batchId = takeFlag(work, "--batch");
+                const filters = new URLSearchParams();
+                for (const flag of ["q", "status", "type", "page"]) {
+                    const value = takeFlag(work, `--${flag}`);
+                    if (value !== undefined)
+                        filters.set(flag, value);
+                }
                 const limit = takeFlag(work, "--limit");
                 const cursor = takeFlag(work, "--cursor");
                 assertNoUnknownFlags(work, "mail");
-                const params = new URLSearchParams();
+                const params = filters;
                 if (batchId)
                     params.set("batchId", batchId);
                 if (limit)
@@ -402,8 +481,13 @@ export async function runMail(args) {
             const work = rest.slice(2);
             if (sub === "list") {
                 const seriesId = takeFlag(work, "--series");
-                assertNoUnknownFlags(work, "mail");
                 const params = new URLSearchParams();
+                for (const name of ["q", "offset", "limit"]) {
+                    const value = takeFlag(work, `--${name}`);
+                    if (value !== undefined)
+                        params.set(name, value);
+                }
+                assertNoUnknownFlags(work, "mail");
                 if (seriesId)
                     params.set("seriesId", seriesId);
                 const qs = params.toString();
@@ -437,7 +521,8 @@ export async function runMail(args) {
                 if (isJson())
                     emitOk("mail", data);
                 else {
-                    const rows = data.suppressions ?? [];
+                    const rows = data.suppressions ??
+                        [];
                     for (const row of rows)
                         console.log(`${row.email ?? ""}  ${row.reason ?? ""}`);
                 }

package/dist/completions/generate.js

@@ -28,6 +28,7 @@ _frontpage_completions() {
     people) COMPREPLY=( $(compgen -W "list get add set note rm-note follow-up hide unhide" -- "\${cur}") ) ;;
     routines) COMPREPLY=( $(compgen -W "list get add set pause resume rm run runs" -- "\${cur}") ) ;;
     buttons) COMPREPLY=( $(compgen -W "list get create update archive restore" -- "\${cur}") ) ;;
+    mail) COMPREPLY=( $(compgen -W "save people campaign settings email template series send sends enrolments suppress --file --q --status --type --page --limit --cursor --source --sort --availability --selected --selected-only --offset --header-align --window-start --window-end --hourly-cap --site --json" -- "\${cur}") ) ;;
     payments) COMPREPLY=( $(compgen -W "status settings connect availability activity buttons tax invoices recurring customers --file --operation-key --preview-hash --person --email --description --amount-cents --cadence --first-date --time-zone --due-days --no-open --site --json --yes" -- "\${cur}") ) ;;
     store) COMPREPLY=( $(compgen -W "items variants categories settings orders import" -- "\${cur}") ) ;;
     modules)
@@ -74,6 +75,7 @@ _frontpage() {
         analytics) _values 'subcommand' dashboard summary query funnel timeseries compare sql ;;
         people) _values 'subcommand' list get add set note rm-note follow-up hide unhide ;;
         routines) _values 'subcommand' list get add set pause resume rm run runs ;;
+        mail) _values 'subcommand' save people campaign settings email template series send sends enrolments suppress ;;
         buttons) _values 'subcommand' list get create update archive restore ;;
         payments) _values 'subcommand' status settings connect availability activity buttons tax invoices recurring customers ;;
         store) _values 'subcommand' items variants categories settings orders import ;;
@@ -114,6 +116,7 @@ export function generateFishCompletion() {
         `complete -c frontpage -n "__fish_seen_subcommand_from analytics" -a "dashboard summary query funnel timeseries compare sql"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from people" -a "list get add set note rm-note follow-up hide unhide"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from routines" -a "list get add set pause resume rm run runs"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from mail" -a "save people campaign settings email template series send sends enrolments suppress"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from buttons" -a "list get create update archive restore"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from payments" -a "status settings connect availability activity buttons tax invoices recurring customers"
 complete -c frontpage -n "__fish_seen_subcommand_from store" -a "items variants categories settings orders import"`,

package/dist/registry.js

@@ -38,9 +38,9 @@ export const COMMANDS = [
         summary: "Save an API key to the OS keychain",
         usage: "frontpage login [api-key]",
         topics: ["auth"],
-        examples: ['frontpage login', 'frontpage login "$FRONTPAGE_API_KEY"'],
+        examples: ["frontpage login", 'frontpage login "$FRONTPAGE_API_KEY"'],
         flags: [
-            "FRONTPAGE_API_KEY env overrides keychain after login for that process"
+            "FRONTPAGE_API_KEY env overrides keychain after login for that process",
         ],
         seeAlso: ["whoami", "doctor", "logout"],
     },
@@ -71,7 +71,7 @@ export const COMMANDS = [
         topics: ["auth", "sync"],
         examples: ["frontpage use arbiter"],
         dangers: [
-            "Clears baseCommitSha when switching sites — run pull again before push"
+            "Clears baseCommitSha when switching sites — run pull again before push",
         ],
         seeAlso: ["link", "pull", "status"],
     },
@@ -207,7 +207,7 @@ export const COMMANDS = [
         examples: [
             "frontpage open",
             "frontpage open /updates",
-            "frontpage open --path /pricing"
+            "frontpage open --path /pricing",
         ],
         flags: [
             "Optional site-relative path appended to https://<slug>.frontpage.host",
@@ -424,14 +424,14 @@ export const COMMANDS = [
             "frontpage customer-inbox get settings",
             "frontpage customer-inbox put settings --file ./inbox-settings.json --request-key settings_revision_1",
             "frontpage customer-inbox get conversations",
-            "frontpage customer-inbox get knowledge"
+            "frontpage customer-inbox get knowledge",
         ],
         flags: [
             "Internal plans and the site pilot apply",
             "Writes require a stable --request-key and a JSON file; reuse both on retries",
             "Human CLI access can guide, take over and reply; website-agent tools have management scope only",
             "Luna and 10× AI billing are fixed",
-            "Full request examples: CUSTOMER-INBOX.md"
+            "Full request examples: CUSTOMER-INBOX.md",
         ],
         seeAlso: ["people", "usage"],
     },
@@ -449,7 +449,7 @@ export const COMMANDS = [
         topics: ["content"],
         examples: [
             "frontpage routines list",
-            "frontpage routines add --cadence weekly --weekdays tue,thu,fri --hours 8am,12pm,4pm --timezone America/Chicago --name \"Weekday check\" --prompt \"Review new form submissions and reply to each customer.\"",
+            'frontpage routines add --cadence weekly --weekdays tue,thu,fri --hours 8am,12pm,4pm --timezone America/Chicago --name "Weekday check" --prompt "Review new form submissions and reply to each customer."',
             "frontpage routines pause <id>",
             "frontpage routines resume <id>",
             "frontpage routines run <id>",
@@ -480,8 +480,8 @@ export const COMMANDS = [
             "frontpage people list",
             "frontpage people add --email alex@example.com --name Alex",
             "frontpage people set <id> --status working",
-            "frontpage people set <id> --line1 \"12 Main\" --city Austin --region TX --postal 78701 --country US",
-            "frontpage people note <id> --body \"Called them\"",
+            'frontpage people set <id> --line1 "12 Main" --city Austin --region TX --postal 78701 --country US',
+            'frontpage people note <id> --body "Called them"',
             "frontpage people follow-up <id> --at 2026-09-12T00:00:00Z",
             "frontpage people hide <id>",
             "frontpage people tag <id> --add vip",
@@ -491,7 +491,7 @@ export const COMMANDS = [
         flags: [
             "Workspace: groups list|get|create|update|archive|restore|preview; stages create|update|reorder|archive|restore; membership get|add|remove|move|stage|advance|override|hold; rules list|get|create|update|enable|pause|archive|validate|preview|runs|retry; attachments create; import preview|start|get|retry; person permission; audience preview; overview; sources",
             "All workspace operations accept --file JSON or --data JSON. Named flags: --id --label --name --group --stage --person --from-group --mode --color --position --terminal --enabled --hold --allowed --archived --reset --override include|exclude|auto --email-kind template|series --email-id --rule --run --cursor --limit --request-key. Boolean flags take true|false. Complex conditions/actions/mappings use JSON.",
-            "CSV: --csv PATH plus --file mapping.json. import start requires a stable --request-key. Retry the same import with the same key and contents.",
+            "CSV: --csv PATH plus --file mapping.json. New contacts default to allowed; JSON emailPermission can select unknown or not_allowed. Row values override the list choice; saved refusals, unsubscribes and suppressions remain protected. import start requires a stable --request-key. Retry the same import with the same key and contents.",
             "list/export: --group GROUP_ID --stage STAGE_ID. See package PEOPLE.md for full examples and every JSON shape.",
             "list: --q --status --source --form-slug --follow-up due|upcoming|none --hidden --sort --last-seen-days --tag --limit --cursor",
             "add requires --email and/or --phone (never name alone). New contacts default to owner-asserted email permission; --email-permission allowed|unknown|not_allowed changes this choice. Existing default decisions stay saved; withdrawals/restrictions cannot be overridden by add.",
@@ -573,10 +573,10 @@ export const COMMANDS = [
     {
         name: "mail",
         summary: "Emails: campaign drafts, People audiences, templates, series, and sends",
-        usage: "frontpage mail settings|email|template|series|campaign|send|sends|enrolments|suppress … [--site <slug>] [--json]",
+        usage: "frontpage mail save|people|settings|email|template|series|campaign|send|sends|enrolments|suppress … [--site <slug>] [--json]",
         topics: ["content"],
         examples: [
-            "frontpage mail settings set --postal \"100 Main St\" --reply-to you@example.com",
+            'frontpage mail settings set --postal "100 Main St" --reply-to you@example.com',
             "frontpage mail email create --file draft.json --name Hours",
             "frontpage mail send --file email.json --to ada@example.com --wait",
             "frontpage mail send template <id> --to ada@example.com --var first_name=Ada",
@@ -584,6 +584,11 @@ export const COMMANDS = [
             "frontpage mail suppress add --email bounce@example.com",
         ],
         flags: [
+            "save --file save.json: one retry-safe email/series save; existing records need expectedUpdatedAt. See MAIL.md.",
+            "people --q --source --sort newest|oldest|name --availability all|eligible|restricted --page --selected --selected-only.",
+            "settings set --file settings.json supports all eight fields and null resets; --header-align, --window-start, --window-end, --hourly-cap null|1..1000.",
+            "sends list --q --status --type campaign|series|confirmation|template|test|inline --page 1 --limit 20.",
+            "Series status active means On; paused/draft mean Off. Enrollment while Off waits at step 1, without sending. Existing people resume their next unsent step.",
             "campaign preview|audience|send|get. --id DRAFT_ID, --file audience.json ({audience:{groupIds|stageIds|personIds|filters}}). send requires --request-key; reuse it after a network error. Templates/series are for automation; campaigns have separate drafts. See PEOPLE.md.",
             "email list is unsent drafts only. Sent one-offs are mail sends list",
             "send --file is an inline one-off (no saved document)",
@@ -617,10 +622,10 @@ export const COMMANDS = [
         examples: [
             "frontpage seo get /",
             "frontpage seo get --path /updates",
-            "frontpage seo set --path / --title \"Home\"",
+            'frontpage seo set --path / --title "Home"',
         ],
         flags: [
-            "get accepts positional path or --path (flag wins); unknown leftover flags fail closed"
+            "get accepts positional path or --path (flag wins); unknown leftover flags fail closed",
         ],
     },
     {
@@ -838,7 +843,7 @@ export const TOPICS = {
   # Store catalog + live storefront: https://frontpage.host/developers/store
   # Integer cents only. $49.99 is 4999. stock --add/--remove are signed delta.
   # Markup: data-fp-store-grid / data-fp-store-product / data-fp-cart. One item.astro, not one file per product.
-  frontpage mail settings|email|template|series|send|sends|enrolments|suppress
+  frontpage mail save|people|settings|email|template|series|send|sends|enrolments|suppress
   frontpage seo get [/path|--path /path] | seo set --path /
   frontpage redirects list|set|rm --from /old --to /new
   frontpage articles list|content|create-section|create-article|set-draft|…

package/llms.txt

@@ -34,6 +34,8 @@
 
 ## People groups, stages, rules, and imports
 
+New owner-added and CSV-imported contacts default to allowed for marketing. Explicit unknown/not_allowed choices and saved refusals, unsubscribes and delivery restrictions still apply. Imports keep their accepted policy on retry. `mail people --json` returns a specific `reasonCode` for unavailable recipients.
+
 Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `attachments`, `import`, and `company`. Use `frontpage mail campaign` for one-off group/stage/list audiences in Emails. Every editor action is available through these commands or `frontpage people workspace OPERATION --file payload.json`. Full operations and examples: [PEOPLE.md](./PEOPLE.md); public guide: https://frontpage.host/developers/people. Automated emails select a saved template or series. Campaigns use their own drafts.
 
 Customer Inbox (Scale and internal sites): CUSTOMER-INBOX.md. Settings, widget, knowledge, human guidance/relay, lifecycle, export/download and recovery. The owner toolbar manages all site-wide Inbox operations through manage_customer_inbox, including conversations, files and recovery, but cannot edit/unlock locked knowledge. The support agent is restricted to its verified customer and cannot change shared knowledge from customer input. No borrowed human credentials.
@@ -47,3 +49,7 @@ Offerings own every standalone Pay now payment. Use `frontpage payments buttons
 Payments owns Stripe currency. Read Offering receiptVariables before creating a confirmation template; attach it through Payments. Forms use submitted input names. Full receipt contract: PAYMENTS.md.
 
 Customer Inbox: Frontpage website chat uses one settings toggle, no website edit/publish. get website shows public availability/managed addresses. websiteKnowledge.enabled controls default-on support website reads; no source or private-preview access. Source-ID toggles, attention filtering and held receipt pagination are supported. See CUSTOMER-INBOX.md.
+
+## Emails workspace workflows
+
+See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "AGENTS.md",
     "llms.txt",
     "PEOPLE.md",
+    "MAIL.md",
     "CUSTOMER-INBOX.md",
     "PAYMENTS.md"
   ],