Communication Flags

Flags express a lead’s communication preferences. They control what automation will send out and signal what an agent should or shouldn’t do manually. Flags compose — a lead can carry several at once, and the combination matters.

The 5 flag types

Flag	What it blocks	What it does NOT block
unsubscribed	Automated email marketing (drips, newsletters, market reports).	Personal one-off emails. SMS. Phone calls.
dnc	All automated outreach across all channels.	Manual contact, but only with a logged reason for the override.
do_not_email	Email of any kind (automated and templated).	SMS. Phone calls. In-person.
do_not_text	SMS of any kind (automated and templated).	Email. Phone calls.
do_not_call	Voice calls (automated and templated).	Email. SMS.

Flag names match what you’ll see in the UI chip and in the timeline event payload.

The unsubscribed vs. dnc distinction

This is the single trap most agents migrating from other CRMs hit.

unsubscribed is the soft signal. It means “stop the marketing firehose.” A lead can be unsubscribed and still expect a personal call from you about the property they asked you about last Tuesday. You can still pick up the phone.
dnc is the hard signal. It means “off across all channels.” If you contact a dnc lead manually, the system requires you to log a reason. That reason becomes part of the audit trail.

When an unsubscribed lead asks you a question by phone, you answer. When a dnc lead asks you a question by phone, you answer and record why you reached back out.

How flags compose

A lead can have several flags active at once. The effective restriction is the union of every active flag’s blocks.

Active flags	Effective restriction
`unsubscribed`	Marketing email off. Personal email, SMS, calls allowed.
`unsubscribed` + `do_not_text`	Marketing email off. SMS off. Personal email and calls allowed.
`unsubscribed` + `do_not_email`	All email off. SMS and calls allowed.
`dnc`	All automated outreach off. Manual contact requires logged reason.
`dnc` + `do_not_call`	All automated outreach off. Manual call additionally requires logged reason (the channel-specific flag stacks on top).

The granular flags (do_not_email, do_not_text, do_not_call) are useful when a lead says something like “you can email me but please stop calling” — set do_not_call alone, not dnc.

Setting and clearing a flag

Flags are mutable. The same lead can be set to unsubscribed, clear that flag two months later, and re-set it after a future email campaign. Each set and each clear is preserved in the timeline.

A flag has a few fields you’ll see when you open one in the detail-page Flags panel:

Field	What it captures
`flag_type`	One of the five above.
`set_at`	When the flag became active.
`cleared_at`	When the flag was lifted. If null, the flag is still active.
`set_by`	The agent or system actor who set it.
`reason`	Optional free-text. Use it for context — “lead emailed asking off the property-alert list.”

Only one active record of each (lead, flag_type) exists at a time. Setting unsubscribed a second time while it’s already active is a no-op. Clearing it writes cleared_at and lets future sets create new active rows.

Where flags appear

Surface	What you see
Board card	Compact chips beside the lead name (DNC, Unsub, No-Email, etc.).
Detail page → Lifecycle card	All currently active chips with set-at timestamps.
Detail page → Timeline	A row for each set and each clear, with who and why.
Flags panel	Full editable list of historical and current flags for this lead.

What flags do NOT do

Flags don’t change the pipeline state. A lead with unsubscribed set can still progress from NEW → CONTACTING → QUALIFIED — the state machine doesn’t read flag rows.

Flags also don’t replace Client.disabled_at, which is a separate soft-delete signal at the Client record level. A disabled client and a flagged client are different states; both can exist simultaneously.

ARCHIVED (pipeline state) is not represented as a flag and never will be — it’s a state on the state machine, derived from the event log. If you’re filtering for “leads we’ve set aside,” filter on state, not on flags.

State machine card — pipeline state, the other dimension flags don’t affect
Temperature signals — engagement score, also independent of flags