boundstate/craft-mailchimp

Subscribe users to Mailchimp lists in Craft CMS

v4.0.0 2022-08-03 07:23 UTC

Requires

• php: ^8.0.2
• craftcms/cms: ^4.0.0
• drewm/mailchimp-api: ^2.5

Requires (Dev)

• craftcms/rector: dev-main

MIT

• Bound State Software

• mailchimp
• cms
• Craft
• craftcms
• craft-plugin

README

Subscribe users to Mailchimp lists in Craft CMS

Installation

To install the plugin, follow these instructions.

1. Open your terminal and go to your Craft project:

    cd /path/to/project
   

2. Then tell Composer to load the plugin:

    composer require boundstate/craft-mailchimp
   

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Mailchimp.

4. In the Control Panel, go to Settings → Plugins → Mailchimp and configure the plugin.

Usage

Your subscribe form template can look something like this:

<form method="post" action="" accept-charset="UTF-8">
    {{ csrfInput() }}
    <input type="hidden" name="action" value="mailchimp/subscribe">
    {{ redirectInput('subscribe/thanks') }}

    <h3><label for="name">Your Name</label></h3>
    <input id="name" type="text" name="mergeFields[NAME]" value="{{ subscription.mergeFields.NAME ?? '' }}" required>

    <h3><label for="email">Your Email</label></h3>
    <input id="email" type="email" name="email" value="{{ subscription.email ?? '' }}" required>
    {{ subscription.getErrors('email')|join() }}

    <input type="hidden" name="tags[]" value="Tag 1">
    <input type="hidden" name="tags[]" value="Tag 2">

    <input type="submit" value="Subscribe">
</form>

The only required field is email. Everything else is optional.

Redirecting after submit

If you have a redirect hidden input, the user will get redirected to it upon successfully subscribing. The following variables can be used within the URL/path you set:

• {email}
• {mergeFields}
• {tags}

For example, if you wanted to redirect to a subscribe/thanks page and pass the user’s name to it, you could set the input like this:

{{ redirectInput('subscribe/thanks?name={mergeFields.NAME}') }}

In your subscribe/thanks template, you can access URL parameters using craft.app.request.getQueryParam():

<p>Thanks for subscribing, {{ craft.app.request.getQueryParam('name') }}!</p>

Note that if you don’t include a redirect input, the current page will get reloaded.

Flash messages & API errors

When a subscribe form is submitted, the plugin will set a notice or success flash message on the user session. You can display it in your template like this:

{% if craft.app.session.hasFlash('notice') %}
    <p class="message notice">{{ craft.app.session.getFlash('notice') }}</p>
{% elseif craft.app.session.hasFlash('error') %}
    <p class="message error">{{ craft.app.session.getFlash('error') }}</p>
{% endif %}

If the Mailchimp API returns an error, the plugin also sets the subscription.apiError variable. You can display it in your template like this:

{% if subscription is defined and subscription.apiError %}
    <h3>{{ subscription.apiError.title }}</h3>
    <p>{{ subscription.apiError.detail }}</p>
{% endif %}