Patri documentation

Address-keyed dedupe, merge-on-import, and a written consent basis stored verbatim on every row an import creates. An import that meets an address already suppressed never overwrites the suppression.

Will not: Record a subscriber as consented just because it was created — creating an address and recording that its owner agreed are two different writes. Let email or status be edited by PATCH — email is immutable (it is what suppression is keyed on) and status is derived from consent, never typed directly. Let an import quietly revive an opted-out address — a live opt-out is kept, and the import is logged as not having changed it.

Checked by the single writer of recipient rows, and again at the moment of dispatch. Release needs a re-opt-in reference and a fresh consent record; a complaint can never be released.

Will not: Expose a DELETE on a suppression entry — there is none. Release a spam-complaint suppression, ever, under any argument — this check fires before any consent lookup even happens. Release without a consent record dated at or after the suppression itself — the only evidence otherwise would be that somebody clicked release.

A GET only reads whether the address is already unsubscribed — it never unsubscribes anyone, because mailbox scanners issue GETs against every link. The POST does the work, writes a suppression entry, and always returns success even on a repeat click.

Needs: an email provider, so the headers reach a real inbox

Will not: Unsubscribe on a GET request — only a POST changes anything. Error on a second click of the same link — that would read as 'did not work' to someone whose next move is the spam button.

Consent is a separate endpoint from subscriber creation, with an append-only event log. Double opt-in mints a token that is never returned to the workspace, precisely so the business cannot confirm its own subscribers on their behalf. The reminder job now runs too: it finds unconfirmed requests older than 24 hours with no reminder sent yet and attempts exactly one follow-up, and it only marks a reminder sent once an email provider actually exists and an attempt was made — a record from before a provider was connected stays eligible rather than being marked reminded for a message that never left the building.

Needs: an email provider, to deliver the confirmation email and its one-time reminder

Will not: Accept a method description under eight characters — it has to actually name the affirmative action, not restate 'opted in'. Lift a suppression just because fresh consent was recorded — the response says still_suppressed and points at the separate release step. Return the double-opt-in token to the authenticated caller — only its hash is stored.

Drafting, HTML sanitisation on write, a real audience count, the approval gate and a confirmed send all run and produce the final rendered message. Delivery needs an email provider.

Needs: an email provider, for actual delivery

Will not: Schedule a send for later — there is no scheduled-send route; a timer cannot supply the human confirmation the boundary requires. Send when the confirmed recipient count no longer matches the live audience — that is a 409 and nothing is written. Send past the daily cap — that is a 429, checked against the size of this send, not only whether the cap has already been hit. Store raw HTML unsanitised — every write runs through an allowlist parser, not a regex filter, dropping scripts, event handlers and unsafe styles entirely.

Approving or rejecting a campaign is restricted to an owner or admin, and editing the copy after approval clears the approval outright — the campaign is forced back to draft. Every submit-for-approval writes its own approval row rather than overwriting the last one, so approval-history shows the full multi-round record. A reminder nudge now runs too, posting an in-app notification to the named approver after the configured wait — deliberately with no email address attached, so it needs no ESP credential at all.

Will not: Let anyone but an owner or admin approve or reject a campaign — that is a 403 for every other role. Let an approved campaign's copy change without clearing the approval — editing subject or body after approval is forced back to draft, with the reason recorded on the campaign.

Merge fields with fallbacks, per-subscriber preview (by subscriber id or by a Wavy contact id), and a coverage check counting how many real recipients a field would render empty for. Conditional content blocks are built too: a block carries a condition in the same AND/OR grammar as list-segmentation, a {{block:name}} token in the body, and a required default so a block can never render as a hole the way an unresolved merge field can — and resolution happens inside the real send path, not only in preview, so a live send actually varies by subscriber. A merge-field catalogue documents which fields exist; the value itself still comes from the subscriber's own attributes.

Will not: Render a working unsubscribe link in a preview — the preview shows a placeholder rather than minting a live opt-out credential for a real subscriber. Invent a merge field's value — the catalogue documents what fields exist; it does not manufacture data a subscriber's row does not have.

generate-copy and rewrite-copy call the LLM with a prompt that forbids invented prices, guarantees or regulated claims, and funnel the result through the exact same write path a hand-typed campaign uses — every call logged for audit. The review gate is unconditional on top of that: AI-marked copy is always held regardless of what the regulated-claims guard finds, a named human has to clear it before the campaign can be approved, and any later edit re-arms the hold.

Needs: an LLM key, for generate-copy and rewrite-copy themselves

Will not: Approve AI-marked copy that nobody has reviewed — copy_held is always true on AI-generated copy until a human explicitly clears it. Invent a price, a guarantee, or a regulated claim — the generation prompt forbids all three, and Lekha's regulated-claim guard still runs over the result before it can be approved. Fall back to a stub draft without a key — generate-copy and rewrite-copy return a 503 naming the missing LLM key rather than fabricating copy locally.

A real AND/OR rule tree over tags, attributes, subscriber status and consent state — evaluated fresh every time, by both the segment's own preview-count and a campaign's own audience computation, so the two can never disagree with each other. Setting a segment on a campaign targets it directly. An empty condition list fails closed rather than matching everyone, and preview-count flags a segment that currently matches the whole workspace so nobody sends to 'everyone' by accident.

Will not: Cache a segment's membership — every count and every send-time audience computation runs the rule tree fresh, so a saved segment and a campaign built from it can never quietly drift apart. Match everyone on an empty rule — an empty condition list is refused rather than treated as 'no filter'. Offer engagement-history conditions (opened, clicked) — no open-tracking data exists on this deployment to build them from honestly.

Per-recipient counts — queued, blocked by suppression, blocked for want of consent, accepted by the provider — are real, drawn from the recipient rows this workspace actually wrote, and a workspace-wide summary and CSV export (built in memory, never written to disk) now aggregate them across every campaign, not only one at a time.

Needs: a sending provider's webhook feed, for opens, clicks, bounces and complaints

Will not: Report an open rate, click rate, bounce count or complaint count as a number, on a single campaign or in the workspace summary — nothing has connected the webhook feed those figures come from, so they come back as unknown rather than as zero. Attribute a sale or booking to a campaign — that needs a connected e-commerce or booking platform this deployment has no integration for, which is why this stays partial rather than requires_configuration.

A sending domain is a real record carrying its own SPF, DKIM and DMARC state. The exact records to publish are generated from the domain rather than looked up, so that half is correct with no resolver at all, and the campaign send route consults an authentication gate that refuses only on positive evidence a recorded domain's SPF or DMARC is missing. 'Unknown' never blocks a send: refusing because this deployment cannot resolve DNS would be an outage wearing a safety label. Metrics report real queued and blocked counts per stream, per day, computed from the recipient rows.

Needs: Two separate things, neither of them a key you can set. A DNS resolver: there is none in this process, so every published-record status stays unknown, and TXT_RESOLVER is the seam that starts answering the moment one exists. And the transactional provider's webhook feed, which is where bounce rate, complaint rate and delivered count would come from — they are reported as null rather than zero, because zero would read as 'nothing bounced'.

Will not: Report SPF, DKIM or DMARC as passing when nothing has actually been checked — with no resolver in this process, a published-record status stays unknown rather than becoming a guess. Treat an owner's attestation as evidence. It is stored separately from the three status columns on purpose, so a later real check can contradict it.

Order confirmations, receipts and password resets run on their own stream, its own rate policy, and the same suppression gate — a bounce, complaint or manual block stops it absolutely.

Needs: an email provider and a separate sending identity

Will not: Send a purpose outside the fixed eight-item list (order confirmation, shipping update, booking confirmation, appointment reminder, payment receipt, password reset, account notice, double opt-in confirmation) — an unlisted purpose is a 400 that names the allowed ones. Let a bounce, a complaint or a manual suppression through — only a marketing-only unsubscribe leaves a transactional send unaffected.

Workspace member. Address-keyed dedupe, merge-on-import, and a written consent basis stored verbatim on every row an import creates. An import that meets an address already suppressed never overwrites the suppression.

{ "email": "priya@example.in", "first_name": "Priya", "source": "manual" }

{ "id": "…", "email": "priya@example.in", "status": "pending", "mailable": false, "note": "Record consent next — POST /consent-records." }

Workspace member. consent_basis under 12 characters, or an attempt to import as consent_state=opted_out, is a 400.

{ "rows": [ { "email": "amit@example.in" } ],
  "consent_basis": "Collected via in-store signup sheet, Aug 2026", "consent_source": "import" }

{ "created": 1, "updated": 0, "rejected": [], "already_suppressed": 0, "kept_opted_out": [] }

Workspace member. A complaint-reason entry is a 409 naming exactly that. A missing recent opted_in consent record is a 409: "Record the new opt-in first. A release needs a consent record dated after the suppression it reverses…"

{ "re_opt_in_reference": "Re-confirmed by phone, 2026-08-16, ref call log #4021" }

{ "id": "…", "active": false, "released_at": "…", "release_reference": "Re-confirmed by phone, …" }

Unauthenticated. Always 200, on the first click and every one after it.

{ "email": "priya@example.in", "unsubscribed": true }

Workspace member. Consent is a separate endpoint from subscriber creation, with an append-only event log. Double opt-in mints a token that is never returned to the workspace, precisely so the business cannot confirm its own subscribers on their behalf. The reminder job now runs too: it finds unconfirmed requests older than 24 hours with no reminder sent yet and attempts exactly one follow-up, and it only marks a reminder sent once an email provider actually exists and an attempt was made — a record from before a provider was connected stays eligible rather than being marked reminded for a message that never left the building.

{ "subscriber_id": "…", "purpose": "marketing", "state": "opted_in",
  "source": "form", "method": "Checked the newsletter box at checkout on our site." }

{ "id": "…", "purpose": "marketing", "state": "opted_in", "consented_at": "…" }

Unauthenticated. Consent is a separate endpoint from subscriber creation, with an append-only event log. Double opt-in mints a token that is never returned to the workspace, precisely so the business cannot confirm its own subscribers on their behalf. The reminder job now runs too: it finds unconfirmed requests older than 24 hours with no reminder sent yet and attempts exactly one follow-up, and it only marks a reminder sent once an email provider actually exists and an attempt was made — a record from before a provider was connected stays eligible rather than being marked reminded for a message that never left the building.

{ "email": "priya@example.in", "state": "opted_in", "confirmed": true }

Workspace member. A stale count is a 409: "The number you confirmed does not match the list as it is right now. Nothing was sent." — with the actual current figure attached.

{ "confirm_recipient_count": 400, "confirmed_by": "Priya" }

{ …campaign, status: "queued" }

Owner or admin. Any other role gets a 403: "Campaign approval requires owner or admin."

{ "comment": "Copy checked, looks good." }

{ …campaign, status: "approved", approved_by: "…", approved_at: "…" }

Workspace member. Merge fields with fallbacks, per-subscriber preview (by subscriber id or by a Wavy contact id), and a coverage check counting how many real recipients a field would render empty for. Conditional content blocks are built too: a block carries a condition in the same AND/OR grammar as list-segmentation, a {{block:name}} token in the body, and a required default so a block can never render as a hole the way an unresolved merge field can — and resolution happens inside the real send path, not only in preview, so a live send actually varies by subscriber. A merge-field catalogue documents which fields exist; the value itself still comes from the subscriber's own attributes.

{ "subject": "…", "html": "…", "unresolved_merge_fields": [],
  "would_be_sent": true, "blocked_reason": null }

Workspace member. Marked ai_generated and held for review the moment it is written, before anyone reads it.

{ "brief": "Announce our end-of-season sale, 20% off, ends Sunday." }

{ …campaign, subject: "…", body_html: "…", ai_generated: true, copy_held: true }

Workspace member. Findings present and acknowledge_findings not set is a 409 that returns the findings for the reviewer to actually look at.

{ "reviewed_by": "Priya", "acknowledge_findings": true }

{ …campaign, copy_held: false, copy_reviewed_by: "Priya", copy_reviewed_at: "…" }

Workspace member. A real AND/OR rule tree over tags, attributes, subscriber status and consent state — evaluated fresh every time, by both the segment's own preview-count and a campaign's own audience computation, so the two can never disagree with each other. Setting a segment on a campaign targets it directly. An empty condition list fails closed rather than matching everyone, and preview-count flags a segment that currently matches the whole workspace so nobody sends to 'everyone' by accident.

{ "name": "Engaged newsletter, Mumbai", "rules": { "op": "and", "conditions": [
  { "field": "tags", "op": "contains", "value": "newsletter" },
  { "field": "consent_state", "op": "eq", "value": "opted_in" } ] } }

{ "id": "…", "name": "Engaged newsletter, Mumbai", "rules": { … } }

Workspace member. A real AND/OR rule tree over tags, attributes, subscriber status and consent state — evaluated fresh every time, by both the segment's own preview-count and a campaign's own audience computation, so the two can never disagree with each other. Setting a segment on a campaign targets it directly. An empty condition list fails closed rather than matching everyone, and preview-count flags a segment that currently matches the whole workspace so nobody sends to 'everyone' by accident.

{ "audience_segment_id": "…", "total": 900, "mailable": 400,
  "blocked_suppressed": 60, "blocked_no_consent": 440,
  "confirm_recipient_count": 400, "merge_field_gaps": [] }

Workspace member. Per-recipient counts — queued, blocked by suppression, blocked for want of consent, accepted by the provider — are real, drawn from the recipient rows this workspace actually wrote, and a workspace-wide summary and CSV export (built in memory, never written to disk) now aggregate them across every campaign, not only one at a time.

{ "recipients": { "queued": 400, "blocked_suppressed": 60, "blocked_no_consent": 440 },
  "queued": 400, "blocked_suppressed": 60, "blocked_no_consent": 440, "delivered": 0,
  "engagement": null,
  "note": "Opens, clicks, bounces and complaints come from the sending provider's webhook feed. None is connected, so they are reported as unknown rather than as zero." }

Workspace member. A sending domain is a real record carrying its own SPF, DKIM and DMARC state. The exact records to publish are generated from the domain rather than looked up, so that half is correct with no resolver at all, and the campaign send route consults an authentication gate that refuses only on positive evidence a recorded domain's SPF or DMARC is missing. 'Unknown' never blocks a send: refusing because this deployment cannot resolve DNS would be an outage wearing a safety label. Metrics report real queued and blocked counts per stream, per day, computed from the recipient rows.

{ "configured": false, "provider": null, "spf_dkim_dmarc": null,
  "message": "…names the missing PATRI_EMAIL_PROVIDER / PATRI_EMAIL_FROM / PATRI_SMTP_URL…",
  "note": "…unknown rather than passing." }

Workspace member. A sending domain is a real record carrying its own SPF, DKIM and DMARC state. The exact records to publish are generated from the domain rather than looked up, so that half is correct with no resolver at all, and the campaign send route consults an authentication gate that refuses only on positive evidence a recorded domain's SPF or DMARC is missing. 'Unknown' never blocks a send: refusing because this deployment cannot resolve DNS would be an outage wearing a safety label. Metrics report real queued and blocked counts per stream, per day, computed from the recipient rows.

{ "marketing": { "daily_cap": 500, "min_gap_seconds": 0.5, "max_gap_seconds": 2.0, "remaining_today": 500 },
  "transactional": { "daily_cap": 5000, "min_gap_seconds": 0, "max_gap_seconds": 0 } }

Workspace member. Order confirmations, receipts and password resets run on their own stream, its own rate policy, and the same suppression gate — a bounce, complaint or manual block stops it absolutely.

{ "email": "priya@example.in", "purpose": "order_confirmation", "subject": "Your order is confirmed" }

{ "purpose": "order_confirmation", "queued": 1, "blocked_suppressed": 0 }