--- name: engagement-suppression-workflow description: "Build a two-tier sunset workflow that re-engages dormant contacts before suppressing them. Tier 1 triggers a re-engagement campaign after a configurable inactivity window. Tier 2 suppresses contacts that fail to re-engage within a configurable re-engagement window." license: MIT metadata: author: tomgranot version: "1.1" category: automation-workflows --- # Engagement-Based Suppression Workflow Build a two-tier sunset system that protects email deliverability while giving disengaged contacts a fair chance to re-engage before suppression. ## Why Two Tiers Matter Suppressing contacts immediately after inactivity is aggressive and loses potential re-activations. A two-tier approach: - **Tier 1** (inactive for your sunset window — typically 120-270 days): Triggers a re-engagement campaign — a last chance to interact. - **Tier 2** (your re-engagement window after Tier 1 — typically 21-45 days — with still no engagement): Suppresses the contact from marketing emails. This preserves deliverability scores while maximizing the recoverable audience. ## Prerequisites - HubSpot Marketing Professional or Enterprise plan - A HubSpot service key (`HUBSPOT_ACCESS_TOKEN` in `.env`; an existing legacy private app token also works) with the `automation` scope (for the API path) - Python 3.10+ with [`uv`](https://github.com/astral-sh/uv) - A re-engagement email campaign or sequence ready to send - A custom dropdown property to track suppression status (default: `engagement_flag` — the execute script creates it if missing) ## Scripts Script paths are relative to this skill's directory. Run them from your project directory so `.env`, `data/`, and `reports/` resolve there: prefix each path with wherever this skill is installed (`skills/engagement-suppression-workflow/` in a clone of the repo). | Stage | Script | Run with | |-------|--------|----------| | Before | [`scripts/before.py`](./scripts/before.py) | `uv run scripts/before.py` | | Execute | [`scripts/execute.py`](./scripts/execute.py) | `uv run scripts/execute.py` | | After | [`scripts/after.py`](./scripts/after.py) | `uv run scripts/after.py` | `before.py` inventories existing workflows and checks for name collisions. `execute.py` creates the `engagement_flag` property (if missing) and both sunset workflows via `POST /automation/v4/flows` — **always disabled, for review in the UI before enabling**. `after.py` verifies they exist and reports enabled state. ## Workflow Design ``` TRIGGER: Last engagement date > [sunset window] ago AND email is known AND not globally unsubscribed AND [suppression status property] is unknown │ ▼ ┌────────────────────┐ │ Set [status prop] │ │ = "re-engagement │ │ sent" │ └────────┬───────────┘ │ ▼ ┌────────────────────┐ │ Enroll in │ │ re-engagement │ │ campaign/sequence │ └────────┬───────────┘ │ ▼ ┌────────────────────┐ │ Delay: [re-engage │ │ window] days │ └────────┬───────────┘ │ ▼ ┌────────────────────┐ │ IF/THEN BRANCH: │ │ Any engagement in │ │ re-engage window? │ ├──────────┬─────────┘ │ YES │ NO │ │ ▼ ▼ Clear Set [status prop] status = "suppressed" prop + set non-marketing ``` ## Building the Workflow: Two Options ### Option A: Create via the v4 Automation API (primary) **API status:** HubSpot documents the Workflows API as **beta** and subject to change. Its current reference is the date-based beta path `/automation/v4/2027-03-beta/flows`; this skill's scripts still call the unversioned `/automation/v4/flows` path, which v4's end of support on March 30, 2027 also covers. Creating workflows disabled and reviewing them in the UI is what makes a beta API acceptable here. If a script's create call starts failing, the manual UI build below is the fallback. The v4 Automation API supports creating workflows programmatically. Instead of one workflow with an if/then branch, the script decomposes the design into **two linear workflows** — which the API expresses cleanly and which are easier to reason about: 1. **Tier 1 — Flag for Re-engagement**: enrollment = last open older than the sunset window (or never) AND email known AND not globally unsubscribed AND flag unknown. Action: set `engagement_flag` = "re-engagement sent". 2. **Tier 2 — Suppress Non-responders**: enrollment = flag = "re-engagement sent" AND still no open/click after sunset + re-engagement windows. Actions: set flag = "suppressed", set marketing contact status to non-marketing. Run the scripts (configure `SUNSET_DAYS`, `REENGAGE_DAYS`, `FLAG_PROPERTY` in `execute.py` first): ```bash uv run scripts/before.py uv run scripts/execute.py ``` **Safety model:** both workflows are created with `isEnabled: false`. Review them in Automation > Workflows, then: - Add the "enroll in re-engagement sequence/email" action to Tier 1 (email/sequence IDs are portal-specific). - If the script reported it could not include the set-marketing-status action, add "Set marketing contact status" to Tier 2 in the UI (one click). - Turn both on, choosing whether to enroll existing contacts. **Payload notes:** the scripts use documented v4 action types (`0-5` set property; `0-31` set marketing contact status, with automatic fallback if your portal rejects its undocumented field shape). If a filter shape is rejected, HubSpot's own recommendation applies: build the workflow once in the UI, `GET /automation/v4/flows/{flowId}`, and adapt the script to the exact shapes your portal returns. ### Option B: Manual UI Build (single workflow with branch) Follow the step-by-step instructions in Stage 3 below. This builds the original single-workflow design with the if/then re-engagement branch, and works on portals where the Automation API is unavailable. **Alternatives:** HubSpot Breeze AI can scaffold a similar workflow from a prompt, but it creates event-based (OR) triggers instead of filter-based (AND) triggers and cannot configure re-enrollment or "is unknown" conditions — every Breeze-built trigger needs manual verification. The Claude Chrome extension can drive the workflow builder UI directly. Both are secondary to Options A and B. ## Step-by-Step Build Instructions ### Stage 1: Plan 1. Choose your **sunset window** (typically 120-270 days; default 180) and **re-engagement window** (21-45 days; default 30). 2. **Define "engagement"** for the Tier 2 check. Recommended: email open OR email click within the re-engagement window. 3. **Create or identify a re-engagement email/sequence.** A simple 1-2 email series asking "Still interested?" with a clear CTA works well. ### Stage 2: Before Run `uv run scripts/before.py` — it inventories all workflows, flags name collisions with the two planned SUNSET workflows, and writes the inventory CSV baseline. If building manually, also create your suppression status property (dropdown: "re-engagement sent", "suppressed") if it does not exist — the API path creates it automatically. ### Stage 3: Execute **Option A:** run `uv run scripts/execute.py`, then complete the UI review steps listed above. **Option B — manual UI build:** 1. **Set enrollment trigger:** - `hs_email_last_open_date` is more than your sunset window (typically 120-270 days) ago OR is unknown - AND `email` is known - AND `hs_email_optout` is not true - AND your suppression status property is unknown 2. **Action: Set contact property** - Your suppression status property = "re-engagement sent" 3. **Action: Enroll in re-engagement sequence** (or send re-engagement email) 4. **Delay: your re-engagement window (typically 21-45 days)** 5. **If/then branch:** - Condition: `hs_email_last_open_date` is less than [re-engagement window] days ago OR `hs_email_last_click_date` is less than [re-engagement window] days ago - **YES (re-engaged):** Set your suppression status property to blank/unknown (clears flag, contact returns to normal) - **NO (still disengaged):** Set your suppression status property = "suppressed" and set `hs_marketable_status` to non-marketing contact via the "Set marketing contact status" workflow action. (The property itself is read-only via direct API writes — a workflow action is the mechanism, whether the workflow is built in the UI or created via the v4 API.) 6. **Settings:** - Re-enrollment: OFF - Goal: Contact opens or clicks any email (optional — exits workflow early) 7. **Turn on the workflow.** ### Stage 4: After 1. Run `uv run scripts/after.py` (API path) to confirm both workflows exist and report their enabled state. 2. Spot-check 10-20 contacts that entered the workflow. Confirm: - Re-engagement email was sent - After the re-engagement window, disengaged contacts were suppressed - Re-engaged contacts had their suppression status property cleared (Option B) or never entered Tier 2 (Option A) 3. Monitor deliverability metrics weekly for the first month. 4. Track how many contacts re-engage vs. get suppressed — adjust the sunset window if needed. ## Rollback 1. Turn off the workflow. 2. To reverse suppressions: filter contacts where your suppression status property = "suppressed" and manually set them back to marketing contacts in the UI. 3. Clear the suppression status property values in bulk if needed. ## Tuning - **Shorten the sunset window** (e.g., 90-120 days) for aggressive deliverability improvement. - **Lengthen the re-engagement window** (e.g., 45-60 days) if your email cadence is low. - **Exclude recent customers** — add a filter to skip contacts with lifecycle stage = Customer or with a closed-won deal in the last 12 months. --- Source attribution: TomGranot Original project: https://github.com/TomGranot/HubSpot-admin-skills/blob/15db04633834a089d7314410fe8928228e561703/skills/engagement-suppression-workflow/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Tom Granot Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: TomGranot Original project: https://github.com/TomGranot/HubSpot-admin-skills/blob/15db04633834a089d7314410fe8928228e561703/skills/engagement-suppression-workflow/SKILL.md Attribution basis: Source repository record Fields of work: Marketing Roles: Email Marketer, Growth Marketer, Marketing Analyst Specialties: API Tools: HubSpot Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 11f4c5cc235fa9da31db2777d9d6257ed8f5eb79b6e92350ef718cdaae0afa22