---
name: set-exclusions-and-suppression
description: >-
  Keeps Meta targeting non-overlapping: excludes existing customers and purchasers from every prospecting
  and lookalike ad set, excludes downstream retargeting tiers from upstream ones, builds account-wide
  suppression audiences from churned, opted-out, or do-not-target lists, and detects overlap
  (self-competition, inflated CPMs, rising frequency) to choose between an exclusion and consolidating ad
  sets. Applies exclusions via mads_update_adset, builds suppression audiences via
  mads_create_custom_audience + mads_add_audience_members on hashed data, and honors opt-out/deletion via
  mads_remove_audience_members, not an irreversible delete. Reach for it whenever prospecting launches, a
  retargeting ladder goes live, a churn or opt-out list needs enforcing, or insights show CPM/frequency
  creep. It ends at clean, non-overlapping targeting - it does not design which tier excludes which
  (design-retargeting-ladder) or restructure a fragmented account (consolidate-fragmented-account).
---
# Set Audience Exclusions, Suppression, and Overlap Control

## Purpose
Unmanaged Meta targeting leaks spend two ways: prospecting keeps buying ads for people who already
bought, and retargeting tiers compete against each other for the same warm visitor, inflating CPMs and
frequency without adding conversions. This skill applies the exclusion and suppression layer that stops
both, and gives a clear rule for when overlap should be excluded away versus fixed by consolidating the
ad sets.

## When to run
- Launching or auditing prospecting campaigns that need a customer/purchaser exclusion.
- Standing up or auditing a retargeting ladder that needs downstream-tier exclusions.
- A churn, opt-out, or do-not-target list needs to be enforced as suppression.
- Insights show rising CPMs or frequency consistent with ad sets competing for the same pool.
- A customer requests deletion or opts out and must be removed from targeting.

## When NOT to run
- The tier structure has not been designed yet → `design-retargeting-ladder` first, then apply exclusions here.
- The source audiences for exclusion do not exist yet → `build-custom-audiences` or
  `upload-customer-list-audience` first.
- The fix requires restructuring the account beyond audience targeting (merging campaigns/ad sets
  wholesale) → `consolidate-fragmented-account`.

## Prerequisites
- Purchaser/customer custom audience(s) built (`build-custom-audiences`) or a hashed customer list
  (`upload-customer-list-audience`).
- The retargeting tier map (`design-retargeting-ladder`) if excluding within a ladder.
- Any churn/opt-out/do-not-target source identified and ready to hash and upload as suppression.
- Ad-set-level access to edit targeting.

## Procedure
1. **Inventory current targeting.** Call `mads_list_campaigns`, `mads_list_adsets`, and
   `mads_list_custom_audiences` to see every active ad set's included and excluded audiences side by side.
2. **Detect overlap.** Cross-check included-audience definitions and sizes via `mads_list_saved_audiences`
   and `mads_list_custom_audiences`, then pull `mads_run_insights`/`mads_get_insights` for
   frequency and CPM trend on the candidate ad sets. Rising CPM and frequency alongside flat or declining
   results is the actionable signal, shared audience membership alone is not automatically a problem.
3. **Build the standard prospecting exclusion.** Exclude a recent-purchaser and/or all-existing-customer
   custom audience from every prospecting and lookalike ad set via `mads_update_adset`. Preview → explicit
   user approval → commit.
4. **Apply ladder exclusions.** Per `design-retargeting-ladder`, exclude purchasers plus every downstream
   tier from each upstream tier via `mads_update_adset`, same preview → approval → commit pattern.
5. **Build suppression audiences.** Source churned/opted-out/do-not-target records via
   `hubspot_search_contacts`, `salesforce_soql_query`, or `sheets_get_values`; normalize and SHA-256 hash
   client-side (see `upload-customer-list-audience` for the exact procedure); create via
   `mads_create_custom_audience` (customer-list subtype) and add members via
   `mads_add_audience_members`; then exclude this audience from every relevant ad set via
   `mads_update_adset`.
6. **Consolidate genuine overlap.** Where step 2 finds two ad sets competing for the same pool with no
   real difference in intent, merge them rather than excluding one from the other, exclusion is for
   different-intent tiers, not for two ad sets accidentally targeting the same audience. If the overlap is
   account-wide and structural, hand off to `consolidate-fragmented-account`.
7. **Honor deletions and opt-outs immediately.** On request, remove the person from every inclusion
   audience and add them to suppression via `mads_remove_audience_members` /
   `mads_add_audience_members`, do not leave them in an audience to "age out."
8. **Verify.** Re-pull `mads_list_adsets` and confirm every prospecting/retargeting ad set carries its
   required exclusions; re-check `mads_run_insights`/`mads_get_insights` after a delivery
   cycle for CPM and frequency normalizing.
9. **Document the exclusion map.** Which audience excludes which, per ad set, and the suppression list's
   refresh/enforcement owner.

## Decision rules
- **Prospecting rule (non-negotiable):** every prospecting and lookalike ad set excludes existing
  customers/recent purchasers, with no exception short of an explicit win-back objective overriding it.
- **Ladder rule:** every retargeting tier excludes purchasers plus all tiers downstream of it, see
  `design-retargeting-ladder` for the tier order this enforces.
- **Overlap threshold:** treat overlap as actionable when paired with rising CPM/frequency and flattening
  results, not merely because two audience definitions intersect (a lookalike naturally overlaps its seed
  somewhat).
- **Exclude vs. consolidate:** exclude between ad sets that intentionally target different intent levels
  (ladder tiers); consolidate ad sets that target the same intent level with no real differentiation, excluding one from the other in that case just starves two thin pools instead of feeding one.
- **Suppression vs. exclusion:** exclusion is applied per ad set at targeting time; suppression lists
  (churn, opt-out, do-not-target) are excluded account-wide, from every ad set, prospecting and
  retargeting alike.
- **Deletion handling:** `mads_remove_audience_members` is the correct response to an opt-out or
  deletion request; `mads_delete_custom_audience` is irreversible and reserved for retiring an entire
  audience, not for removing individual members, prefer keeping the audience and removing the member.
- **Done means:** every prospecting ad set excludes customers, every retargeting tier excludes purchasers
  plus downstream tiers, every known suppression list is excluded account-wide, detected overlap is either
  justified or consolidated, and the exclusion map is written down.

## Common failure modes
- **Prospecting silently re-targeting existing customers** because no exclusion was ever attached, spend wasted on people who already converted.
- **Retargeting tiers all overlapping** with no downstream exclusion, so one visitor is eligible for
  three tiers' worth of ads at once, inflating frequency and CPM.
- **Excluding aggressively between ad sets that should just be merged**, fragments one viable audience
  into two pools too small to individually reach the ~50-event learning floor.
- **Using a hard delete instead of member_remove** for a single opt-out request, destroying an entire
  audience's history to remove one person.
- **Building a suppression list once and never refreshing it**, new opt-outs keep getting served.
- **Skipping consent/legal review on a suppression source containing EEA records**, suppression lists
  carry the same PII handling obligations as any other customer list.

## Related skills
- Run before this: `build-custom-audiences`, `upload-customer-list-audience` (sources for exclusion and
  suppression audiences), `design-retargeting-ladder` (defines which tier excludes which).
- Related: `consolidate-fragmented-account` (when overlap is account-wide and structural, not just an
  audience-targeting fix).