Contact Policies - KaireonAI

Overview

Contact Policies are post-qualification rules that remove Offers a customer is eligible for but should not receive right now. The decision-flow engine evaluates them after qualification rules and consent checks, but before scoring and ranking. Each policy inspects materialized interaction summaries (impression counts, last-contact timestamps, outcome history) and either blocks or allows a candidate. Policies are evaluated in priority order (highest first). An allow_override policy that matches a candidate causes the engine to skip all blocking rules for that candidate. Otherwise, the first blocking rule that fires removes the candidate from the result set. Mandatory Offers (marked isMandatory) still respect frequency_cap and cross_channel_cap rules plus any policy where config.bypassable is false. All other blocking rules are skipped for mandatory Offers.

Rule Types

KaireonAI supports 10 rule types. Nine are defined across the validation schema and domain rules; one (metric_condition) lives in the engine and domain layer but is not yet exposed in the API validation enum.

Rule Type	Summary	Scopes
`frequency_cap`	Max impressions per day / week / month / total	global, offer, creative, channel
`cooldown`	Minimum hours between contacts	global, offer, creative, channel
`budget_exhausted`	Suppress when impression or spend budget consumed	offer, creative
`outcome_based`	Suppress after a specific outcome (e.g. complaint)	offer, creative
`segment_exclusion`	Exclude customers in named segments	global
`time_window`	Restrict to specific hours and days of the week	global, channel
`mutual_exclusion`	If one Offer in a group was served, suppress the others	offer
`cross_channel_cap`	Frequency cap aggregated across all channels	global, offer, creative, channel
`allow_override`	Explicitly allow contact despite other blocking rules	global, offer, creative, channel
`category_suppression`	Suppress all Offers in a category after any was shown recently	global
`metric_condition`	Block when a behavioral metric crosses a threshold	global, offer, creative, channel

metric_condition is implemented in the contact-policy engine but is not included in the API validation enum. All other ten types (including category_suppression) are fully wired end-to-end.

frequency_cap

Limits how many times a customer can be contacted within rolling time windows. You can set one or more caps on the same policy. Config fields:

Field	Type	Description
`maxPerDay`	`number`	Max impressions per calendar day
`maxPerWeek`	`number`	Max impressions per ISO week
`maxPerMonth`	`number`	Max impressions per calendar month
`maxTotal`	`number`	Lifetime impression cap

Runtime: The engine aggregates interaction summaries for the matching period and blocks the candidate when impressions >= max*.

{
  "ruleType": "frequency_cap",
  "scope": "channel",
  "scopeId": "ch_email",
  "config": {
    "maxPerDay": 1,
    "maxPerWeek": 3
  },
  "priority": 80
}

cooldown

Enforces a minimum wait period (in hours) since the last contact before the same Offer can be served again. Config fields:

Field	Type	Description
`cooldownHours`	`number`	Minimum hours between contacts

Runtime: Looks up lastContactAt from interaction summaries and blocks if fewer than cooldownHours have elapsed.

{
  "ruleType": "cooldown",
  "scope": "offer",
  "scopeId": "off_welcome_bonus",
  "config": {
    "cooldownHours": 48
  },
  "priority": 60
}

budget_exhausted

Suppresses an Offer when its impression count or spend crosses a threshold. The engine checks alltime summary records. Config fields:

Field	Type	Description
`budgetField`	`"impressions" \| "spend"`	Which metric to check
`threshold`	`number`	Value at which the Offer is suppressed

Runtime: Reads the alltime summary for the exact offer + creative + channel combination and blocks when the budget field meets or exceeds threshold.

{
  "ruleType": "budget_exhausted",
  "scope": "offer",
  "scopeId": "off_spring_promo",
  "config": {
    "budgetField": "impressions",
    "threshold": 50000
  },
  "priority": 90
}

outcome_based

Suppresses an Offer for a specified number of days after a customer records a particular outcome (e.g. complaint, opt_out). Config fields:

Field	Type	Description
`afterOutcome`	`string`	The outcome key that triggers suppression
`suppressForDays`	`number`	Number of days to suppress after that outcome

Runtime: Checks the last recorded outcome key and, if it matches afterOutcome, blocks the candidate until suppressForDays have passed.

{
  "ruleType": "outcome_based",
  "scope": "offer",
  "scopeId": "off_credit_card",
  "config": {
    "afterOutcome": "complaint",
    "suppressForDays": 90
  },
  "priority": 85
}

segment_exclusion

Blocks all Offers for customers belonging to one or more excluded segments. This is a global-only rule. Config fields:

Field	Type	Description
`excludeSegments`	`string[]`	Segment keys to exclude

Runtime: Compares segments from the Recommend request against excludeSegments. If the customer matches any, the candidate is blocked. If no segment data is available in the request, the engine fails open (allows the candidate through) to avoid blocking all offers when segment data is unavailable.

{
  "ruleType": "segment_exclusion",
  "scope": "global",
  "config": {
    "excludeSegments": ["do_not_contact", "legal_hold", "recently_churned"]
  },
  "priority": 100
}

time_window

Restricts contacts to specific hours and/or days of the week. Supports IANA timezone strings validated at write time. Config fields:

Field	Type	Description
`startHour`	`number` (0-23)	Start of allowed window (inclusive)
`endHour`	`number` (0-23)	End of allowed window (exclusive)
`daysOfWeek`	`string[]`	Allowed days: `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun`
`timezone`	`string`	IANA timezone (e.g. `America/New_York`). Falls back to UTC if omitted or invalid

Runtime: Converts the current time to the configured timezone, then checks both day-of-week and hour range. Overnight windows (e.g. startHour: 22, endHour: 6) are handled correctly.

{
  "ruleType": "time_window",
  "scope": "channel",
  "scopeId": "ch_sms",
  "config": {
    "daysOfWeek": ["Mon", "Tue", "Wed", "Thu", "Fri"],
    "startHour": 9,
    "endHour": 18,
    "timezone": "America/New_York"
  },
  "priority": 70
}

mutual_exclusion

Prevents competing Offers from being served to the same customer within a time window. If any Offer in the group has been shown recently, the others are suppressed. Config fields:

Field	Type	Description
`offerGroup`	`string[]`	List of Offer IDs that are mutually exclusive
`suppressForDays`	`number`	Days to suppress other group members after one is shown (default: 90)

Runtime: For each candidate Offer in the group, checks whether any other Offer in the group has an alltime summary with impressions > 0 and lastContactAt within suppressForDays.

{
  "ruleType": "mutual_exclusion",
  "scope": "offer",
  "scopeId": "off_platinum_card",
  "config": {
    "offerGroup": ["off_platinum_card", "off_gold_card", "off_silver_card"],
    "suppressForDays": 30
  },
  "priority": 75
}

category_suppression

Suppresses all Offers in a category (or sub-category) for a specified number of days after any Offer in that category was shown to the customer. This prevents fatigue from repeated pitches in the same product area. Config fields:

Field	Type	Description
`categoryId`	`string`	The Category ID to suppress
`subCategoryId`	`string` (optional)	Narrow to a specific sub-category
`suppressionDays`	`number`	Days to suppress after any category Offer was shown (default: 7)

Runtime: Builds a map of all Offer IDs in the target category from the current candidate set. Checks alltime summaries for any of those Offers. If any was shown within suppressionDays, all candidates in that category are blocked.

{
  "ruleType": "category_suppression",
  "scope": "global",
  "config": {
    "categoryId": "cat_auto_insurance",
    "suppressionDays": 7
  },
  "priority": 80
}

cross_channel_cap

Like frequency_cap, but aggregates impressions across all channels for the same Offer within a period. Config fields:

Field	Type	Description
`periodType`	`"daily" \| "weekly" \| "monthly"`	Aggregation period (default: `daily`)
`maxTotal`	`number`	Max total impressions across all channels in the period

Runtime: Sums impressions across all channel summaries for the Offer in the current period and blocks when the total meets or exceeds maxTotal.

{
  "ruleType": "cross_channel_cap",
  "scope": "global",
  "config": {
    "periodType": "weekly",
    "maxTotal": 5
  },
  "priority": 80
}

allow_override

An override that allows contact despite other blocking policies. When the engine finds a matching allow_override, it skips all blocking rules for that candidate. Use this for mandatory or time-sensitive Offers that must bypass normal frequency limits. Config fields:

Field	Type	Description
`allowSegments`	`string[]`	(Optional) Only apply override if customer is in one of these segments
`allowOfferIds`	`string[]`	(Optional) Only apply override for these specific Offer IDs

Runtime: allow_override policies are evaluated before all blocking rules. If both allowSegments and allowOfferIds are set, both conditions must match. The engine logs a warning for every override to maintain an audit trail.

Use allow_override sparingly. Every override is logged with a warning. Consider making overrides time-bounded by pausing or archiving them after the campaign ends.

{
  "ruleType": "allow_override",
  "scope": "offer",
  "scopeId": "off_regulatory_notice",
  "config": {
    "allowOfferIds": ["off_regulatory_notice"]
  },
  "priority": 100
}

metric_condition

Blocks candidates when a behavioral metric value crosses a threshold. Supports dimension mapping to resolve metric values per candidate.

This rule type is implemented in the contact-policy engine and domain layer (contact-policy-rules.ts) but is not yet included in the API validation schema (api-validate.ts). To use it today, add it to the ruleType enum in the validation schema or write policies directly to the database.

Config fields:

Field	Type	Description
`metricId`	`string`	The behavioral metric to evaluate
`operator`	`"gt" \| "gte" \| "lt" \| "lte" \| "eq"`	Comparison operator (default: `gte`)
`threshold`	`number`	Value that triggers suppression
`dimensionMapping`	`Record<string, string>`	Maps metric dimensions to candidate fields (e.g. `{"channel": "$candidate.channelId"}`)

Runtime: Looks up the metric value using the dimension mapping, applies the operator, and blocks if the condition is met.

{
  "ruleType": "metric_condition",
  "scope": "global",
  "config": {
    "metricId": "met_7d_impression_count",
    "operator": "gte",
    "threshold": 10,
    "dimensionMapping": {
      "channel": "$candidate.channelId"
    }
  },
  "priority": 70
}

Volume Constraints

Volume Constraints are system-wide caps that limit the total number of times an offer, category, or channel can be recommended across all customers within a time period. Unlike frequency caps (which are per-customer), volume constraints enforce business-level limits such as “no more than 20,000 email impressions per week” or “limit the Gold Card offer to 5,000 recommendations per month.”

How They Differ from Contact Policies

	Contact Policies	Volume Constraints
Scope	Per-customer	System-wide (all customers)
Question answered	”Has this customer been contacted too often?"	"Has this offer/channel been used too much overall?”
Evaluation point	After qualification, before scoring	After scoring, before response assembly
Typical use	Frequency caps, cooldowns	Inventory caps, channel throughput limits, campaign budgets

Configuration

Each volume constraint specifies a scope, period, and maximum count:

Field	Type	Required	Description
`name`	string	Yes	Human-readable name
`scope`	`"offer" \| "category" \| "channel"`	Yes	What entity the cap applies to
`scopeId`	string	Yes	The ID of the scoped entity
`period`	`"daily" \| "weekly" \| "monthly"`	Yes	Rolling time window
`maxCount`	integer	Yes	Maximum recommendations allowed in the period
`status`	`"active" \| "paused"`	No	Default `"active"`

Example: Limit the “Premium Card” offer to 10,000 recommendations per week:

{
  "name": "Premium Card Weekly Cap",
  "scope": "offer",
  "scopeId": "offer_premium_card",
  "period": "weekly",
  "maxCount": 10000,
  "status": "active"
}

Counter Mechanism

Volume counters are auto-incremented when impression outcomes are recorded via the Respond API. This means:

The counter reflects actual deliveries, not just recommendations
A recommendation that is never delivered does not consume volume
Counters reset automatically at the start of each period (midnight UTC for daily, Monday 00:00 UTC for weekly, first of month for monthly)

API

Method	Endpoint	Description
`GET`	`/api/v1/volume-constraints`	List all volume constraints
`POST`	`/api/v1/volume-constraints`	Create a new volume constraint
`PUT`	`/api/v1/volume-constraints`	Update an existing volume constraint (requires `id`)
`DELETE`	`/api/v1/volume-constraints?id={id}`	Delete a volume constraint

Use volume constraints alongside contact policies for complete control. Contact policies protect individual customers from over-contact; volume constraints protect your business from over-committing inventory or exceeding channel capacity.

Scopes

Every Contact Policy operates within one of four scopes, which determines which candidates it applies to.

Scope	Matches When	Typical Use
`global`	Always matches every candidate	Company-wide compliance rules
`offer`	`scopeId` equals the candidate’s Offer ID	Product-specific frequency limits
`creative`	`scopeId` equals the candidate’s Creative ID	Creative-level fatigue rules
`channel`	`scopeId` equals the candidate’s Channel ID	Channel-specific time windows or caps

Not every rule type supports every scope. The table in the Rule Types section above shows allowed scopes per rule type. The UI dynamically filters the scope dropdown based on your selected rule type.

Use global scope for company-wide compliance rules (e.g. “no more than 5 contacts per week across all channels”) and narrower scopes for product-specific constraints.

Priority and Conflict Resolution

Each Contact Policy has a priority value from 0 to 100 (default: 50). Higher values are evaluated first. The engine resolves conflicts as follows:

Sort all active policies by priority descending.
Separate allow_override policies from blocking policies.
For each candidate, check allow_override policies first. If any matches, the candidate is explicitly allowed and all blocking rules are skipped.
Otherwise, evaluate blocking policies in priority order. The first rule that blocks removes the candidate.
Unknown rule types fail open (the candidate is allowed through) with a warning log. This prevents misconfigured rule types from silently killing all offers, but also means invalid policies provide zero protection.

This means a priority-100 allow_override will beat a priority-100 frequency_cap because overrides are always checked first regardless of priority.

Suppressions (Pre-Computed Enforcement)

Starting with recent releases, contact policies are enforced via pre-computed suppression records rather than being evaluated live at decision time. This architecture dramatically reduces latency in the Recommend API by replacing per-policy evaluation with a single database read.

How It Works

Write path (Respond API): When a respond call records an outcome that triggers a policy threshold (e.g., a frequency cap is reached, a cooldown begins), the engine writes a suppression record to the database with an expiry timestamp and the relevant scope (offer, creative, channel, or category).
Read path (Recommend API): At decision time, the engine loads all active (non-expired) suppressions for the customer in one query. Any candidate matching a suppression is immediately removed — no per-policy evaluation needed.

This means the cost of contact policy enforcement at decision time is constant regardless of how many policies are configured.

Pre-Computed vs Live-Evaluated Policy Types

Not all policy types can be pre-computed. Policies that depend on the current request context (time of day, customer segments in the request payload) must still evaluate live.

Enforcement	Policy Types
Pre-computed (suppression records)	`cooldown`, `outcome_based`, `mutual_exclusion`, `category_suppression`, `frequency_cap`, `cross_channel_cap`, `budget_exhausted`
Live-evaluated (checked at decision time)	`time_window`, `segment_exclusion`, `allow_override`

The seven pre-computed types cover the vast majority of contact policies. The three live-evaluated types are inherently request-dependent and cannot be pre-computed.

Suppression Expiry Modes

Each suppression record carries an expiresAt timestamp. The engine supports three expiry calculation modes:

Mode	Behavior	Example
`exact`	Expires exactly N hours from now	A 48-hour cooldown expires at the same time of day, two days later
`calendar_day`	Expires at midnight (UTC) on day N	A 7-day suppression created on Monday expires at midnight the following Monday
`end_of_day`	Expires at midnight (UTC) tonight	A daily frequency cap resets at the start of the next calendar day

Audit Trail

Every suppression record embeds evidence — a JSON object containing the policy ID, rule type, the threshold that was crossed, and the interaction that triggered it. This evidence is preserved for the lifetime of the suppression and is surfaced in decision traces when debug mode is enabled.

{
  "customerId": "C-4821",
  "scope": "channel",
  "scopeId": "ch_email",
  "reason": "frequency_cap",
  "policyId": "cp_email_weekly",
  "expiresAt": "2026-03-30T00:00:00Z",
  "expiryMode": "end_of_day",
  "evidence": {
    "ruleType": "frequency_cap",
    "threshold": { "maxPerWeek": 3 },
    "actual": 3,
    "triggeredBy": "interaction_abc123"
  }
}

Escalating Suppressions

When a customer repeatedly triggers the same policy, the suppression duration escalates automatically. Each suppression record tracks a triggerCount that increments on each re-trigger, and the engine looks up the matching escalation tier to determine how long the next suppression lasts. Configuration: Add an escalation array to any suppression-eligible policy’s config alongside the base cooldownHours:

{
  "cooldownHours": 48,
  "escalation": [
    { "trigger": 2, "durationDays": 14 },
    { "trigger": 3, "durationDays": 90 },
    { "trigger": 4, "action": "permanent" }
  ]
}

How it works:

Trigger Count	Behavior
1 (first trigger)	Base suppression duration applies (e.g. `cooldownHours: 48`)
2	Matches `trigger: 2` tier — suppressed for 14 days
3	Matches `trigger: 3` tier — suppressed for 90 days
4+	Matches `trigger: 4` with `"action": "permanent"` — suppressed for 10 years

Reset behavior: If the customer does not re-trigger the policy within 7 days of the current suppression’s expiry, the triggerCount resets to zero. The next violation starts fresh at tier 1.

Use escalating suppressions for policies like outcome_based (e.g. complaints) or cooldown where repeat offenders should face progressively longer quiet periods. The "permanent" action is implemented as a 10-year suppression to avoid infinite timestamps.

Field Reference

All fields accepted by the POST /api/v1/contact-policies endpoint:

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	Unique policy name
`description`	`string`	No	`""`	Human-readable description
`status`	`"draft" \| "active" \| "paused" \| "archived"`	No	`"active"`	Only `active` policies are evaluated at decision time
`scope`	`"global" \| "offer" \| "creative" \| "channel"`	No	`"offer"`	Which entity level this policy targets
`scopeId`	`string \| null`	No	`null`	The ID of the scoped entity (required unless scope is `global`)
`ruleType`	enum (see Rule Types)	Yes	—	One of the nine API-supported rule types
`config`	`object`	No	`{}`	Rule-specific configuration (see each rule type above)
`priority`	`integer` (0-100)	No	`50`	Evaluation order; higher = evaluated first

Worked Example

Setup

Customer C-4821 has already received 3 emails this week for the “Spring Promo” Offer. A frequency_cap policy limits the email channel to 3 per week. Policy:

{
  "id": "cp_email_weekly",
  "name": "Weekly Email Cap",
  "ruleType": "frequency_cap",
  "scope": "channel",
  "scopeId": "ch_email",
  "config": { "maxPerWeek": 3 },
  "priority": 80,
  "status": "active"
}

Step 1 — Frequency Cap Blocks

When the Recommend API runs for customer C-4821, the engine:

Loads the weekly interaction summary: impressions = 3 for ch_email in the current ISO week.
Evaluates frequency_cap: 3 >= 3 (maxPerWeek) — BLOCKED.
The candidate is removed from the result set.

Decision trace (debug mode):

{
  "contactPolicyReasons": [
    {
      "offerId": "off_spring_promo",
      "creativeId": "cr_spring_email_v2",
      "reason": "Weekly frequency cap reached: 3/3",
      "policyId": "cp_email_weekly"
    }
  ]
}

Step 2 — Allow Override Bypasses the Cap

Now suppose a regulatory notice must reach C-4821 regardless of frequency limits. An allow_override policy exists:

{
  "id": "cp_regulatory_override",
  "name": "Regulatory Notice Override",
  "ruleType": "allow_override",
  "scope": "offer",
  "scopeId": "off_regulatory_notice",
  "config": {
    "allowOfferIds": ["off_regulatory_notice"]
  },
  "priority": 100,
  "status": "active"
}

The engine evaluates allow_override policies before blocking rules. Because this override matches the regulatory notice Offer, the frequency_cap is never checked for that candidate. The regulatory notice is delivered. The engine logs a warning:

WARN [contact-policy-engine] allow_override policy bypassing contact policy
  — ensure this override is time-bounded and approved
  { policyId: "cp_regulatory_override", offerId: "off_regulatory_notice" }

API Quick Reference

Method	Endpoint	Auth	Description
`GET`	`/api/v1/contact-policies`	viewer, editor, admin	List policies (paginated, sorted by priority desc)
`POST`	`/api/v1/contact-policies`	admin	Create a new policy
`PUT`	`/api/v1/contact-policies`	admin	Update an existing policy (requires `id` in body)
`DELETE`	`/api/v1/contact-policies?id={id}`	admin	Soft-delete a policy

Deleting a policy uses soft-delete (the record is retained with a deletedAt timestamp). If the policy is referenced by any Decision Flow’s draftConfig, the response includes a warnings array listing affected flows (ghost reference check). Updates use auditedUpdate to create audit snapshots and increment rowVersion. See the API Reference for full request and response schemas.

Contact Policies vs Volume Constraints

Contact policies and volume constraints are complementary mechanisms that are both enforced during the Contact Policy pipeline stage, but they protect different things:

	Contact Policies	Volume Constraints
Protects	Individual customers	The business
Purpose	Frequency caps, cooldowns, suppressions	Budget caps, inventory limits, channel quotas
Scope	Per-customer interaction history	System-wide counters across all customers

Evaluation order: Contact policies are evaluated first, then volume constraints filter the remaining candidates. A customer may pass all contact policy checks but still be blocked by a volume constraint if the offer, category, or channel has reached its delivery cap.

Use both together for complete control. Contact policies prevent individual customer fatigue; volume constraints prevent over-committing inventory or exceeding channel capacity. See the Volume Constraints page for configuration details.

Qualification Rules

Rules evaluated before Contact Policies that determine initial Offer eligibility.

Volume Constraints

System-wide delivery caps on offers, categories, and channels.

Behavioral Metrics

Create metrics from interaction data to drive metric_condition policies.

Decision Flows

The pipeline that orchestrates qualification, contact policies, scoring, and ranking.

Get Started

Deploy & Operate

Runbooks

Data Platform

Decisioning Studio

Execute & Optimize

Intelligence

Platform & Security

Integrations

Reports

Release Notes

​Overview

​Rule Types

​frequency_cap

​cooldown

​budget_exhausted

​outcome_based

​segment_exclusion

​time_window

​mutual_exclusion

​category_suppression

​cross_channel_cap

​allow_override

​metric_condition

​Volume Constraints

​How They Differ from Contact Policies

​Configuration

​Counter Mechanism

​API

​Scopes

​Priority and Conflict Resolution

​Suppressions (Pre-Computed Enforcement)

​How It Works

​Pre-Computed vs Live-Evaluated Policy Types

​Suppression Expiry Modes

​Audit Trail

​Escalating Suppressions

​Field Reference

​Worked Example

​Setup

​Step 1 — Frequency Cap Blocks

​Step 2 — Allow Override Bypasses the Cap

​API Quick Reference

​Contact Policies vs Volume Constraints

​Related

Qualification Rules

Volume Constraints

Behavioral Metrics

Decision Flows

Overview

Rule Types

frequency_cap

cooldown

budget_exhausted

outcome_based

segment_exclusion

time_window

mutual_exclusion

category_suppression

cross_channel_cap

allow_override

metric_condition

Volume Constraints

How They Differ from Contact Policies

Configuration

Counter Mechanism

API

Scopes

Priority and Conflict Resolution

Suppressions (Pre-Computed Enforcement)

How It Works

Pre-Computed vs Live-Evaluated Policy Types

Suppression Expiry Modes

Audit Trail

Escalating Suppressions

Field Reference

Worked Example

Setup

Step 1 — Frequency Cap Blocks

Step 2 — Allow Override Bypasses the Cap

API Quick Reference

Contact Policies vs Volume Constraints

Related