Lists

Overview
Docs
Updates

Note: Sprout Lists is currently in public beta. Features that integrate with Sprout Email and Custom List Types will not work until the next release of Sprout Email (coming soon).


Sprout Lists allows your users to:

Subscribe and unsubscribe to things
Follow or unfollow things
Like or unlike things

Subscribers can be added and removed to Lists within Craft, using the default Subscriber List Type, or third-party lists using a Custom List Type integration.

Note: We will use the term Subscribe throughout the docs, but you can substitute in the terms Like or Follow as you prefer.

Subscribers #

Subscribers can be added to a Subscriber List in Sprout Lists using two types of Subscriptions:

  1. Craft User Subscription: A relationship between an Element ID and a User ID
  2. Email Subscription: A relationship between an Element ID and an email address

A Subscriber can be on multiple Lists but a Subscriber can only be on a single list once. A Subscriber can be allowed to subscribe to any Element in Craft – Entries, Categories, Products, Users, Lists, etc.

When an email address is added to a Subscriber List, if the email address matches the address of a known User in Craft, a link can be created between the two (more info on the Enable User Sync setting below).

Subscribe and Unsubscribe Forms #

Example subscribe and unsubscribe form for known Craft Users using an hidden userId field:

{% set params = {
  listHandle: 'listHandle',
  userId: currentUser.id,
  elementId: entry.id,
} %}

{# Check if a user is subscribed already #}
{% if craft.sproutLists.isSubscribed(params) %}

  {# Unsubscribe a user from a specific List #}
  <form method="post" accept-charset="utf-8">
    <input type="hidden" name="action" value="sproutLists/lists/unsubscribe">
    <input type="hidden" name="listHandle" value="listHandle">
    <input type="hidden" name="elementId" value="{{ entry.id }}">
    <input type="hidden" name="userId" value="{{ currentUser.id }}">
    <input type="submit" value="Remove from List">
  </form>

{% else %}

  {# Subscribe a user to a specific List #}
  <form method="post" accept-charset="utf-8">
    <input type="hidden" name="action" value="sproutLists/lists/subscribe">
    <input type="hidden" name="listHandle" value="listHandle">
    <input type="hidden" name="elementId" value="{{ entry.id }}">
    <input type="hidden" name="userId" value="{{ currentUser.id }}">
    <input type="submit" value="Add to List">
  </form>

{% endif %}

Example subscribe and unsubscribe form for an anonymous user with an email address using an email field. Note the email field in place of the userId field in the last example.

{# Allow a user to submit their email to unsubscribe from a specific List #}
<form method="post" accept-charset="utf-8">
  <input type="hidden" name="action" value="sproutLists/lists/unsubscribe">
  <input type="hidden" name="listHandle" value="listHandle">
  <input type="hidden" name="elementId" value="{{ entry.id }}">
  <input type="email" name="email" value="[email protected]">
  <input type="submit" value="Remove from List">
</form>

{# Allow a user to submit their email to subscribe from a specific List #}
<form method="post" accept-charset="utf-8">
  <input type="hidden" name="action" value="sproutLists/lists/subscribe">
  <input type="hidden" name="listHandle" value="listHandle">
  <input type="hidden" name="elementId" value="{{ entry.id }}">
  <input type="email" name="email" value="[email protected]">
  <input type="submit" value="Add to List">
</form>

craft.sproutLists.isSubscribed() #

To check if someone is subscribed to a list you can check for a subscription. A subscription is a relationship between a Subscriber and a List, on a particular list.

The isSubscribed variable can take the following arguments:

  • listType and listHandle (required)
  • elementId or listId (required)
  • userId or email (required)

The listType defaults to subscriber (the Sprout Lists List Type) but may be updated to work with third-party list type integrations such as mailchimp. See documentation on a specific integration for appropriate list type.

The userId can only be used if you Enable User Sync in the Sprout Lists settings.

Displaying Counts #

Subscriber Counts #

{# Total Subscribers on a given List #}
{% set totalSubscribers = craft.sproutLists.subscriberCount({ 
    listHandle: 'listHandle' 
}) %}

{{ totalSubscribers }}

List Counts #

{# Total Lists that include the subscriber with the given User ID #}
{% set totalLists = craft.sproutLists.getListCount({
  userId: currentUser.id
}) %}

{{ totalLists }}
{# Total Lists that include the subscriber with the given email #}
{% set totalLists = craft.sproutLists.getListCount({
  email: [email protected]'
}) %}

{{ totalLists }}

Getting and displaying all Subscribers (or Users) on a List #

{# All Subscribers on a List #}
{% set subscribers = craft.sproutLists.subscribers({
  listHandle: 'listHandle'
}) %}

{# Looping through the Sprout Lists Subscribers results #}
{% for subscriber in subscribers %}
    {{ subscriber.email }}
    {{ subscriber.firstName }}
    {{ subscriber.lastName }}
{% endfor %}

{# Looping through the Subscriber results as Users using the `subscriberUserIds` filter #}
{% for user in craft.users
  .id(subscribers|subscriberUserIds)
  .limit(10)
  %}
  {{ user.username }}<br/>
{% endfor %}

This requires the Enable User Sync setting to be turned on and your subscribers to be matched to User IDs in Craft.

Settings #

Enable User Sync #

When an email address is added to a Subscriber List, if the email address matches the address of a known User ID in Craft, Sprout Lists can create a link between the two. Enable this behavior the the Sprout Lists settings.

User Sync will behave as follows when enabled:

  • When a new user is created in Sprout Lists, Sprout Lists will check if any Craft Users with a matching email address also exist. If Sprout Lists will create a link between the two.
  • When a new user is created in Craft, when the user is saved if there are any matching Subscribers in Sprout Lists, their Sprout Lists Subscriber Records will be linked to the Craft User account.
  • When any updates are made to the Email, First Name, and Last Name fields of a Sprout Lists Subscriber or Craft User, those updates will be reflected in both places

Note: With User Sync enabled, if you submit a blank value for the First Name or Last Name fields (in Sprout List or Craft), the field will also be updated with a blank value in the other location. You will need to enforce First Name and Last Name fields as required if necessary.

Craft Services

Optimize Craft CMS to improve your workflows, impress your users, and acheive your business goals.

We have over 20,000 hours of Craft experience and work in close collaboration with businesses, agencies, and individuals to help make Craft CMS the best platform for you and your business. Save time and build a website that respects best practices and is designed to be scalable, maintainable, and grow with your online business and marketing needs.

Let's talk

Bring it on

  • Project Planning
  • Content Architecture
  • Data Migrations
  • Performance Optimization
  • API Integrations
  • Monthly Analysis
  • Digital Marketing Strategy

Make your life easier, your customers happy, and your business run more smoothly.

On top of our experience with the Sprout Plugin Suite, we’ve designed and built numerous custom plugins to help organizations address unique business and marketing challenges. From custom workflows to e-commerce to deep API integrations with customer databases, analytics, and cloud services, we can help build custom plugins suited to your specific needs.

Let's talk

Make things better

  • Custom Tooling
  • Improved Workflows
  • API Integrations
  • CRM Integrations
  • Email Marketing
  • Lead Generation Forms
  • E-Commerce & Donations

Spend more time focused on your business. We’ll spend the time to focus on your website.

Maintaining your website, content strategy, and customer relationships have a large impact on your business. Whether you’re a business owner, marketing director, or content author, we can help keep things running smoothly. We offer on-call and monthly retainer services to help you answer burning questions, fix annoying bugs, update software, monitor analytics, and even come running if there’s a fire.

Let's talk

We've got your back

  • General questions
  • Design changes
  • Bugfixes
  • Craft updates
  • Plugin updates
  • Coaching and Training

Build your roadmap to improve performance, usability, and identify new business opportunities.

Curious how your Craft website stacks up against all the other Craft sites out there? As a digital agency and CMS specialists who have worked with Craft since day one, our team can provide you insight into everything from content architecture to code debt. Request an audit to learn about optimization opportunities and provide a path for your business to create a better user experience and a more targeted digital strategy.

Request an Audit

Know where you stand

  • Craft Best Practices
  • Usability Audits
  • Code Audits
  • Security Audits
  • Server Audits
  • SEO Audits