Download the PHP package jub/craft-newsletter without Composer

Newsletter Plugin for Craft CMS

Newsletter for Craft CMS plugin makes it possible to let end users subscribe with various emailing services from a frontend form.

It currently supports the following services:

• Mailchimp
• Mailjet
• Brevo (ex Sendinblue)

This plugin is GDPR compliant and requires the user to give its consent when subscribing to the newsletter.

💡 Similar to Craft Mailer adapters, you can even create your own adapter to connect to unsupported services.

Requirements

This plugin requires Craft CMS 4.0.0 or later and PHP 8.0.2 or later.

In order to support automatic Google reCAPTCHA verification, you will need to install jub/craft-google-recaptcha plugin.

Installation

1. Install with composer via composer require jub/craft-newsletter from your project directory.
2. Install the plugin in the Craft Control Panel under Settings → Plugins, or from the command line via ./craft install/plugin newsletter.

Configuration

Control Panel

You can manage configuration setting through the Control Panel by going to Settings → Newsletter

• From the Service type dropdown, select the service type you wish to use to handle newsletter users subscription
• Provide the required API keys and parameters as described below.
• If Google reCAPTCHA plugin is installed and enabled, choose whether to verify the submission or not using the Enable Google reCAPTCHA light-switch.

⚠️ When enabled, the Google reCAPTCHA feature will not render the frontend widget for you. You have to add {{ craft.googleRecaptcha.render() }} somewhere in the form view.

Service configuration

Mailjet settings

• API Key (apiKey)
• API Secret (apiSecret)
• List ID (optional) (listId)

You can find these informations in your Mailjet account informations in the REST API keys section.

You can provide a contact list ID in order to subscribe the enduser to a specific one.

If no list ID is provided, user will only be created as a contact.

Brevo (ex Sendinblue) settings

• API Key (apiKey)
• List ID (optional, required if DOI is on) (listId)
• Activate Double Opt-in (DOI) (optional) (doi)
• Mail Template ID (required if DOI is on) (doiTemplateId)
• Redirection URL (required if DOI is on) (doiRedirectionUrl)

You can find these informations in your Brevo account.

You can provide a contact list ID in order to subscribe the enduser to a specific one.

You can also enable Brevo Double Opt-in feature. You will need a Sendinblue template as described here.

If no list ID is provided, user will only be created as a contact.

Mailchimp settings

• API Key (apiKey): You can find that information from your Mailchimp account.
• Server prefix (serverPrefix): You can find that information by looking at the url when logged into your Mailchimp account. For instance, https://us4.admin.mailchimp.com/account/api/ indicate the server prefix to use is us4
• Audience ID (listId): You can find that information in Audience > All contacts > Settings > Audience name and campaign defaults

Configuration file

You can create a newsletter.php file in the config folder of your project and provide the settings as follow (example):

Depending on the service and its specific settings, adjust the adapterType to the according service adapter class name and provide required parameters in the adapterTypeSettings associative array (see Service configuration).

⚠️ Any value provided in that file will override the settings from the Control Panel.

Front-end form

You can use the following template as a starting point for your registration form:

The newsletter/newsletter/subscribe action expects the following inputs submitted as POST:

• email: User email to subscribe
• consent: Any value indicating that the user gives its consent to receive the newsletter

⚠️ Don’t forget to add {{ craft.googleRecaptcha.render() }} in the form view if the Google reCAPTCHA verification is enabled.

XHR / AJAX form

Alternatively, you can submit the newsletter form with Javascript.
This gives you more freedom to provide visual effects to the user and prevents the page from reloading and scrolling to the top of the page.
The downside is that you need to write the ajax-request.
Use the example below as a reference, note the required application/json header:

⚠️ If the Google reCAPTCHA verification is enabled, add the data.append("g-recaptcha-response", ""); to the request as well!

Custom validations

You can provide your own validations on frontend form submission in a project module or a plugin using the afterValidate event on the NewsletterForm model:

How to create an adapter

To add a new adapter for unsupported services:

Create an adapter class that extends the juban\newsletter\adapters\BaseNewsletterAdapter class.

Some small example:

The template settings view could look like this:

The adapter model can be accessed in the twig view using the adapter variable.

Last, in a module or a plugin, register the adapter as follow:

Roadmap

• Support additional form fields
• Support for multiple lists

Base plugin icon makes use of Font Awesome Free