Manage newsletters in Laravel
This package is auto-updated.
Last update: 2021-10-07 08:08:30 UTC
This package provides an easy way to integrate MailChimp with Laravel.
Should you find that Mailchimp is too expensive for your use case, consider using Mailcoach instead. Mailcoach is a premium Laravel package that allows you to self host your email lists and campaigns.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
You can install this package via composer using:
composer require spatie/laravel-newsletter
The package will automatically register itself.
To publish the config file to
php artisan vendor:publish --provider="Spatie\Newsletter\NewsletterServiceProvider"
This will publish a file
newsletter.php in your config directory with the following contents:
return [ /* * The driver to use to interact with MailChimp API. * You may use "log" or "null" to prevent calling the * API directly from your environment. */ 'driver' => env('MAILCHIMP_DRIVER', 'api'), /* * The API key of a MailChimp account. You can find yours at * https://us10.admin.mailchimp.com/account/api-key-popup/. */ 'apiKey' => env('MAILCHIMP_APIKEY'), /* * The listName to use when no listName has been specified in a method. */ 'defaultListName' => 'subscribers', /* * Here you can define properties of the lists. */ 'lists' => [ /* * This key is used to identify this list. It can be used * as the listName parameter provided in the various methods. * * You can set it to any string you want and you can add * as many lists as you want. */ 'subscribers' => [ /* * A MailChimp list id. Check the MailChimp docs if you don't know * how to get this value: * http://kb.mailchimp.com/lists/managing-subscribers/find-your-list-id. */ 'id' => env('MAILCHIMP_LIST_ID'), /* * The GDPR marketing permissions of this audience. * You can get a list of your permissions with this command: "php artisan newsletter:permissions" */ 'marketing_permissions' => [ // 'email' => '2a4819ebc7', // 'customized_online_advertising' => '4256fc7dc5', ], ], ], /* * If you're having trouble with https connections, set this to false. */ 'ssl' => true, ];
Behind the scenes v3 for the MailChimp API is used.
After you've installed the package and filled in the values in the config-file working with this package will be a breeze. All the following examples use the facade. Don't forget to import it at the top of your file.
Subscribing an email address can be done like this:
use Newsletter; Newsletter::subscribe('firstname.lastname@example.org');
Let's unsubscribe someone:
You can pass some merge variables as the second argument:
Newsletter::subscribe('email@example.com', ['FNAME'=>'Rince', 'LNAME'=>'Wind']);
Please note the at the time of this writing the default merge variables in MailChimp are named
LNAME. In our examples we use
lastNamefor extra readability.
You can subscribe someone to a specific list by using the third argument:
Newsletter::subscribe('firstname.lastname@example.org', ['FNAME'=>'Rince', 'LNAME'=>'Wind'], 'subscribers');
That third argument is the name of a list you configured in the config file.
You can also subscribe and/or update someone. The person will be subscribed or updated if he/she is already subscribed:
Newsletter::subscribeOrUpdate('email@example.com', ['FNAME'=>'Foo', 'LNAME'=>'Bar']);
You can subscribe someone to one or more specific group(s)/interest(s) by using the fourth argument:
Newsletter::subscribeOrUpdate('firstname.lastname@example.org', ['FNAME'=>'Rince','LNAME'=>'Wind'], 'subscribers', ['interests'=>['interestId'=>true, 'interestId'=>true]])
false if you want to remove someone from a group/interest.
You can also unsubscribe someone from a specific list:
Deleting is not the same as unsubscribing. Unlike unsubscribing, deleting a member will result in the loss of all history (add/opt-in/edits) as well as removing them from the list. In most cases you want to use
unsubscribe instead of
Here's how to perform a delete:
Delete all personally identifiable information related to a list member, and remove them from a list. This will make it impossible to re-import the list member.
Here's how to perform a permanent delete:
You can get information on a subscriber by using the
This will return an array with information on the subscriber. If there's no one subscribed with that
e-mail address the function will return
There's also a convenience method to check if someone is already subscribed:
Newsletter::hasMember('email@example.com'); //returns a boolean
In addition to this you can also check if a user is subscribed to your list:
Newsletter::isSubscribed('firstname.lastname@example.org'); //returns a boolean
This the signature of
public function createCampaign( string $fromName, string $replyTo, string $subject, string $html = '', string $listName = '', array $options = , array $contentOptions = )
Note the campaign will only be created, no emails will be sent out.
If you are subject to GDRP, you need to collect your user's consent. This package provides a simple artisan command that outputs a nice table with the names and ID's of your audience's marketing permissions.
Get the marketing permissions of your default list:
php artisan newsletter:permissions
You may also get the permissions of a specific list:
php artisan newsletter:permissions subscribers
Next, you need to add the permissions to your list's config:
'lists' => [ 'subscribers' => [ 'id' => env('MAILCHIMP_LIST_ID'), 'marketing_permissions' => [ 'email' => '2a4819ebc7', 'customized_online_advertising' => '4256fc7dc5', ], ], ],
Now you can easily update a subscriber's marketing permissions. The first argument is the email, the second argument the permission key from the config, the third argument a boolean to enable/disable the permission, and an optional fourth argument is the name of a specific list.
Update a subscriber's marketing permission:
Newsletter::setMarketingPermission('email@example.com', 'email', true);
If something went wrong you can get the last error with:
If you just want to make sure if the last action succeeded you can use:
Newsletter::lastActionSucceeded(); //returns a boolean
If you need more functionality you get an instance of the underlying MailChimp Api with:
$api = Newsletter::getApi();
Run the tests with:
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email firstname.lastname@example.org instead of using the issue tracker.
- Freek Van der Herten
- All Contributors be dedicated to allocating workforce on maintenance and new awesome stuff.
The MIT License (MIT). Please see License File for more information.