From a78d60a127c9d6ef703daf523e4976606a385329 Mon Sep 17 00:00:00 2001
From: justin <justin@liquidator.optimal-reality.com>
Date: Mon, 8 Jun 2026 10:37:49 -0500
Subject: [PATCH] hc: auto-reply for 'already revalidated' replies + permanent
 suppression

A lead replied with proof their Medicare revalidation was already approved (CMS
data-lag: the public Revalidation Due Date List still showed them overdue weeks
after approval). Two of these arrived same-day, so:

- Carbonio auto-reply (deployed on co.carrierone.com): created mailbox
  hc-replies@ on the info@ distribution list with a Sieve that auto-acknowledges
  'my revalidation is already complete' replies (tag + mark read + file into a
  'Reval Completed (auto-acked)' folder + on-brand reply explaining the CMS lag).
  CRITICAL: info@ is the shared reply-to for ALL campaigns (healthcare, trucking,
  telecom), so every rule is anchored to Medicare/revalidation context -- a
  trucking 'MCS-150 done, this is bogus' or telecom 'RMD done' reply does NOT
  trigger it (tested + passing). A buyer guard ('please file / how much') also
  suppresses the auto-reply so a human handles the sale.
  Carbonio 25.x Sieve quirks documented (vacation/imap4flags/body :text all
  unsupported; use reply/flag/tag/body :contains).

- Permanent suppression: new data/hc_suppress.txt do-not-contact list the warmup
  honors at import AND --prune removes from the live lists. Seeded with the two
  completed providers (Pangea Lab, Yakima Valley FWC); both also blocklisted in
  listmonk_hc and removed from lists 3 + 4.
---
 docs/carbonio-reval-autoreply-setup.md     | 114 +++++++++++++++++++++
 docs/hc-reval-already-completed-reply.txt  |  23 +++++
 scripts/build_healthcare_campaigns_cron.py |  18 ++++
 3 files changed, 155 insertions(+)
 create mode 100644 docs/carbonio-reval-autoreply-setup.md
 create mode 100644 docs/hc-reval-already-completed-reply.txt

diff --git a/docs/carbonio-reval-autoreply-setup.md b/docs/carbonio-reval-autoreply-setup.md
new file mode 100644
index 0000000..d5947cd
--- /dev/null
+++ b/docs/carbonio-reval-autoreply-setup.md
@@ -0,0 +1,114 @@
+# Carbonio auto-reply: "my Medicare revalidation is already complete" replies
+
+Recurring pattern (Pangea Lab/Sue Kincer; Yakima Valley Farm Workers/Sheila
+Robertson, both same day). Root cause is the CMS data-lag window: the public CMS
+Medicare Revalidation Due Date List still shows a provider as due for several
+weeks after they have actually been approved, so a recently completed
+revalidation can still look overdue in the published data we target from. Our
+outreach matched the official list; the list was just behind reality.
+
+## How it's deployed (Carbonio / co.carrierone.com)
+
+`info@performancewest.net` is a Carbonio **distribution list**, and EVERY PW
+campaign (healthcare, trucking, telecom) uses `info@` as its reply-to. So the
+auto-reply must (a) live on a mailbox that receives `info@` mail and (b) be
+anchored to Medicare/revalidation context so it never fires on a trucking
+(MCS-150/UCR) or telecom (FCC/RMD) reply.
+
+Setup that is LIVE:
+  - Created mailbox `hc-replies@performancewest.net` and added it as a second
+    member of the `info@` distribution list (justin@ stays on it too).
+  - Installed the Sieve below on hc-replies@ via
+    `zmprov ma hc-replies@performancewest.net zimbraMailSieveScript "<script>"`
+    then `zmprov fc account hc-replies@performancewest.net`.
+  - Created folder "Reval Completed (auto-acked)" on hc-replies@.
+
+Carbonio Sieve gotchas learned the hard way (this version = 25.3.1 Zextras):
+  - `vacation` is NOT supported as an incoming-filter action -> use `reply`.
+  - `imap4flags` / `addflag` are NOT supported -> use `flag "read"`.
+  - `body :text :contains` fails ("Subnode null") -> use `body :contains`.
+  - Tagging uses the `tag` action, not addflag.
+
+## The working Sieve (as deployed)
+
+require ["fileinto", "reply", "tag", "flag", "body"];
+
+# 1) Genuine healthcare service request -> do nothing, a human handles the sale.
+if allof (
+    anyof (
+        body :contains "revalidation",
+        body :contains "medicare",
+        body :contains "pecos",
+        body :contains "npi"
+    ),
+    anyof (
+        body :contains "please file",
+        body :contains "sign me up",
+        body :contains "get started",
+        body :contains "how much",
+        body :contains "interested"
+    )
+) {
+    stop;
+}
+
+# 2) Healthcare reval "already complete / objection" -> auto-acknowledge, tag,
+#    mark read, file into the auto-acked folder. The Medicare/reval ANCHOR (first
+#    anyof) is mandatory so trucking/telecom replies on the shared info@ list
+#    (MCS-150, UCR, FCC, RMD, etc.) never trigger this.
+if allof (
+    anyof (
+        body :contains "revalidation",
+        header :contains "subject" "revalidation",
+        body :contains "medicare",
+        body :contains "pecos"
+    ),
+    anyof (
+        body :contains "was completed",
+        body :contains "already revalidated",
+        body :contains "was approved",
+        body :contains "already completed",
+        body :contains "already done",
+        body :contains "this is bogus",
+        body :contains "is bogus",
+        body :contains "completed on"
+    )
+) {
+    tag "reval-already-complete";
+    flag "read";
+    reply "Hi,
+
+Thank you for letting us know, and congratulations on completing your revalidation. We have noted it and removed your practice from any further revalidation reminders.
+
+For context: our notice was based on the CMS public Medicare Revalidation Due Date List, which CMS refreshes periodically. There is often a lag of several weeks between when a providers revalidation is approved and when CMS updates that public list, so a recently completed revalidation can still show as due in the published data. That appears to be exactly what happened here.
+
+No action is needed on your part. If we can ever help with NPI/NPPES updates, enrollment, reactivation, or OIG/SAM exclusion screening, we are glad to assist.
+
+Thank you again for the heads-up, and apologies for any confusion.
+
+Best regards,
+Performance West Compliance
+(888) 411-0383 - info@performancewest.net
+Performance West is an independent compliance firm, not affiliated with CMS or Medicare.";
+    fileinto "Reval Completed (auto-acked)";
+    stop;
+}
+
+## Tested
+  - Healthcare "Medicare revalidation was completed / this is bogus" -> auto-reply
+    sent, tagged, marked read, filed into Reval Completed (auto-acked). PASS.
+  - Trucking "MCS-150 already completed, this is bogus" -> NO reply, stays in
+    Inbox for a human. PASS.
+  - Telecom "RMD filing completed, this is bogus" -> NO reply, stays in Inbox.
+    PASS.
+  - Healthcare "please file it for me, how much" -> NO auto-reply (buyer guard),
+    stays in Inbox. PASS.
+
+## Suppression (so the warmup never re-mails a completed provider)
+Append the provider's email to data/hc_suppress.txt, then run:
+  python3 scripts/build_healthcare_campaigns_cron.py --prune-only
+The cron skips suppressed emails at import, and --prune removes them from the
+warmup lists. Done for:
+  - Pangea Laboratory LLC, NPI 1851915888 (reval approved 05/01/2026) -- skincer@medicalpracticepartner.com
+  - Yakima Valley Farm Workers Clinic, NPI 1710422407 (approved 04/29/2026) -- sheilar@yvfwc.org
+Both also blocklisted in listmonk_hc and removed from lists 3 + 4.
diff --git a/docs/hc-reval-already-completed-reply.txt b/docs/hc-reval-already-completed-reply.txt
new file mode 100644
index 0000000..2b0d813
--- /dev/null
+++ b/docs/hc-reval-already-completed-reply.txt
@@ -0,0 +1,23 @@
+SUBJECT: Re: Your Medicare revalidation — thank you for confirming
+
+Hi {{first name}},
+
+Thank you for letting us know, and congratulations on completing your
+revalidation. We have noted it and removed your practice from any further
+revalidation reminders.
+
+For context: our notice was based on the CMS public Medicare Revalidation
+Due Date List, which CMS refreshes periodically. There is often a lag of
+several weeks between when a provider's revalidation is approved and when CMS
+updates that public list, so a recently completed revalidation can still show
+as due in the published data. That appears to be exactly what happened here.
+
+No action is needed on your part. If we can ever help with NPI/NPPES updates,
+enrollment, reactivation, or OIG/SAM exclusion screening, we are glad to assist.
+
+Thank you again for the heads-up, and apologies for any confusion.
+
+Best regards,
+Performance West Compliance
+(888) 411-0383 · info@performancewest.net
+Performance West is an independent compliance firm, not affiliated with CMS or Medicare.
diff --git a/scripts/build_healthcare_campaigns_cron.py b/scripts/build_healthcare_campaigns_cron.py
index d2df7e0..45b5c26 100644
--- a/scripts/build_healthcare_campaigns_cron.py
+++ b/scripts/build_healthcare_campaigns_cron.py
@@ -49,6 +49,10 @@ def _token() -> str:
 VERIFIED_CSV = os.getenv("HC_VERIFIED_CSV", "/opt/performancewest/data/hc_warmup_week1_verified.csv")
 STATE_DIR = os.getenv("HC_STATE_DIR", "/opt/performancewest/data")
 WARMUP_STAMP = "/etc/postfix/hc-warmup-start"
+# Permanent do-not-contact list (one email per line). Providers who tell us they
+# already revalidated, asked to stop, etc. go here so the warmup NEVER imports or
+# re-mails them, regardless of segment or stale CMS data. Append + run --prune.
+SUPPRESS_FILE = os.getenv("HC_SUPPRESS_FILE", os.path.join(STATE_DIR, "hc_suppress.txt"))
 
 FROM_EMAIL = "Performance West Compliance <compliance@performancewest.net>"
 REPLY_TO = "info@performancewest.net"
@@ -58,6 +62,12 @@ REPLY_TO = "info@performancewest.net"
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from build_healthcare_campaigns import SEGMENTS, template_path  # noqa: E402
 
+
+def load_suppressed() -> set[str]:
+    if os.path.exists(SUPPRESS_FILE):
+        return {ln.strip().lower() for ln in open(SUPPRESS_FILE) if ln.strip() and not ln.startswith("#")}
+    return set()
+
 # Which segments to warm, in priority order. Revalidation stays the lead (it has
 # the most verified data + the official-record card). The others warm in
 # parallel on smaller slices so we collect engagement data across all programs
@@ -276,9 +286,11 @@ def warm_segment(seg_key: str, rows: list[dict], slice_n: int,
     campaign active. Returns how many NEW subscribers were imported."""
     seg = SEGMENTS[seg_key]
     imported = load_imported(seg_key)
+    suppressed = load_suppressed()
     candidates = [r for r in rows
                   if r.get("email", "").strip()
                   and r["email"].strip().lower() not in imported
+                  and r["email"].strip().lower() not in suppressed
                   and not _is_google_hosted(r)
                   and row_matches(seg_key, r)]
     todo = candidates[:slice_n]
@@ -339,6 +351,7 @@ def prune_holdouts(dry_run: bool) -> int:
         return 0
     rows = list(csv.DictReader(open(master_path)))
     by_email = {r.get("email", "").strip().lower(): r for r in rows if r.get("email")}
+    suppressed = load_suppressed()
     removed = 0
     for seg_key, seg in SEGMENTS.items():
         try:
@@ -351,6 +364,11 @@ def prune_holdouts(dry_run: bool) -> int:
             continue
         drop_ids = []
         for sid, email in _all_list_subscribers(list_id):
+            # Always remove anyone on the permanent do-not-contact list (they
+            # told us to stop / already revalidated), regardless of source data.
+            if email in suppressed:
+                drop_ids.append(sid)
+                continue
             r = by_email.get(email)
             if r is None:
                 continue  # not in our source data; leave it alone