Skip to content
HomeStar Docs

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Each switch in the detail page’s Communication preferences section sits on a record with a few fields:

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

Section titled “Where flags appear”
Surface What you see
Board card Compact chips beside the lead name (DNC, Unsub, No-Email, etc.).
Detail page → Lifecycle card A red warning line above the Next step buttons naming any active flag, e.g. “Do Not Contact is set on this lead. Do not reach out.”
Detail page → Communication preferences Five switches at the bottom of the Lifecycle card (Do Not Contact, Unsubscribed, No Call, No Text, No Email). Flip to set or clear; the change is immediate.
Board card Do Not Contact or No Call also hides the card’s Call link.

What flags do NOT do

Section titled “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.

Section titled “Related”