Sprout Documentation

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.

← Sent Email →