@softure-ai/mailing 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,40 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`mailing@x.y.z`).
 
+## 0.1.8
+
+- `checkSenderDns` takes `expectDmarc: { policy, subdomainPolicy, adkim, aspf }`: a DMARC record weaker than it (a
+  lower policy, relaxed or absent alignment where strict is required, `pct` under 100) fails with the new finding
+  `weak`. Without the option nothing changes.
+- `replyTo` checks that the reply domain accepts mail: MX records that are not a null MX (finding `null-mx`) and at
+  most one SPF record.
+- `returnPath: [{ host, targetDomain? }]` checks return-path hosts: a CNAME (to the target domain, else finding
+  `unexpected-target`) or MX records. New `resendReturnPath(domain)` gives Resend's `send.` and `rsend.` hosts.
+- `SenderDnsReport` has two new keys, `replyTo` (`null` when not asked) and `returnPath` (`[]` when not asked); new
+  resolver options `resolveMx` and `resolveCname`.
+- `softure-mail dns`: `--dmarc-policy`, `--dmarc-sp`, `--dmarc-adkim`, `--dmarc-aspf`, `--reply-to`,
+  `--return-path`, `--resend-return-path`; without `--domain` it also checks the configured `replyTo`. New output
+  lines `REPLY` and `PATH`.
+
+## 0.1.7
+
+- A failed send keeps the provider's HTTP status: `SendMailResult` failures and `deliverOnce` outcomes carry
+  `httpStatus`, and `mailing.deliveries.provider_status` stores it (migration `0003`).
+- New codes `mailing.provider_refused` (401/403: the key or account is refused) and `mailing.quota_exceeded` (429
+  that is not a rate limit), with en/pl copy. Before, `resend()` read 401/403 as `rejected` and 429 as `unavailable`.
+  Provider adapters may answer the new `refused` and `quota_exceeded` statuses.
+- `deliverOnce` returns `halted` for both: nothing is closed, the claim is released with its attempt given back.
+  `sendCampaign` (and `softure-mail campaign`) stops at the first one and reports `halted`; the rest of the list is
+  left for the next run.
+- `legacyUnsubscribe: { params, verify }`: unsubscribe links an app sent before adopting the module keep working on
+  the page, its action and the one-click route. New `readUnsubscribeLink`; `unsubscribe` takes its result (a bare
+  token still works).
+- `filterCampaignRecipient`: campaigns skip recipients the app does not want to mail (e.g. by consent scope), without
+  a ledger row; summaries and plans count them as `filtered`.
+- `staleClaimMs` and `uncertainClaimMs` module options. **Changed default:** a claim older than 23 hours is no longer
+  taken over by itself (`uncertain`), since the provider may have forgotten its idempotency key; pass
+  `retakeUncertain` (`--resend-uncertain`) to send it anyway.
+
 ## 0.1.6
 
 - Adapters and commands use the configured database handle; `@softure-ai/ui` is a peer dependency.

package/README.md

@@ -10,16 +10,19 @@ FIRE ran deployment-specific scripts.
 
 ## 1. What it provides
 
-- `mailing({ from, replyTo, provider, timeoutMs })` for `softure.config.ts`.
+- `mailing({ from, replyTo, provider, timeoutMs, ... })` for `softure.config.ts` (section 3).
 - `sendMail(context, mail, options)` in `@softure-ai/mailing/server` and `sendMail(mail, options)` in
-  `@softure-ai/mailing/next` (on the registered config). The result is a core `Result`:
+  `@softure-ai/mailing/next` (on the registered config). The result is a core `Result`; a failure the
+  provider answered with an HTTP status also carries it as `httpStatus`:
 
   | Result | Meaning | What the caller does |
   | --- | --- | --- |
   | `ok({ id, provider })` | the provider accepted the mail | keep `id` if it needs one |
   | `err("mailing.invalid_input")` | refused before anything left the process | fix the input; never retry |
-  | `err("mailing.rejected")` | the provider refused it (4xx: bad address, bad key, key reused with another body) | do not retry the same request |
-  | `err("mailing.unavailable")` | provider down (5xx), 408, 429, a busy idempotency key, network, timeout, an answer without an id, no API key; for list mail also no unsubscribe secret or an unreadable suppression list | retry later with the same `idempotencyKey` |
+  | `err("mailing.rejected")` | the provider refused this mail (4xx: bad address, key reused with another body) | do not retry the same request |
+  | `err("mailing.provider_refused")` | the provider refused the account (401/403: missing, wrong or restricted API key, account not allowed to send) | stop sending: every mail fails the same way; fix the key or account, then retry |
+  | `err("mailing.quota_exceeded")` | the account's sending quota is spent (429 that is not a rate limit: Resend's daily or monthly quota) | stop sending; retry when the quota renews |
+  | `err("mailing.unavailable")` | provider down (5xx), 408, a rate limit (429 `rate_limit_exceeded`), a busy idempotency key, network, timeout, an answer without an id, no API key; for list mail also no unsubscribe secret or an unreadable suppression list | retry later with the same `idempotencyKey` |
   | `err("mailing.suppressed")` | a list mail to a recipient who unsubscribed; nothing was sent | skip the recipient; never retry |
 
 - **List mail.** `kind: "transactional"` (the default) is mail the recipient needs whatever they
@@ -31,16 +34,19 @@ FIRE ran deployment-specific scripts.
 - The unsubscribe page (`/unsubscribe`) and the one-click route (`/api/mailing/unsubscribe`) in `/next`,
   each mounted with one line (section 4).
 - `@softure-ai/mailing/server`: `isSuppressed(ctx, address)`, `suppressRecipient(ctx, address)` (for
-  scripts, bounce or complaint handlers), `unsubscribe(ctx, token, source)`,
+  scripts, bounce or complaint handlers), `unsubscribe(ctx, link, source)` (a link from
+  `readUnsubscribeLink(params, config)`, or a bare token),
   `liftSuppression(ctx, address)` (a new explicit consent lifts the person's own opt-out),
   `buildUnsubscribeLinks`, `getRecipientKey`, and the footer and header helpers.
 - **An `onUnsubscribed` hook**, run in the opt-out's transaction, so the consent ledger can record
-  the withdrawal (section 10).
+  the withdrawal, and **`legacyUnsubscribe`**, which keeps unsubscribe links the app sent before it
+  adopted the module working (section 10).
 - **Sending once.** `deliverOnce(ctx, { scope, mail })` (`/server`, and `deliverOnce({ scope, mail })`
   in `/next`) sends a mail at most once per scope and recipient through the delivery ledger.
 - **Campaigns.** `sendCampaign`, `planCampaign` and the content file parser in `/server`; the
   `softure-mail campaign` command sends a campaign from a content file.
-- **Sender DNS.** `checkSenderDns(domain)` and `softure-mail dns` report SPF, DKIM and DMARC.
+- **Sender DNS.** `checkSenderDns(domain)` and `softure-mail dns` report SPF, DKIM and DMARC, hold DMARC to a
+  required minimum, and check the reply-to domain's MX and the provider's return-path hosts.
 - The `MailProvider` contract and `resend()`, the first adapter.
 - `@softure-ai/mailing/testing`: `fakeMailProvider()` and `readMailOutbox(file)`.
 
@@ -106,20 +112,29 @@ const outcome = await deliverOnce({
 | Outcome | Meaning |
 | --- | --- |
 | `{ status: "sent", id }` | sent now |
-| `{ status: "rejected", reason }` | refused now, for good: `mailing.suppressed`, `rejected`, `invalid_input`, or `unavailable` on the last attempt |
+| `{ status: "rejected", reason, httpStatus? }` | refused now, for good: `mailing.suppressed`, `rejected`, `invalid_input`, or `unavailable` on the last attempt |
 | `{ status: "done", outcome }` | an earlier call closed it (`sent` or `rejected`); nothing sent |
 | `{ status: "in-flight" }` | another sender holds a fresh claim; nothing sent |
-| `{ status: "retry-later" }` | the provider was unavailable; the claim is released, call again later |
+| `{ status: "uncertain" }` | a claim older than `uncertainClaimMs` is open: its send may have gone out; nothing sent (see Retries) |
+| `{ status: "retry-later", httpStatus? }` | the provider was unavailable; the claim is released, call again later |
+| `{ status: "halted", reason, httpStatus? }` | `mailing.provider_refused` or `mailing.quota_exceeded`: the account cannot send. The claim is released with its attempt given back; stop sending and call again once the account can send |
 
 - **Scopes** name what the mail is about and are the only registration a lifecycle mail needs:
   `<module>.<event>:<entity>` (`billing.trial-ending:sub_42`, `waitlist.welcome:<signup id>`).
   Lowercase letters, digits and `._:-`, at most 128 characters. Campaigns use `campaign:<id>`.
 - **Idempotency key.** The ledger sends with `<scope>:<recipient key>`; callers do not pass one.
 - **Retries.** `unavailable` releases the claim (`pending`); the fifth attempt (`maxAttempts`) that
-  is still unavailable closes the row as `rejected`. A process that dies between the send and the
-  outcome leaves a claim; after 15 minutes (`staleClaimMs`) another call takes it over and sends
-  again with the same idempotency key, which the provider folds into the first send while it keeps
-  the key (Resend: 24 hours). Outcomes are fenced by the attempt number, so a sender that lost its
+  is still unavailable closes the row as `rejected`. A halt (`provider_refused`, `quota_exceeded`)
+  never closes a row and never uses up an attempt, so a run with a bad key loses no recipient. The
+  provider's HTTP status of the last failed answer is kept in `provider_status`.
+- **Interrupted sends.** A process that dies between the send and the outcome leaves a claim; after
+  `staleClaimMs` (15 minutes) another call takes it over and sends again with the same idempotency
+  key, which the provider folds into the first send while it keeps the key (Resend: 24 hours). A
+  claim older than `uncertainClaimMs` (23 hours) is `uncertain`: the provider may have forgotten the
+  key, so a retake could mail twice, and it waits for an operator. Check the provider's log, then
+  pass `retakeUncertain: true` (`softure-mail campaign --resend-uncertain`) to send it anyway. Both
+  windows are module options, and `deliverOnce(ctx, delivery, { staleClaimMs, uncertainClaimMs })`
+  overrides them per call. Outcomes are fenced by the attempt number, so a sender that lost its
   claim cannot overwrite the one that took over.
 - A malformed scope or kind throws (a bug); a database failure propagates.
 
@@ -151,8 +166,25 @@ softure-mail campaign launch.md --recipients recipients.txt              # sends
   mail). Run `softure migrate` first.
 - Sends go one at a time with a 500 ms pause (`--pause-ms`; Resend allows 2 requests per second by
   default). Unsubscribed recipients are rejected without a send and never retried.
+- **Recipient filter.** With `mailing({ filterCampaignRecipient })` every recipient is checked before
+  the ledger is touched, e.g. against the consent scope the app stored for the address. A refused
+  recipient is counted as `filtered out` and gets no row, so a later run sends to them once they
+  qualify:
+
+  ```ts
+  mailing({
+    from: "…",
+    provider: resend(),
+    filterCampaignRecipient: async ({ address }, ctx) => hasNewsletterConsent(ctx.db, address),
+  }),
+  ```
+
+- **A refused key or a spent quota stops the run** at the first such answer: the command prints why
+  (with the HTTP status) and exits 1; that recipient and every one after it are left for the next
+  run. `sendCampaign` returns the same as `halted: { reason, httpStatus }`.
 - **Re-runs are safe.** Recipients with an outcome are skipped; the command exits 1 while some have
-  none yet (`retry later`, `in flight`): run the same command again. `mailing.campaigns` pins the
+  none yet (`retry later`, `in flight`): run the same command again. It also exits 1 for `uncertain`
+  recipients (an interrupted send older than `uncertainClaimMs`) and names `--resend-uncertain`. `mailing.campaigns` pins the
   content by hash: other content under the same id is refused, so a changed campaign needs a new id.
 - From a script (a bundled container, a list built from the database), call
   `runMailCli({ config, argv })` from `@softure-ai/mailing/cli`, or `sendCampaign(ctx, { campaign,
@@ -161,15 +193,32 @@ softure-mail campaign launch.md --recipients recipients.txt              # sends
 ### Sender DNS check: `softure-mail dns`
 
 ```bash
-softure-mail dns                                       # the domain of `from` in the config
+softure-mail dns                                       # the domain of `from` (and replyTo) in the config
 softure-mail dns --domain mail.example.com --spf-host send.mail.example.com
+softure-mail dns --spf-host send.mail.example.com --resend-return-path \
+  --dmarc-policy reject --dmarc-sp reject --dmarc-adkim s --dmarc-aspf s
 ```
 
-It reads TXT records and reports each check as `pass`, `warn` or `fail`, exiting 1 on any `fail`:
-SPF (one `v=spf1` record on the domain or each `--spf-host`; `+all` warns), DKIM (a non-empty `p=`
-at `<selector>._domainkey.<domain>`; selector `resend` unless `--dkim-selector` is given) and DMARC
-(`_dmarc.<domain>` or a parent domain's record; `p=none` warns: it only reports). Resend publishes
-SPF on `send.<domain>`. It cannot see whether the provider signs with the published key.
+It reports each check as `pass`, `warn` or `fail`, exiting 1 on any `fail`:
+
+- **SPF**: one `v=spf1` record on the domain or each `--spf-host`; `+all` warns. Resend publishes SPF on
+  `send.<domain>`.
+- **DKIM**: a non-empty `p=` at `<selector>._domainkey.<domain>`; selector `resend` unless `--dkim-selector` is given.
+- **DMARC**: `_dmarc.<domain>` or a parent domain's record; `p=none` warns: it only reports. With a required minimum
+  (`expectDmarc: { policy, subdomainPolicy, adkim, aspf }`, or the `--dmarc-*` flags) a weaker record fails as
+  `weak`: `p=quarantine` where `reject` is required, `adkim=r` (or no `adkim`) where `s` is required, `pct` under 100
+  when a policy is required. A stricter record passes, so adding `rua=` or tightening a tag never turns it red. For
+  an inherited record the domain's policy is `sp`, else `p`.
+- **REPLY** (when `replyTo` is configured and `--domain` is not given, or with `--reply-to`; `replyTo` option of the
+  function): the reply domain must have MX records that are not a null MX (`0 .`, "accepts no mail") and at most one
+  SPF record. Without it replies bounce while every sender check is green.
+- **PATH** (`returnPath: [{ host, targetDomain? }]`, `--return-path <host>`, `--resend-return-path`): each host must
+  be a CNAME (to `targetDomain` or under it, when set) or have MX records. `resendReturnPath(domain)` (the flag) gives
+  Resend's `send.<domain>` and `rsend.<domain>` with target `rmta.net`; a domain Resend set up with MX records on
+  `send` and no `rsend` checks `--return-path send.<domain>` alone.
+
+It cannot see whether the provider signs with the published key. The function takes `resolveTxt`, `resolveMx` and
+`resolveCname` for tests; by default it asks the system resolver.
 
 ## 2. Installation
 
@@ -200,6 +249,10 @@ mailing({
 | `provider` | `MailProvider` | required | `resend()`, `fakeMailProvider()` or your own adapter. |
 | `timeoutMs` | `number` | `10000` | 1000 to 60000. |
 | `onUnsubscribed` | `(event, ctx) => Promise<void>` | — | Runs on every verified unsubscribe, in its transaction (section 10). |
+| `legacyUnsubscribe` | `{ params, verify }` | — | Verifies unsubscribe links the app sent before it adopted the module (section 10). |
+| `filterCampaignRecipient` | `(recipient, ctx) => Promise<boolean>` | — | Decides per recipient whether a campaign goes to them (section 1, Campaigns). |
+| `staleClaimMs` | `number` | `900000` (15 min) | How long a delivery claim may stay open before another sender takes it over. 1 minute to 23 hours. |
+| `uncertainClaimMs` | `number` | `82800000` (23 h) | How old a claim may get before it waits for an operator (`uncertain`). More than `staleClaimMs`, at most 30 days; keep it under the provider's idempotency window. |
 | `routes` | `{ unsubscribe?, oneClick? }` | `/unsubscribe`, `/api/mailing/unsubscribe` | Where you mount the page and the route; links are built on `appOrigin` plus these paths. |
 
 `resend({ apiKey?, endpoint?, fetch? })`: without `apiKey` it reads `RESEND_API_KEY` on every send,
@@ -213,13 +266,18 @@ const provider: MailProvider = {
   async send(message, { signal }) {
     const response = await fetch(URL, { method: "POST", body: toBody(message), signal });
     if (response.ok) return { status: "sent", id: (await response.json()).MessageID };
-    return { status: response.status >= 500 || response.status === 429 ? "unavailable" : "rejected", httpStatus: response.status };
+    const httpStatus = response.status;
+    if (httpStatus === 401 || httpStatus === 403) return { status: "refused", httpStatus };
+    if (httpStatus === 429) return { status: "unavailable", httpStatus }; // or "quota_exceeded" for a spent quota
+    return { status: httpStatus >= 500 ? "unavailable" : "rejected", httpStatus };
   },
 };
 ```
 
 A provider receives a validated `ProviderMessage` (`from`, `to`, `replyTo`, `subject`, `text`, `html`,
-`headers`, `idempotencyKey`, nulls for what is absent). A throw reads as `unavailable`.
+`headers`, `idempotencyKey`, nulls for what is absent) and answers `sent` with an id, or `rejected`
+(this mail), `refused` (the account or key), `quota_exceeded` (the account's quota) or `unavailable`
+(try later), each with an optional `httpStatus`. A throw or anything else reads as `unavailable`.
 
 ## 4. Mounting
 
@@ -253,6 +311,7 @@ Schema `mailing`, applied by `softure migrate`:
 | `0001_create_suppressions.sql` | `mailing.suppressions` | `recipient_key` (primary key, 43-character base64url), `source` (`one-click`, `page`, `operator`), `created_at`. One row per address, the first opt-out kept. |
 | `0002_create_campaigns_and_deliveries.sql` | `mailing.campaigns` | `id` (kebab-case), `kind` (never `transactional`), `subject`, `content_hash` (sha256 of kind, subject and bodies), `created_at`. |
 | | `mailing.deliveries` | primary key (`scope`, `recipient_key`), `kind`, `campaign_id` (then `scope` is `campaign:<id>`), `status` (`pending`, `claimed`, `sent`, `rejected`), `attempts`, `claimed_at`, `finished_at`, `provider_message_id` (exactly when sent), `reason` (exactly when rejected). |
+| `0003_add_delivery_provider_status.sql` | `mailing.deliveries` | `provider_status` (the HTTP status of the last failed or released answer, 100 to 599, else null); `attempts` may be 0 on a `pending` row (a halt gave its attempt back). |
 
 The health check (`checkMailingTables`) runs `select 1 from mailing.<table> limit 0` for the three
 tables.
@@ -281,7 +340,7 @@ styled by the app's tokens.
 
 ## 9. Copy
 
-`src/messages/{en,pl}.ts`: `errors.mailing.{invalid_input,rejected,unavailable,suppressed}`,
+`src/messages/{en,pl}.ts`: `errors.mailing.{invalid_input,rejected,unavailable,suppressed,provider_refused,quota_exceeded}`,
 `footer.{text,htmlLead,htmlLink}` (the list-mail footer, in the app's locale) and
 `unsubscribe.*` (the page). `getMailingErrorMessage(messages, code)` returns the copy for a code;
 override any text with `mailing({ messages: { en: { footer: { text: "…" } } } })`.
@@ -304,6 +363,29 @@ import { withdrawWaitlistConsents } from "@softure-ai/waitlist/server";
 mailing({ from: "…", provider: resend(), onUnsubscribed: withdrawWaitlistConsents }),
 ```
 
+**`legacyUnsubscribe: { params, verify }`** keeps unsubscribe links working that the app sent
+before it adopted the module, in its own scheme (an HMAC over a sign-up id, say, on its own path).
+`params` are the old link's query names (1 to 8; never `r` or `status`, which the module's links and
+page own; `t` may be shared). A link without `r` that carries every one of them (non-empty, at most
+512 characters) is a legacy link: the page shows the same button with the values in hidden fields,
+and the action and the one-click POST call `verify(values, ctx)`. It returns the recipient's
+**address** when the link is genuine, else `null`; the module records the opt-out under that
+address's key and runs `onUnsubscribed`, exactly as for its own links. `verify` must check the
+link's signature itself (in constant time): whatever address it returns is unsubscribed. A throw is
+a failure (the page offers a retry, the route answers 500), not an invalid link. Mount the module's
+page and route at the old paths too:
+
+```ts
+mailing({
+  from: "…",
+  provider: resend(),
+  legacyUnsubscribe: { params: ["u", "t"], verify: ({ u, t }, ctx) => verifyOldLink(ctx.db, u, t) },
+}),
+
+// app/old-unsubscribe/page.tsx
+export { UnsubscribePage as default } from "@softure-ai/mailing/next";
+```
+
 **`liftSuppression(ctx, address)`** is the other direction: a module that has just recorded a new
 explicit consent (the waitlist's sign-up) calls it in that consent's transaction. It deletes the
 row only when its source is `page` or `one-click`; an `operator` row stays. It returns whether it
@@ -330,8 +412,9 @@ personal data. So the module neither exports nor deletes per user (`privacy: { e
 - `sendMail` does not retry: the caller retries `unavailable` with the same `idempotencyKey` (Resend
   keeps keys for 24 hours), or uses `deliverOnce`, which keeps the state between runs.
 - Exactly-once ends where the provider's idempotency window ends: a sender that dies after the
-  provider accepted a mail and before the outcome was written, with the row taken over more than
-  24 hours later, sends that mail twice. No delivery, bounce or complaint webhooks yet.
+  provider accepted a mail and before the outcome was written leaves an `uncertain` claim once
+  `uncertainClaimMs` passes; retaking it (`retakeUncertain`) may send that mail twice. No delivery,
+  bounce or complaint webhooks yet.
 - Campaigns have no personalisation, scheduling or markdown: the body is sent as written.
 - Suppression is global per address: no per-list preferences. A person comes back in through a
   module's explicit consent (`liftSuppression`, e.g. a new waitlist sign-up); an operator row is

package/dist/cli/run.d.ts

@@ -1,6 +1,6 @@
 import { type SoftureConfig } from "@softure-ai/core";
 import { type DatabaseHandle } from "@softure-ai/db";
-import { type ResolveTxt } from "../server/dns.js";
+import { type ResolveCname, type ResolveMx, type ResolveTxt } from "../server/dns.js";
 import { type Env } from "../server/unsubscribe-link.js";
 export interface CliOutput {
     readonly log: (line: string) => void;
@@ -17,6 +17,8 @@ export interface RunMailCliOptions {
     /** Opens the campaign's database connection. Default: the config's `database.handle`, else `createDatabase(url, { max: 1 })`. */
     readonly openDatabase?: (url: string) => Promise<DatabaseHandle>;
     readonly resolveTxt?: ResolveTxt;
+    readonly resolveMx?: ResolveMx;
+    readonly resolveCname?: ResolveCname;
     readonly sleep?: (ms: number) => Promise<void>;
     readonly env?: Env;
 }

package/dist/cli/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAWA,OAAO,EAAe,KAAK,aAAa,EAA8B,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIhG,OAAO,EAAkD,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnG,OAAO,EAAiF,KAAK,GAAG,EAAE,MAAM,+BAA+B,CAAC;AAExI,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,wGAAwG;IACxG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,iIAAiI;IACjI,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,UAAU,QAkBa,CAAC;AAYrC,yGAAyG;AACzG,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB5E"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAWA,OAAO,EAAe,KAAK,aAAa,EAA8B,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIhG,OAAO,EAAkI,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AAE3O,OAAO,EAAiF,KAAK,GAAG,EAAE,MAAM,+BAA+B,CAAC;AAExI,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,wGAAwG;IACxG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,iIAAiI;IACjI,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,UAAU,QAgCa,CAAC;AAgCrC,yGAAyG;AACzG,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB5E"}

package/dist/cli/run.js

@@ -13,7 +13,7 @@ import { systemClock } from "@softure-ai/core";
 import { openCommandDatabase } from "@softure-ai/db";
 import { parseCampaignFile, parseRecipientList } from "../server/campaign-file.js";
 import { planCampaign, sendCampaign } from "../server/campaigns.js";
-import { checkSenderDns, getSenderDomain } from "../server/dns.js";
+import { checkSenderDns, getSenderDomain, resendReturnPath } from "../server/dns.js";
 import { getMailingOptions } from "../server/options.js";
 import { MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV } from "../server/unsubscribe-link.js";
 export const EXIT_OK = 0;
@@ -22,20 +22,34 @@ export const EXIT_USAGE = 2;
 /** Pause between sends: Resend's default limit is two requests per second. */
 export const DEFAULT_PAUSE_MS = 500;
 export const MAIL_USAGE = `Usage:
-  softure-mail campaign <content-file> --recipients <file> [--dry-run] [--pause-ms <ms>]
+  softure-mail campaign <content-file> --recipients <file> [--dry-run] [--pause-ms <ms>] [--resend-uncertain]
   softure-mail dns [--domain <domain>] [--dkim-selector <name>]... [--spf-host <host>]...
+                   [--dmarc-policy <p>] [--dmarc-sp <p>] [--dmarc-adkim <a>] [--dmarc-aspf <a>]
+                   [--reply-to <address>] [--return-path <host>]... [--resend-return-path]
 
 campaign  Sends the campaign in <content-file> (frontmatter id, kind, subject, optional html,
           then the text body) to every address in the recipients file (one per line), at most
-          once each. Re-running sends only to recipients without an outcome yet.
-  --dry-run          count what would be sent and change nothing
-  --pause-ms <ms>    pause after every send (default ${String(DEFAULT_PAUSE_MS)})
+          once each. Re-running sends only to recipients without an outcome yet. A refused
+          API key or a spent quota stops the run; the rest go out on the next one.
+  --dry-run            count what would be sent and change nothing
+  --pause-ms <ms>      pause after every send (default ${String(DEFAULT_PAUSE_MS)})
+  --resend-uncertain   also send to recipients whose send was interrupted long ago
+                       (it may have gone out: they may get the mail twice)
 
 dns       Checks SPF, DKIM and DMARC for the sender domain (default: the domain of "from").
   --domain <domain>       check this domain instead
   --dkim-selector <name>  DKIM selector to look up (default resend; repeatable)
   --spf-host <host>       where SPF is published (default the domain; repeatable;
                           Resend publishes it on send.<domain>)
+  --dmarc-policy <p>      require at least this DMARC policy (quarantine or reject)
+                          and pct=100; a weaker record fails
+  --dmarc-sp <p>          require at least this subdomain policy (sp, else p)
+  --dmarc-adkim <a>       require this DKIM alignment (r or s; absent counts as r)
+  --dmarc-aspf <a>        require this SPF alignment (r or s; absent counts as r)
+  --reply-to <address>    check that this address's domain accepts mail (MX, one SPF)
+                          (default: replyTo of the config, when --domain is not given)
+  --return-path <host>    a return-path host that must be a CNAME or have MX (repeatable)
+  --resend-return-path    check Resend's send.<domain> and rsend.<domain> CNAMEs
 
 Options for both:
   --config <file>    the app's softure.config file (bin only)
@@ -44,6 +58,9 @@ const consoleOutput = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
 };
+const DMARC_POLICIES = ["quarantine", "reject"];
+const DMARC_ALIGNMENTS = ["r", "s"];
+const DNS_ONLY_OPTIONS = ["domain", "dkim-selector", "spf-host", "dmarc-policy", "dmarc-sp", "dmarc-adkim", "dmarc-aspf", "reply-to", "return-path", "resend-return-path"];
 /** Runs the command and returns the process exit code: 0 done, 1 failed or incomplete, 2 usage error. */
 export async function runMailCli(options) {
     const output = options.output ?? consoleOutput;
@@ -82,14 +99,26 @@ function parseCommand(argv) {
     if (values.help === true)
         return { kind: "help" };
     if (name === "dns") {
-        const misplaced = ["recipients", "dry-run", "pause-ms"].filter((option) => values[option] !== undefined);
+        const misplaced = ["recipients", "dry-run", "pause-ms", "resend-uncertain"].filter((option) => values[option] !== undefined);
         if (misplaced.length > 0)
             return `dns does not take --${misplaced.join(", --")}`;
         if (positionals.length > 0)
             return `dns takes no file, got "${positionals.join(" ")}"`;
-        return { kind: "dns", domain: values.domain, dkimSelectors: values["dkim-selector"], spfHosts: values["spf-host"] };
+        const expectDmarc = parseDmarcExpectation(values);
+        if (typeof expectDmarc === "string")
+            return expectDmarc;
+        return {
+            kind: "dns",
+            domain: values.domain,
+            dkimSelectors: values["dkim-selector"],
+            spfHosts: values["spf-host"],
+            expectDmarc,
+            replyTo: values["reply-to"],
+            returnPathHosts: values["return-path"] ?? [],
+            resendReturnPath: values["resend-return-path"] === true,
+        };
     }
-    const misplaced = ["domain", "dkim-selector", "spf-host"].filter((option) => values[option] !== undefined);
+    const misplaced = DNS_ONLY_OPTIONS.filter((option) => values[option] !== undefined);
     if (misplaced.length > 0)
         return `campaign does not take --${misplaced.join(", --")}`;
     const [contentFile, ...extra] = positionals;
@@ -102,7 +131,7 @@ function parseCommand(argv) {
     const pauseMs = values["pause-ms"] === undefined ? DEFAULT_PAUSE_MS : Number(values["pause-ms"]);
     if (!Number.isInteger(pauseMs) || pauseMs < 0 || pauseMs > 60_000)
         return `--pause-ms expects whole milliseconds from 0 to 60000, got "${values["pause-ms"] ?? ""}"`;
-    return { kind: "campaign", contentFile, recipientsFile: values.recipients, dryRun: values["dry-run"] === true, pauseMs };
+    return { kind: "campaign", contentFile, recipientsFile: values.recipients, dryRun: values["dry-run"] === true, pauseMs, resendUncertain: values["resend-uncertain"] === true };
 }
 function parseCommandArgs(args) {
     return parseArgs({
@@ -111,45 +140,105 @@ function parseCommandArgs(args) {
             recipients: { type: "string" },
             "dry-run": { type: "boolean" },
             "pause-ms": { type: "string" },
+            "resend-uncertain": { type: "boolean" },
             domain: { type: "string" },
             "dkim-selector": { type: "string", multiple: true },
             "spf-host": { type: "string", multiple: true },
+            "dmarc-policy": { type: "string" },
+            "dmarc-sp": { type: "string" },
+            "dmarc-adkim": { type: "string" },
+            "dmarc-aspf": { type: "string" },
+            "reply-to": { type: "string" },
+            "return-path": { type: "string", multiple: true },
+            "resend-return-path": { type: "boolean" },
             help: { type: "boolean" },
         },
         strict: true,
         allowPositionals: true,
     });
 }
+/** One choice of a fixed list, case-insensitive; `undefined` when the option was not given. */
+function pickChoice(values, option, allowed) {
+    const given = values[option];
+    if (given === undefined)
+        return { value: undefined };
+    const found = allowed.find((candidate) => candidate === given.trim().toLowerCase());
+    return found === undefined ? `--${option} expects ${allowed.join(" or ")}, got "${given}"` : { value: found };
+}
+function parseDmarcExpectation(values) {
+    const policy = pickChoice(values, "dmarc-policy", DMARC_POLICIES);
+    if (typeof policy === "string")
+        return policy;
+    const subdomainPolicy = pickChoice(values, "dmarc-sp", DMARC_POLICIES);
+    if (typeof subdomainPolicy === "string")
+        return subdomainPolicy;
+    const adkim = pickChoice(values, "dmarc-adkim", DMARC_ALIGNMENTS);
+    if (typeof adkim === "string")
+        return adkim;
+    const aspf = pickChoice(values, "dmarc-aspf", DMARC_ALIGNMENTS);
+    if (typeof aspf === "string")
+        return aspf;
+    const expectation = {
+        ...(policy.value === undefined ? {} : { policy: policy.value }),
+        ...(subdomainPolicy.value === undefined ? {} : { subdomainPolicy: subdomainPolicy.value }),
+        ...(adkim.value === undefined ? {} : { adkim: adkim.value }),
+        ...(aspf.value === undefined ? {} : { aspf: aspf.value }),
+    };
+    return Object.keys(expectation).length === 0 ? undefined : expectation;
+}
 async function runDns(command, options, output) {
     let domain = command.domain;
+    let replyTo = command.replyTo;
     if (domain === undefined) {
         if (options.config === undefined) {
             output.error("softure-mail dns: pass --domain <domain>, or run it with the app's config to check the sender's domain");
             return EXIT_FAILED;
         }
-        domain = getSenderDomain(getMailingOptions(options.config).from);
+        const mailing = getMailingOptions(options.config);
+        domain = getSenderDomain(mailing.from);
+        replyTo ??= mailing.replyTo;
     }
+    const returnPath = [...(command.resendReturnPath ? resendReturnPath(domain) : []), ...command.returnPathHosts.map((host) => ({ host }))];
     const report = await checkSenderDns(domain, {
         ...(command.dkimSelectors === undefined ? {} : { dkimSelectors: command.dkimSelectors }),
         ...(command.spfHosts === undefined ? {} : { spfHosts: command.spfHosts }),
+        ...(command.expectDmarc === undefined ? {} : { expectDmarc: command.expectDmarc }),
+        ...(replyTo === undefined ? {} : { replyTo }),
+        returnPath,
         ...(options.resolveTxt === undefined ? {} : { resolveTxt: options.resolveTxt }),
+        ...(options.resolveMx === undefined ? {} : { resolveMx: options.resolveMx }),
+        ...(options.resolveCname === undefined ? {} : { resolveCname: options.resolveCname }),
     });
-    const checks = [
+    const authentication = [
         ["SPF", report.spf],
         ["DKIM", report.dkim],
         ["DMARC", report.dmarc],
     ];
+    const reply = report.replyTo === null ? [] : [["REPLY", report.replyTo]];
+    const paths = report.returnPath.map((check) => ["PATH", check]);
     output.log(`sender domain ${report.domain}`);
-    for (const [name, check] of checks) {
-        const line = `${name.padEnd(6)}${check.status.padEnd(6)}${check.finding.padEnd(15)}${check.host}${check.record === null ? "" : `  ${check.record}`}`;
+    for (const [name, check] of [...authentication, ...reply, ...paths]) {
+        const line = `${name.padEnd(6)}${check.status.padEnd(6)}${`${check.finding} `.padEnd(15)}${check.host}${check.record === null ? "" : `  ${check.record}`}`;
         if (check.status === "fail")
             output.error(line);
         else
             output.log(line);
     }
-    const failed = checks.filter(([, check]) => check.status === "fail").length;
-    output.log(failed === 0 ? "receivers can authenticate mail from this domain" : `${String(failed)} check(s) failed: list mail from this domain will land in spam or be refused`);
-    return failed === 0 ? EXIT_OK : EXIT_FAILED;
+    const countFailed = (checks) => checks.filter(([, check]) => check.status === "fail").length;
+    const failedAuthentication = countFailed(authentication);
+    const failedReply = countFailed(reply);
+    const failedPaths = countFailed(paths);
+    if (failedAuthentication + failedReply + failedPaths === 0) {
+        output.log("receivers can authenticate mail from this domain");
+        return EXIT_OK;
+    }
+    if (failedAuthentication > 0)
+        output.log(`${String(failedAuthentication)} check(s) failed: list mail from this domain will land in spam or be refused`);
+    if (failedReply > 0)
+        output.log("the reply-to domain does not accept mail: replies will bounce");
+    if (failedPaths > 0)
+        output.log(`${String(failedPaths)} return-path host(s) failed: the provider cannot use them for bounces`);
+    return EXIT_FAILED;
 }
 async function runCampaign(command, options, output) {
     const cwd = options.cwd ?? process.cwd();
@@ -181,7 +270,9 @@ async function runCampaign(command, options, output) {
     }
     const ctx = { db: opened.handle.db, clock: systemClock, config };
     try {
-        return command.dryRun ? await reportPlan(ctx, loaded, output) : await reportSend(ctx, loaded, { pauseMs: command.pauseMs, sleep: options.sleep }, output);
+        return command.dryRun
+            ? await reportPlan(ctx, loaded, command.resendUncertain, output)
+            : await reportSend(ctx, loaded, { pauseMs: command.pauseMs, sleep: options.sleep, retakeUncertain: command.resendUncertain }, output);
     }
     catch (error) {
         // Driver errors: the message only, never a stack, an address or the database URL.
@@ -214,10 +305,17 @@ async function loadCampaign(contentPath, recipientsPath) {
         return `cannot read the recipients file ${recipientsPath}`;
     return { campaign: { ...content, html }, recipients: parseRecipientList(list) };
 }
-async function reportPlan(ctx, loaded, output) {
-    const plan = await planCampaign(ctx, loaded);
+async function reportPlan(ctx, loaded, retakeUncertain, output) {
+    const plan = await planCampaign(ctx, loaded, { retakeUncertain });
     output.log(`campaign ${loaded.campaign.id} (${loaded.campaign.kind}), dry run: nothing sent or written`);
-    output.log(`recipients ${String(plan.recipients)}, already done ${String(plan.done)}, unsubscribed ${String(plan.suppressed)}, to send ${String(plan.toSend)}`);
+    output.log([
+        `recipients ${String(plan.recipients)}`,
+        `already done ${String(plan.done)}`,
+        `unsubscribed ${String(plan.suppressed)}`,
+        `filtered out ${String(plan.filtered)}`,
+        `uncertain ${String(plan.uncertain)}`,
+        `to send ${String(plan.toSend)}`,
+    ].join(", "));
     if (plan.contentChanged) {
         output.error(`campaign ${loaded.campaign.id} was sent with other content; give this content a new id`);
         return EXIT_FAILED;
@@ -229,6 +327,7 @@ async function reportSend(ctx, loaded, pace, output) {
     const total = loaded.recipients.length;
     const result = await sendCampaign(ctx, loaded, {
         pauseMs: pace.pauseMs,
+        retakeUncertain: pace.retakeUncertain,
         ...(pace.sleep === undefined ? {} : { sleep: pace.sleep }),
         onDelivery: () => {
             handled += 1;
@@ -240,14 +339,29 @@ async function reportSend(ctx, loaded, pace, output) {
         output.error(`campaign ${loaded.campaign.id} was sent with other content; give this content a new id`);
         return EXIT_FAILED;
     }
-    output.log(`campaign ${loaded.campaign.id} (${loaded.campaign.kind}): ${formatSummary(result.value)}`);
-    const open = result.value.inFlight + result.value.retryLater;
-    if (open > 0) {
+    const summary = result.value;
+    output.log(`campaign ${loaded.campaign.id} (${loaded.campaign.kind}): ${formatSummary(summary)}`);
+    let code = EXIT_OK;
+    if (summary.halted !== null) {
+        const status = summary.halted.httpStatus === undefined ? "" : ` (HTTP ${String(summary.halted.httpStatus)})`;
+        output.error(`stopped: ${HALT_EXPLANATIONS[summary.halted.reason]}${status}; the remaining recipients were not touched, run the same command again once it is fixed`);
+        code = EXIT_FAILED;
+    }
+    const open = summary.inFlight + summary.retryLater;
+    if (open > 0 && summary.halted === null) {
         output.error(`${String(open)} recipient(s) have no outcome yet; run the same command again later`);
-        return EXIT_FAILED;
+        code = EXIT_FAILED;
     }
-    return EXIT_OK;
+    if (summary.uncertain > 0) {
+        output.error(`${String(summary.uncertain)} recipient(s) are uncertain: a send was interrupted long ago and may have gone out; check the provider's log, then run again with --resend-uncertain to send them anyway`);
+        code = EXIT_FAILED;
+    }
+    return code;
 }
+const HALT_EXPLANATIONS = {
+    "mailing.provider_refused": "the provider refused the account (check the API key and the account)",
+    "mailing.quota_exceeded": "the account's sending quota is spent",
+};
 function formatSummary(summary) {
     const rejected = Object.entries(summary.rejected).filter(([, count]) => count > 0);
     const rejectedTotal = rejected.reduce((sum, [, count]) => sum + count, 0);
@@ -259,6 +373,8 @@ function formatSummary(summary) {
         `already done ${String(summary.done)}`,
         `in flight ${String(summary.inFlight)}`,
         `retry later ${String(summary.retryLater)}`,
+        `filtered out ${String(summary.filtered)}`,
+        `uncertain ${String(summary.uncertain)}`,
     ].join(", ");
 }
 async function openDatabase(database, open) {