Audiences

Audiences provide a flexible way to manage mailing lists and subscribers. Subscribers can be stored as Craft Users or retrieved via custom queries from wherever you prefer to store your subscriber data.

Audience Types

Audience Types allow you to manage different types of audiences.

Audience Types	Description	Module
User Group	Define audience members based on their Craft User Groups	Mailer
Subscriber List	Allow Craft Users audience members to Subscribe and Unsubscribe to lists	Mailer
Data Set List	Build custom queries to define and segment audience members	Data Studio

Subscriber Lists

The Subscriber List Audience Type enhances Craft's native User Elements with additional features. Enabling the Subscriber List Audience Type allows you to:

Feature	Description
Audiences	Create one or more Subscriber List Audience
Mailing Lists	Send email to Users who are subscribed to a Subscriber List
Subscriber List Field	Allow Users to manage which lists they are on via a Subscriber Lists field that displays on the User Element Content tab
Element Index Sources	Filter Users by Subscriber List via custom sources that display in the sidebar of the Users Element Index page

A subscriber can be an existing User in Craft or created on the fly as a non-credentialed User. In either case, the Subscriber is identified by their email address.

Templating

Subscribe and Unsubscribe

A user can Subscriber or Unsubscribe from a list using the Audience ID to identify the Subscriber List. The Audience ID can be found in the sidebar of the Subscriber List Audience edit page in the control panel.

{# Retrieve a list #}
{% set subscriberListAudience = sprout.mailer.audiences
    .id(123)
    .one() %}

{# Check if the subscription already exists on a list #}
{% if subscriberListAudience.isSubscribed(currentUser.id) %}

    {# Remove a subscriber from a list #}
    <form method="post" accept-charset="utf-8">
        {{ csrfInput() }}
        <input type="hidden" name="action" value="sprout-module-mailer/subscriber-lists/remove">
        <input type="hidden" name="audience[id]" value="{{ subscriberListAudience.id }}">
        <input type="text" name="user[email]" value="{{ currentUser.email }}">
        <input type="submit" value="Remove from List">
    </form>

{% else %}

    {# Add a subscriber to a list #}
    <form method="post" accept-charset="utf-8">
        {{ csrfInput() }}
        <input type="hidden" name="action" value="sprout-module-mailer/subscriber-lists/add">
        <input type="hidden" name="audience[id]" value="{{ subscriberListAudience.id }}">
        <input type="text" name="user[email]" value="{{ currentUser.email }}">
        <input type="submit" value="Add to List">
    </form>

{% endif %}

Check if a user is subscribed using the User Element, User ID, or email address:

{% set subscriberListAudience = sprout.mailer.audiences
    .id(123)
    .one() %}

{# Check if the subscription already exists on a list #}
{% if subscriberListAudience.isSubscribed(currentUser) %}...{% endif %}
{% if subscriberListAudience.isSubscribed(123) %}...{% endif %}
{% if subscriberListAudience.isSubscribed('[email protected]') %}...{% endif %}

Querying Subscriber Lists

Subscriber Lists add the getSproutSubscriberLists method to User Elements:

{% for list in currentUser.getSproutSubscriberLists() %}
    {{ list.name }}<br>
{% endfor %}

Querying Subscribers

Subscriber Lists add the sproutSubscriberListId attribute to the craft.users query:

{% set subscribers = craft.users
    .sproutSubscriberListId(50)
    .all() %}

{% for subscriber in subscribers %}
    {{ subscriber.email }}
{% endfor %}

Displaying Counts

The number of Subscribers on a Subscriber List can be retrieved like so:

{% set subscribersCount = craft.users
    .sproutSubscriberListId(50)
    .count() %}

{{ subscribersCount }}

Developers

Custom Audience Types

To create a custom Audience Type extend the base AudienceType class and register your new class via EVENT_REGISTER_AUDIENCE_TYPES.

use BarrelStrength\Sprout\mailer\audience\AudienceType;

class MyAudienceType extends AudienceType
{
  ...
}

See the Sprout codebase for examples.

Settings

Read the Config Settings documentation to explore and customize settings.

Updates

See update guides for the Mailer and Framework modules.