Skip to main content

​
Why subscription lists

Subscription lists give you and your customers control over who receives what. Instead of every user getting every marketing email, you create lists (“Product Updates”, “Beta Newsletter”, “Weekly Tips”) and customers can opt in or out independently. Halo enforces consent on every send. Users who’ve unsubscribed from a list never receive emails for that list, even if they’re in the audience. Configure at Settings > Emails > Subscriptions. Each subscription list has a consent_type:
ModelBehavior
Opt-inOnly users who have explicitly subscribed receive emails for this list. Default for new lists.
Opt-outAll users except those who have explicitly unsubscribed receive emails.
Use caseRecommended
Marketing newsletterOpt-in
Product update emailsOpt-in or opt-out depending on regulation (GDPR-leaning teams use opt-in)
Transactional notifications (account, billing)Don’t use a subscription list; these aren’t subject to opt-out

​
Subscribing and unsubscribing

Subscriptions live on contact_subscription_preferences:
  • Users can subscribe by interacting with your product (e.g. clicking a “Subscribe to updates” button)
  • Users can unsubscribe via the unsubscribe link in any email tied to a list
  • The unsubscribe page is hosted by Halo (/unsubscribe?...) and includes branding
When a user unsubscribes from a list, Halo records subscribed: false for that pair. Future sends in that list are filtered out automatically.

​
Unsubscribe page

The unsubscribe page is auto-generated and includes:
  • The list name and description
  • Unsubscribe and resubscribe buttons
  • Your help center logo and brand colors
  • Optional secondary lists for the user to manage at the same time
  • Footer with your company info (CAN-SPAM compliant)
Customize the page at Settings > Emails > Subscriptions > Unsubscribe Page Branding.

​
Failsafe behavior

Halo fails closed when subscription configuration is wrong:
  • Missing list ID → no recipients
  • Wrong-org list → no recipients
  • Subscription audience but list has zero subscribers → no recipients
This prevents accidentally blasting “everyone” when you meant to send to a specific list.

​
Audience targeting with subscription lists

When you set audience_type: subscription on a broadcast or series, you must specify a subscription_id. The audience is computed:
  • Opt-in lists: only users with subscribed: true for this list
  • Opt-out lists: all users except those with subscribed: false for this list
You can also combine subscription scoping with segment filters. A series audience can be “subscribers of the Beta Newsletter list AND on the Pro plan.”

​
Series with the unsubscribed exit rule

For series, you can add unsubscribed to the series’ exit rules. When set:
  • Before each step send, Halo checks if the user has unsubscribed from the linked list
  • If yes, the user’s pending rows are removed and they exit cleanly
  • The next step in the series is skipped, not dropped
This is critical for compliance: a user who unsubscribes from your “Welcome series” should stop receiving the rest of the series immediately.

​
Resubscribing

Users can re-subscribe at any time from the unsubscribe page. Halo restores their subscribed: true and they’re eligible for future sends.

​
Where to go next

Broadcasts

One-shot emails with subscription audiences.

Series

Multi-step sequences with subscription audiences and unsubscribe exit rules.

Sending Settings

The default unsubscribe link toggle and email branding.