Explain and apply recipient exclusions

Purpose

Staff inspect why resolved people cannot receive marketing and deliberately subtract other groups.

How It Works

Evaluation checks each contact in a defined order and retains the first applicable exclusion. Status, selected-address availability, suppression and CRM opt-out information contribute to the current result. A coordinator may also subtract the people reached by other lists or audiences. Those references are validated when the exclusion choices are saved. Excluded audiences contribute their resolved people without recursively applying their own exclusions. Oversized exclusions fail the evaluation rather than leave only part of the intended group out. An unfamiliar contact status also fails evaluation. Checks for subscription types, repeat sending, frequency limits and environment restrictions exist but await their later data sources.

Relationships

Address selection determines which address is checked for suppression.
Status inclusion permits selected statuses without bypassing other checks.
Parameter handling supplies values when excluded audiences resolve their people.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Each resolved recipient is deliverable or carries one exclusion reason.Additional audience and list exclusions remove selected groups.
Surfaces: consoleapi
Preconditions: Evaluation has identified people and their available contact facts.
Postconditions: Excluded recipients retain the earliest applicable reason.
Intent sources: services-marketing:docs/milestones/MKT-M2.md#4. **Options**: one e-mail per person listing all their records (default) or one per record; send once per shared address (off);services-marketing:docs/milestones/MKT-M2.md#6. **Preview**: "Matching records 241 → People 233 → Deliverable 216" with a table of who is left out and why (bounced orservices-marketing:docs/milestones/MKT-M2.md#- Consent: "CRM owns it" (2026-10-20): until CRM's consent ledger exists, the gate honours CRM's global `email_opt_out`;services-marketing:docs/milestones/MKT-M1.md#D-M2services-marketing:docs/milestones/MKT-M2.md#5. A deceased contact is excluded with its reason; a user with the override permission includes it after confirming; the auditservices-marketing:docs/milestones/MKT-M2.md#8. A bounced address and a contact with `email_opt_out` are excluded with their reasons.

Controls

18 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-CRY-001 TC-DAT-002 TC-IAM-001 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PRV-001 TC-PRV-002 TC-PRV-004 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004

Permissions

Key	Checked at	Scope
`marketing.audiences.manage`	api	tenant
`marketing.audiences.view`	api	tenant

Business Rules

11 rules, 10 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Eligibility records the first failing check in this order: missing contact, inactive, deceased, missing selected address, suppression, subscription-type opt-out, global opt-out, additional exclusion, repeat restriction, frequency limit and environment restriction. no proof recorded yet	policy	service	test services-marketing:modules/resolution/tests/unit/eligibility-gate.spec.ts#lists the reason codes in the table’s order
`02`must prove Proposed	Inactive and deceased contacts are excluded unless their corresponding inclusion option is enabled. origin: services-marketing:docs/milestones/MKT-M2.md#5. A deceased contact is excluded with its reason; a user with the override permission includes it after confirming; the audit no proof recorded yet	policy	service	test services-marketing:modules/marketing/tests/unit/evaluate-audience.spec.ts#leaves out a deceased contact with its reason
`03`must prove Proposed	Active workspace suppressions exclude matching addresses regardless of case or whitespace; released suppressions do not apply, and status inclusion cannot bypass suppression. no proof recorded yet	policy	service	test services-marketing:modules/marketing/tests/integration/services/audience-evaluation.integration.spec.ts#answers an address with an active suppression, whatever its case or spacing
`04`must prove Proposed	CRM's global e-mail opt-out excludes a contact from marketing; subscription-type opt-outs await the later subscription capability. origin: services-marketing:docs/milestones/MKT-M2.md#- Consent: "CRM owns it" (2026-10-20): until CRM's consent ledger exists, the gate honours CRM's global `email_opt_out`; no proof recorded yet	policy	service	test services-marketing:modules/marketing/tests/unit/evaluate-audience.spec.ts#leaves out a contact who opted out of e-mail, as globally unsubscribed
`05`must prove Proposed	A contact absent from readable contact facts, including an alias with a missing survivor, receives the missing-contact exclusion. no proof recorded yet	policy	service	test services-marketing:modules/resolution/tests/unit/resolve-recipients.spec.ts#excludes with `contact_missing` an alias whose survivor does not exist
`06`must prove Proposed	Additional exclusions remove people reached by selected lists or audiences, with a maximum of fifty references of each kind. no proof recorded yet	policy	api, service	test services-marketing:modules/marketing/tests/unit/evaluate-audience.spec.ts#leaves out the members of the excluded list and the people of the excluded audience, with their reason
`07`must prove Proposed	Exclusion references must exist in the workspace, repeated references are consolidated, and an audience cannot exclude itself. no proof recorded yet	validation	service	test services-marketing:modules/marketing/tests/integration/services/audiences.integration.spec.ts#refuses an excluded audience that does not exist, with the code unknown_exclusion
`08`must prove Proposed	An excluded audience supplies resolved people without applying its own gate or exclusions; exceeding 100,000 contributing records fails the enclosing evaluation. no proof recorded yet	policy	service	observed services-marketing:modules/marketing/services/evaluation/evaluate-audience.ts:excludedContactIds
`09`must prove Proposed	Contacts classified as duplicates remain eligible for the gate, after merged identities resolve to survivors. no proof recorded yet	policy	service	test services-marketing:modules/resolution/tests/unit/eligibility-gate.spec.ts#passes a contact whose status is `duplicate` (chapter 04 says nothing about it)
`10`must prove Proposed	An unfamiliar contact status fails evaluation rather than selecting or silently excluding that contact. no proof recorded yet	validation	service	observed services-marketing:modules/marketing/services/evaluation/crm-reads.ts:readContactFacts
`11` Proposed	Subscription-type, repeat, frequency and environment checks currently receive empty inputs and therefore exclude no recipients.	policy	service	observed services-marketing:modules/marketing/services/evaluation/evaluate-audience.ts:evaluateAudience

Scenarios

Id	Given	When	Then	Provenance
`01`	Eight board contacts include a deceased person, an inactive person, an opted-out person, a suppressed address and a missing primary address.	Staff preview the board audience.	The five affected contacts receive their distinct exclusion reasons and contribute to the grouped totals.	test services-marketing:modules/marketing/tests/unit/evaluate-audience.spec.ts#groups the exclusions by reason
`02`	The audience subtracts the Do not contact list.	Staff request evaluation.	Listed contacts receive the additional-exclusion reason and other eligible contacts remain.	test services-marketing:modules/marketing/tests/integration/services/audience-evaluation.integration.spec.ts#leaves out the members of an excluded list, with their reason

Edge Cases

Id	Given	When	Then	Provenance
`03`	A contact is inactive and has no selected address.	Eligibility checks the contact.	The inactive-status exclusion is retained because it precedes address availability.	test services-marketing:modules/resolution/tests/unit/eligibility-gate.spec.ts#reports the status before the address when the contact is inactive and has no address

Planning

Explain and apply recipient exclusions ​

Purpose ​

How It Works ​

Relationships ​