WREA Seller Email Nurture Operating System — Build Specification

1. Context and strategy (why this shape)

WREA leads convert or die fast: in the last 180 days, 2,656 leads reached meeting-agents and 2,366 of those (89%) did so within 24 hours; 2,567 within 72 hours; 2,627 within 7 days. Failed outcomes are equally fast (3,022 within 24h). A long fixed drip therefore cannot be the conversion engine. The strategy this spec implements is:

• Two send systems, not six lanes. Rescue (short conversion support, days 0–7, for leads that stall) and Utility (one monthly per-property/suburb send built from modules — market data, property-value refresh, decision-relief content — where a genuine market event replaces that month's regular send rather than adding to it). Phase 0 showed the "local utility" and "market event" audiences are ~identical (10,083 vs 10,104 contacts); running them as separate systems guarantees frequency conflicts.
• A suppression/eligibility layer under everything. One function decides marketability; preview and send share that code path.
• Email capture is the binding constraint, not email cleverness. 16,455 of 30,505 property-owner contacts (730d) have no valid email; 66% of rescue candidates are unreachable. The new property value tool is the capture engine and must be instrumented from day one (§12).
• ROI = downstream CRM movement vs holdout, never opens. Campaign identity travels in SendGrid custom args and lands as columns on msg_emails, joined to milestone timestamps.

Full lane sizing and exclusion numbers are in the Appendix (§15) and in artifacts/wrea/email-nurture-phase0/2026-06-30/phase0-findings.md.

2. Executive decisions taken

These decisions are locked for Phase 0 and Phase 1. Future changes require an explicit spec revision; Felix should not silently substitute a different behaviour during implementation.

3. Requirements

3.1 Functional requirements

3.2 Non-functional requirements

• N1 — Fail closed. If eligibility cannot be computed (missing data, query error), the contact is not sent to. An exclusion with reason beats an accidental send.
• N2 — At-most-once with visible failure. A unique (enrolment_id, step_no) attempt and atomic claim prevent duplicate jobs. Ambiguous provider outcomes are surfaced for human reconciliation and never automatically retried.
• N3 — Auditable. Every attempt knows its campaign/step/enrolment/address/classification; every exclusion and stop has a reason; consent evidence and campaign status changes are attributable.
• N4 — Reversible. Pause stops new claims within one tick (≤10 min); resume shows proceed/expire counts and stale rows expire rather than drain. No destructive migration of existing CRM history.
• N5 — Deliverability-safe. Marketing classification, appropriate marketing pool, batch throttles, recency warm-up, body unsubscribe and List-Unsubscribe/List-Unsubscribe-Post headers before the first external send.
• N6 — Compliance control. Recipient-level consent evidence, sender identification and functional unsubscribe are release gates; legacy unsubscribe tags are binding. Legal/business confirmation of the recent-enquiry rescue basis gates external P1 sends, not Phase 0 engineering.

4. Current capability map and gaps (code-verified through 2026-07-11)

4.1 What already exists and is reused

4.2 Gaps to plug

5. Target architecture

5.1 The tick loop (core runtime)

every 10 min: email-nurture:tick  (withoutOverlapping, like trigger:action-queue)
  for each enrolment WHERE status='active' AND next_send_at <= now()  (chunked, ordered):
    campaign = enrolment.campaign
    if campaign.status NOT IN ('active','testing')      → skip without claiming
    step = campaign.steps[enrolment.current_step + 1]
    if no step                                          → status='completed'
    if next_send_at is older than campaign.max_overdue_hours
                                                        → stop EXPIRED
    validity = AudienceService::journeyStillValid(enrolment)
    if !validity.ok                                     → stop PROGRESSED / FAILED_STAGE / other outcome
    elig = EligibilityService::check(contact, target_address, communication_class, context)
    if !elig.ok                                         → record skip:
         hard reasons (UNSUB_TAG, ADDRESS_SUPPRESSED, BLACKLISTED,
                       NO_EMAIL, NO_CONSENT_EVIDENCE)                 → status='stopped', exclusion_reason
         soft reasons (FREQ_CAP, RECENT_STAFF_TOUCH)                  → defer next_send_at +24h (max 3 defers, then stop)
    if campaign.status='testing' AND target not in test allowlist     → exclude with TEST_ALLOWLIST reason
    template = resolve template_id or template_map[current milestone/default]
    within one DB transaction:
         INSERT email_send_attempts(status='pending')
           UNIQUE(enrolment_id, step_no); duplicate means another tick won → skip
         advance current_step and next_send_at
    after commit: dispatch job(attempt_id)
    job atomically claims pending → claimed; duplicate job exits
    deterministic error before Mail::send()             → failed (manual retry allowed)
    exception/worker death during provider call          → ambiguous (NO automatic retry)
    success: create MsgEmail normally; observer runs; attempt → sent + msg_email_id
    stale claimed attempt >30 min                        → ambiguous + operator alert
    respect campaign.throttle_per_hour (stop tick batch when exhausted)

Why not pre-create msg_emails: MsgEmailObserver treats creation as a real sent email, creates an activity and touches the property. Attempt state therefore lives separately; msg_emails is created only after a successful provider call. Absolute exactly-once delivery is impossible across an external provider boundary, so the deliberate contract is at-most-once with visible ambiguous outcomes.

6. Database schema

MySQL/InnoDB, Laravel timestamped migrations in database/migrations/, named indexes and repo-compatible integer widths. Use foreign keys only where the current migration/test conventions support them cleanly; the behavioural contract relies on unique/index constraints and service validation, not an assumed no-FK rule.

6.1 new email_campaigns

id                bigint PK
key               varchar(64)  UNIQUE      -- slug, e.g. 'fast-rescue-v1'; goes into custom_args
name              varchar(150)
lane              varchar(16)              -- 'rescue' | 'utility' | 'event' | 'tool'
status            varchar(16)  default 'draft'   -- draft|testing|active|paused|archived
description       text NULL
communication_class varchar(16) default 'marketing' -- marketing|operational; nurture is marketing
ip_pool           varchar(32)  default 'marketing'
required_consent_basis varchar(64)          -- e.g. recent_service_request
required_consent_scope varchar(64) NULL
holdout_pct       tinyint unsigned default 20
throttle_per_hour int unsigned NULL        -- null = param default
test_recipients   json NULL                -- allowlist emails used when status='testing'
settings          json NULL                -- touch window, max_overdue_hours (rescue default 48), cohort filters
created_by        unsignedInteger NULL     -- users.id
timestamps, softDeletes
INDEX idx_email_campaigns_status (status)

Status transitions: draft→testing→active⇄paused→archived. Activation fails unless consent requirements, templates, sender identity, body unsubscribe token and testing allowlist are valid. Pause takes effect within one tick. Resume confirmation shows how many overdue rows will expire and how many remain eligible; no re-anchor UI is required.

6.2 new email_campaign_steps

id            bigint PK
campaign_id   bigint unsigned          -- email_campaigns.id
step_no       smallint unsigned        -- 1..n
template_id   unsignedInteger NULL     -- templates.id (simple case)
template_map  json NULL                -- stage-branched: {"lead": 123, "failed": 124, "meeting_agents": 125}
offset_hours  int unsigned             -- from enrolment.anchor_at (step 1) / from prev send (steps 2+)
send_window   varchar(32) NULL         -- e.g. '08:00-18:00' local property timezone (reuse get_time_modified pattern)
active        boolean default true
timestamps
UNIQUE uq_campaign_step (campaign_id, step_no)

Exactly one of template_id/template_map must be set (validated in service). template_map implements D7 stage branching keyed on the property's current milestone label.

6.3 new email_enrolments

id                bigint PK
campaign_id       bigint unsigned
contact_id        unsignedInteger          -- contacts.id
property_id       unsignedInteger default 0 -- properties.id; 0 = contact-level (avoids NULL-in-unique problem)
status            varchar(16)              -- active|completed|stopped|excluded|holdout
current_step      smallint unsigned default 0
anchor_at         datetime                 -- timing origin (property.created_at for rescue; enrol time otherwise)
next_send_at      datetime NULL
last_send_at      datetime NULL
last_msg_email_id unsignedInteger NULL
defer_count       tinyint unsigned default 0
exclusion_reason  varchar(64) NULL         -- reason code at stop/exclude time
source            varchar(16)              -- workflow|manual|batch|tool
consent_basis     varchar(64)               -- copied at enrolment
consent_evidence_type varchar(32)           -- property_enquiry|tag|pvt_event|staff_record
consent_evidence_id varchar(64)              -- property id / tag id / event uuid
consent_evidence_at datetime
enrolled_by       unsignedInteger NULL
timestamps
UNIQUE uq_enrolment (campaign_id, contact_id, property_id)
INDEX idx_enrolments_due (status, next_send_at)
INDEX idx_enrolments_contact (contact_id)
INDEX idx_enrolments_property (property_id)

Holdout rows are created at enrolment and never sent. P1 evidence is recent_service_request / property_enquiry / property_id / property.created_at; failure to populate it produces NO_CONSENT_EVIDENCE. PROGRESSED is a positive pre-send outcome and is not grouped with suppression/exclusion in reporting. The unique key represents one journey record per campaign/contact/property, not a lifetime ban: an explicit re-enrol may reactivate a non-intent terminal row (TEST_ALLOWLIST, EXPIRED, PROGRESSED or other non-suppression exclusion) only after eligibility, journey validity and consent evidence are re-run and the step/anchor are reset. UNSUBSCRIBED and MANUAL_STOP are never reactivated automatically.

6.4 new email_suppressions (effective address state)

id                bigint PK
email             varchar(255)             -- lower(trim(email)); do not alter dots/plus aliases
scope             varchar(32) default 'marketing'
reason            varchar(32)              -- unsubscribe|spam|bounce|block|invalid|dropped|manual
source            varchar(32)              -- sg_webhook|one_click|landing|staff|import
contact_id        unsignedInteger NULL
msg_email_id      unsignedInteger NULL
last_event_ref    varchar(255) NULL         -- sg_event_id / one-click token id / staff action id
last_event_at     datetime
occurrences       smallint unsigned default 1
lifted_at         datetime NULL
lifted_by         unsignedInteger NULL
lift_reason       varchar(255) NULL
history           json NULL                 -- compact suppression/lift evidence; append under row lock
timestamps
UNIQUE uq_email_suppression (email, scope, reason)
INDEX idx_email_suppressions_active (email, scope, lifted_at)
INDEX idx_email_suppressions_contact (contact_id)

Active means lifted_at IS NULL. Upstream SendGrid events remain the provider-event ledger; this row is effective state with compact lift evidence. Unsubscribe/spam can only be lifted with recorded re-consent. Delivery suppressions can be manually lifted after verification. Existing blacklist remains a separate hard-block input.

6.5 new email_send_attempts (outbox + failure state)

id                bigint PK
campaign_id       bigint unsigned
enrolment_id      bigint unsigned
step_no           smallint unsigned
contact_id        unsignedInteger
email             varchar(255)             -- exact normalized target selected at claim
communication_class varchar(16) default 'marketing'
status            varchar(16)              -- pending|claimed|sent|failed|ambiguous
msg_email_id      unsignedInteger NULL
error             text NULL
claimed_at        datetime NULL
sent_at           datetime NULL
timestamps
UNIQUE uq_attempt_step (enrolment_id, step_no)
INDEX idx_attempts_status_age (status, created_at)

The unique row is the idempotency guard. A failed attempt can be deliberately reset/requeued by an admin command after eligibility and journey validity are re-checked. An ambiguous attempt cannot be retried until a human checks SendGrid activity and records the reconciliation decision.

6.6 change msg_emails — additive columns

ALTER TABLE msg_emails
  ADD campaign_id  bigint unsigned NULL,
  ADD enrolment_id bigint unsigned NULL,
  ADD step_no      smallint unsigned NULL,
  ADD communication_class varchar(16) NULL,
  ADD ip_pool varchar(32) NULL,
  ADD INDEX idx_msg_emails_campaign (campaign_id, created_at);

Written after a successful send. Legacy call sites default to operational until their P0 inventory classification is explicit; unclassified calls log loudly and P0 cannot exit while an active workflow action remains unclassified. Frequency caps count communication_class='marketing', not IP pool.

6.7 change Suppression and unsubscribe lifecycle

SuppressionService::suppressAddress() is the only writer used by SendGrid webhook events, the signed one-click POST endpoint, the existing body preference flow and staff/manual actions. It upserts normalized address state even when contact resolution fails. For unsubscribe/spam it also applies the canonical unsubscribed tag (matched by name across duplicate tag rows) and, once P1 tables exist, stops all active enrolments for the resolved contact synchronously. The one-click URL is HMAC signed, login-free, idempotent, CSRF-exempt only for that route, rate-limited, returns a generic response and remains valid for at least 30 days. GET shows a confirmation/preferences page and never unsubscribes automatically.

6.8 P3 Property value tool tables (in CRM)

pvt_events
  id bigint PK · uuid char(36) UNIQUE · occurred_at datetime
  event_type varchar(32)   -- value_requested|value_viewed|value_refreshed|return_visit|
                           -- cost_to_sell_used|report_requested|report_unlocked|
                           -- email_captured|email_verified|consent_given
  session_id varchar(64) NULL
  address_full varchar(255) NULL · suburb varchar(100) NULL · state char(3) NULL · postcode varchar(8) NULL
  property_type varchar(20) NULL · beds tinyint NULL
  estimate_low/mid/high decimal(12,2) NULL · estimate_source varchar(32) NULL · confidence varchar(16) NULL
  email varchar(255) NULL · consent json NULL   -- {scope, wording_version, ts, source_url}
  contact_id unsignedInteger NULL · property_id unsignedInteger NULL   -- resolved async
  payload json NULL · timestamps
  INDEX (event_type, occurred_at) · INDEX (contact_id) · INDEX (property_id)

property_estimates          -- history, so "your estimate changed" emails are honest
  id bigint PK · property_id unsignedInteger · as_of date
  low/mid/high decimal(12,2) · source varchar(32)   -- rea_cache|yipm|oth_suburb_type|pvt
  confidence varchar(16) NULL · sales_support smallint NULL  -- recent sales count behind the number
  timestamps · UNIQUE (property_id, as_of, source)

7. Service layer and commands

Per repo rules: thin controllers, business logic in app/Services/. New namespace App\Services\EmailNurture\. All new code paths log through the standard Laravel log with a [email-nurture] prefix.

7.1 Console commands

7.2 Touch points in existing code modifications

• app/Jobs/SendSimpleBodyEmail.php — accept attempt/campaign/classification context; do not pre-create MsgEmail; merge campaign args and stamp successful send rows. Refactor only enough to surface pre-provider vs provider-call failure to SendAttemptService.
• app/Services/Messages/SendgridEventWebhookService.php — call SuppressionService for unsubscribe/group-unsubscribe/spam/bounce/block/invalid/dropped as defined; unresolved addresses still persist.
• app/Mail/SimpleBody.php — include body unsubscribe token and SendGrid v3 List-Unsubscribe/List-Unsubscribe-Post headers on marketing class; add signed POST route/controller.
• app/Services/Workflow/Actions/SendEmailUsingTemplate.php (+ …ToContact) — pass explicit communication class; marketing-class sends call gateOrAbort(). Pool never decides class.
• app/Services/ContactService.php::sendAgentDigest() / app/Jobs/SendDigestEmail.php — vendor digest and mass path are marketing and gate at send time. Agent digest remains operational for P0 by explicit decision, not by contact-type loophole.
• app/Http/Controllers/Staff/Parameters/ParametersController.php::massMessages() — confirm step returns the PreviewService reason breakdown instead of a bare count (small change, big safety win).
• app/Observers/MsgEmailObserver.php is not disabled; instead, staff-touch queries exclude actions joined to msg_emails.campaign_id IS NOT NULL. Audit active EmailSent workflows before the first test send.
• routes/web.php / HTTP kernel — register and attach IsAdminStaff to campaign administration; all staff may use per-contact stop. Add shared asStaff() test helper if it does not exist on the target branch.

8. CRM UI surfaces

Stack: Blade + jQuery on layouts.base, statistic pages via the AbstractStatisticController two-route pattern (@plot GET view + @data POST JSON). No Vue needed for P1–P2 — plain tables are the fastest route to trustworthy. Admin-gated via IsAdminStaff middleware initially.

8.1 essential Campaign list + detail — /email-nurture

New app/Http/Controllers/Staff/EmailNurture/CampaignController.php, views under resources/views/staff/email-nurture/.

 EMAIL NURTURE — CAMPAIGNS                                        [+ New campaign]
 ┌────────────────────┬────────┬─────────┬─────────┬──────────┬──────────┬─────────────┐
 │ Campaign           │ Lane   │ Status  │ Active  │ Next 24h │ Sent 30d │ Actions     │
 ├────────────────────┼────────┼─────────┼─────────┼──────────┼──────────┼─────────────┤
 │ fast-rescue-v1     │ rescue │ ACTIVE  │     41  │      12  │     214  │ Pause View  │
 │ value-refresh-v1   │ utility│ TESTING │      6* │       6  │      18  │ Stop  View  │
 │ vic-market-jul     │ utility│ DRAFT   │      —  │       —  │       —  │ Preview     │
 └────────────────────┴────────┴─────────┴─────────┴──────────┴──────────┴─────────────┘
 * testing = internal allowlist only                     Global cap: 2 sends / 14 days

Detail page shows: communication class, consent requirement, sender identity, steps/templates with rendered preview, offsets, overdue limit, throttle, holdout and test allowlist; live audience preview; enrolments; and send attempts grouped into pending/claimed/sent/failed/ambiguous. Pause/Stop-all require confirmation. Resume confirmation shows rows that will proceed versus expire. Ambiguous attempts link to a manual reconciliation action and can never be blindly retried.

8.2 essential Audience preview (embedded in campaign detail + standalone)

 AUDIENCE PREVIEW — fast-rescue-v1            computed 2026-07-02 09:41   [Refresh]
 Candidates matching cohort ................ 399
   ├─ would enrol (send) ................... 104     ├─ holdout (20%) ............ 26
   └─ excluded ............................. 269
        NO_EMAIL ........................... 262     RECENT_STAFF_TOUCH (14d) ....  74
        UNSUB_TAG ..........................   0     FREQ_CAP ....................   3
        ADDRESS_SUPPRESSED .................  11     (overlaps shown per-contact)
 Flags (would send, but review): OPEN_TASK_CONFLICT 38
 ┌─ Sample (20) ────────────────────────────────────────────────────────────────────┐
 │ Contact      Suburb      Stage            Last staff touch   Eligibility        │
 │ J. Smith     Tarneit     Report Delivered 11d ago (call)     OK  ⚑ open task    │
 │ K. Nguyen    Baldivis    Email Nurture    —                  OK                 │
 │ …                                                                               │
 └──────────────────────────────────────────────────────────────────────────────────┘

This is R7. It renders PreviewService output — the same object the enrol command prints. The rescue view must include the touch-overlap numbers so the 137×239 question is answered on screen, permanently.

8.3 essential Email journey card on contact + property screens

New partial resources/views/staff/partials/email-journey/card.blade.php, included in staff/contact/show.blade.php and staff/property/show.blade.php following the existing @include card pattern (e.g. staff/partials/activities/card), backed by a controller partial-refresh endpoint like #other_contacts_table.

 ✉ EMAIL JOURNEY                                              Marketable: YES
 fast-rescue-v1   step 1/2 sent 30 Jun 09:12 (delivered, clicked)   next: step 2 · 2 Jul 09:12
 value-refresh-v1 EXCLUDED — RECENT_STAFF_TOUCH (call 28 Jun)
 Last marketing sends: 1 in last 14 days (cap 2)        [Stop all nurture for this contact]

This card is also the staff-conflict safeguard: consultants see what marketing sent before they dial, and can stop all nurture for a contact in one click. It also shows address suppression and failed/ambiguous attempt warnings. Campaign-generated email activities remain visible here but are excluded from RECENT_STAFF_TOUCH calculations.

8.4 essential (P2) Lane performance report — statistic pattern

New app/Http/Controllers/Staff/Statistic/EmailNurtureReportController.php extending AbstractStatisticController (routes stat.email-nurture + stat.data.email-nurture), view extends staff.statistic.main with the period filter partial.

 EMAIL LANE PERFORMANCE — 1 Jun → 30 Jun
 ┌───────────────┬───────┬───────┬────────┬───────┬────────┬───────────────┬──────────────┐
 │ Campaign      │ Sent  │ Deliv │ Bounce │ Unsub │ Click  │ Meeting-agents│ vs holdout   │
 ├───────────────┼───────┼───────┼────────┼───────┼────────┼───────────────┼──────────────┤
 │ fast-rescue-v1│  214  │  208  │   4    │   1   │  31    │ 11/214 (5.1%) │ +2.3pp (n=54)│
 │ value-refr-v1 │  480  │  471  │   6    │   3   │  74    │  6/480 (1.3%) │ +0.6pp (n=120)│
 └───────────────┴───────┴───────┴────────┴───────┴────────┴───────────────┴──────────────┘
 Downstream (fee received) is lagged — treat <60-day windows as provisional.

8.5 nice-to-have (defer)

• Email Journey Dashboard (graphical, cross-campaign live view) — the campaign list covers the need numerically first.
• Contact timeline visualisation merging sends/opens/touches — the journey card + existing activities card cover it.
• Vue campaign builder — Blade forms are fine at <10 campaigns.
• Weekly growth report email block — P3, automate only once numbers are trusted.
• Per-suburb drill-downs on the performance page.

9. Testing strategy

Repo rules are strict and this spec follows them: use DatabaseTransactions (shared test DB — never RefreshDatabase) and $this->createMock() (never Mockery). Most existing tests hand-seed rows; do the same (factories are minimal in this repo). For staff feature tests, add one shared asStaff() helper if it is still absent on the implementation branch, then use it consistently.

9.1 Unit tests (tests/Unit/Services/EmailNurture/)

9.2 Feature tests (tests/Feature/Staff/EmailNurture/)

• CampaignControllerTest — registered admin middleware, list/detail for admin, 403 for non-admin; activation lint rejects missing consent requirement, sender identity, body-unsubscribe token or internal allowlist; pause attributed; resume shows proceed/expire counts; staff stop-all works.
• PreviewEndpointTest — JSON shape (counts, reasons, samples) matches PreviewService on seeded data; no PII beyond what staff already see.
• WebhookSuppressionTest — signed unsubscribe/spam/delivery events write effective address state; unsigned event rejected when verification enabled; unresolved address still suppresses; event-hash dedupe unchanged.
• OneClickUnsubscribeTest — signed bare POST requires no login/PII, is CSRF-exempt only for the route, idempotently suppresses the exact target address and stops active contact journeys; GET never suppresses.
• SendSimpleBodyEmailCampaignArgsTest — successful attempt stamps msg_emails and provider payload with campaign/enrolment/attempt/classification/msg_email_id; marketing payload has body link plus both unsubscribe headers.
• LegacySendGateTest — marketing-class workflow/mass/vendor digest re-checks suppression at send time; operational class unaffected; pool value alone cannot bypass or activate the gate.
• WorkflowClassificationTest — inventory command ignores soft-deleted triggers/actions, reports every active email action and exits non-zero/blocks P0 completion when any is unclassified.

9.3 E2E (e2e-tests/tests/crm/, Playwright)

• email-nurture-preview.spec — open campaign detail, refresh preview, assert counts render and reason table is non-empty.
• email-journey-card.spec — contact with seeded enrolment shows the card; "Stop all nurture" stops it.

9.4 Manual QA checklist (before any real cohort)

1. Test-mode send to internal allowlist: merge tags resolve, sender/reply-to and communication class are correct, body unsubscribe present, both headers arrive as real headers, custom args visible, provider message id reconciles.
2. Unsubscribe via body and one-click header ⇒ address suppression and journey stop are visible immediately; contact excluded from the next preview. GET link scanner request does not unsubscribe.
3. Pause campaign mid-flight ⇒ no sends on next two ticks.
4. Resume after overdue threshold ⇒ confirmation shows proceed/expire counts and stale rescue rows do not send.
5. Force deterministic send failure and ambiguous provider exception ⇒ both visible in campaign detail/report; only failed is retryable.
6. Preview counts vs email-nurture:enrol dry-run counts are identical (same code path proof).

10. Phased delivery plan

Phase 0 Safety substrate — code complete; production reconciliation pending

Exit criteria: zero active workflow email actions unclassified; keep/defuse register approved; defused triggers inactive and pending queue count zero; suppression backfill reconciled with explained differences; duplicate-contact and unresolved-webhook tests green; signed one-click/body unsubscribe suppresses the normalized address; unsigned webhook rejected when verification is enabled; queued mass email suppressed after enqueue is skipped at send time; no new nurture email is sent.

Phase 1 Rescue pilot — operating layer code complete; live pilot not started

Exit criteria: attempt race tests prove one dispatch; failure/ambiguous states are visible and obey retry rules; journey guard stops progressed/stale leads; campaign-created action does not block step 2; activation lint passes; internal Gmail/Outlook/iCloud test proves headers/body unsubscribe; legal/business sign-off records rescue consent basis and recency; 15-lead lane completes with zero suppressed sends/collisions. The micro-cohort validates operation, not statistical lift.

Phase 2 Utility engine — ~1.5–2 dev weeks

Exit criteria: one full monthly utility cycle for VIC with bounce rate <2%, complaint rate <0.1%, zero suppressed sends; performance page reconciles with SendGrid dashboard counts (±2%); event-replaces-monthly logic proven by frequency-cap test.

Phase 3 Scale, events, property value tool — ~2–3 dev weeks, partly parallel with tool build

• Utility expansion NSW/QLD; recency-cohort warm-up continues.
• Market-event playbook: pre-built campaign (status draft), rate-decision template, audience by state, preview-gated manual activation (R13).
• PVT ingestion endpoint + pvt_events/property_estimates + resolver job + enrolment triggers (R14, §12).
• Weekly growth report email block (R15); dormant-lead expansion decisions data-driven from P2 lift numbers.

11. Dogfooding and rollout protocol

1. Read-only first. Every cohort/preview command is dry-run by default; production dry-runs are safe and encouraged (matches the workspace production-write safety rule).
2. Internal allowlist. Campaign in testing sends only to seeded internal contacts (Thomas, Felix, a Gmail, an Outlook, an iCloud address — deliverability spread). Run the full manual QA checklist (§9.4).
3. Micro-cohort. Rescue: the current-open 1–7d lane (~15 leads). Watch for one week: delivery, failures/ambiguous attempts, replies, staff feedback, zero conflicts. Do not claim causal lift from this sample.
4. Steady state with holdout. Rescue monthly flow (~104 send / 26 holdout at current volumes). Utility: freshest 500 by recency, then expand by cohort while bounce <2% and complaints <0.1%.
5. Weekly readout ritual. email-nurture:report numbers into the weekly growth review (Telegram/HTML per existing delivery rails). Every campaign gets a keep / fix / kill call monthly. Downstream fee data lags — hold ROI judgements on any lane younger than 60 days.
6. Kill criteria (pre-agreed). Pause a campaign immediately if: complaint rate >0.2%, bounce >5% on a batch, unsub >2% on a send, or consultants report ≥3 collision incidents in a week.

12. Property value tool instrumentation contract

The tool is being built separately; this section is the contract it must satisfy so email triggers work later. Valuation sources already investigated: REA cache / YIPM / OnTheHouse suburb-type medians (docs/odin-onthehouse-valuation-fallback-investigation-2026-06-22.md).

12.1 Events the tool must emit (→ pvt_events, §6.8)

12.2 Rules

• Value first, contact second (LocalAgentFinder-validated sequencing), but email verification is the WREA upgrade: the estimate is shown free; saving/tracking it requires the verified email.
• Normalise location at capture (canonical state/suburb/postcode) — prevents recreating the G10 mess.
• Estimates are history, not a scalar (property_estimates): "your estimate changed" emails must reference real prior values, with sales_support recorded so alerts can be confidence-gated (a suburb "median" backed by zero recent sales — e.g. the Moore Park case — must not trigger a "market moved" email).
• Delivery to CRM: authenticated POST /api/pvt/events (batchable, uuid-idempotent). An async resolver job matches address→property and email→contact, backfilling contact_id/property_id; unmatched events keep raw fields for later resolution.
• Enrolment wiring (P3): resolver outcomes call EnrolmentService (e.g. verified+consented+no meeting-agents within 24h ⇒ rescue; consent scope my_property ⇒ value-refresh watch). No direct sends from the tool, ever — everything flows through the same eligibility/journey rails.

13. Risks and safeguards

14. Locked decisions and release gates

There are no architecture questions left for Felix to decide. The following choices are locked; the checks below validate external state without reopening the design.

1. SMS: excluded from P1. Revisit as fast-rescue-v2 only after the email pilot readout and separate SMS consent/cost review.
2. Frequency: maximum 2 marketing-class emails per normalized address/contact in a rolling 14 days. Configurable after evidence; events replace rather than stack.
3. Permissions: campaign administration/pause/resume is admin-only; all staff may stop nurture for a contact. Register and test IsAdminStaff.
4. Unsubscribe ownership: CRM is source of truth. Use body unsubscribe plus List-Unsubscribe/List-Unsubscribe-Post to the signed CRM endpoint; no SendGrid ASM dependency. Validate one real internal header delivery before external sends.
5. PVT integration: authenticated, UUID-idempotent POST to CRM; no shared database and no direct sends from the tool.
6. Templates and sender: Thomas owns the two P1 rescue templates and chooses visible From name/reply identity. Activation is blocked until body unsubscribe and accurate WREA business/contact footer are present.
7. Consent release gate: before the first external rescue send, record counsel/business confirmation that a recent agent-comparison enquiry supports the two rescue emails and choose the recency limit (implementation default: 7 days). P2 separately requires a decision on legacy newsletter consent evidence.
8. Production/runtime validation: re-run workflow inventory and pending queue counts read-only; verify SendGrid webhook signature enforcement/key, current unsubscribe-tag counts, EmailSent trigger interactions and real header delivery. Differences are documented before any write/send.
9. Branch/test validation: implement against current pre_production, not the feature branch used for the July 11 review. CI is the suite-health authority; use QUEUE_DRIVER=sync and add a shared asStaff() helper if absent.

15. Appendix

15.1 Key code references (reviewed through 2026-07-11; re-check on implementation branch)

15.2 Phase 0 lane sizing (2026-06-30 dry run, read-only)

Suppression signals: MailChimp:unsubscribed 2,132 · unsubscribed 486 · Unsubscribe to Newsletter 11 · SendGrid 730d: dropped 446 ev/250 contacts, bounce 315/216, spamreport 4/4. State pools (gated): VIC 3,115 · NSW 2,554 · QLD 2,052 · WA 1,360 · SA 524 · TAS 254 · ACT 252 contacts.

15.3 Phase 0 workflow inventory baseline (local read-only review, 2026-07-11)

This is a baseline, not production proof. Phase 0 deliberately repeats the inventory against production before changing workflow or queue state.

15.4 Related documents

• artifacts/wrea/email-nurture-strategy/2026-07-02/claude-fable-context-brief.md — context brief this spec answers
• reports/wrea-email-nurture-strategy-crm-capability-2026-06-30.html — strategy & CRM capability review
• artifacts/wrea/email-nurture-phase0/2026-06-30/phase0-findings.md — dry-run numbers
• artifacts/wrea/competitor-reviews/local-agent-finder-2026-06-26/…/report/index.html — LAF valuation-tool teardown (capture sequencing)
• docs/odin-onthehouse-valuation-fallback-investigation-2026-06-22.md — valuation data sources for §12

Original specification authored by Claude (Fable 5) on 2026-07-02. Version 2.0 was jointly reviewed and corrected by Codex and Claude Code on 2026-07-11 against the strategy evidence and a read-only inspection of the wrea-multi-project/wrea codebase. Reconcile code references and production inventory at implementation start.