Manage newsletters in Laravel
This package provides an easy way to integrate subscriptions to email lists of various email services.
Currently this package support:
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
To publish the config file to
php artisan vendor:publish --tag="newsletter-config"
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('NEWSLETTER_DRIVER', Spatie\Newsletter\Drivers\MailcoachDriver::class), /** * These arguments will be given to the driver. */ 'driver_arguments' => [ 'api_key' => env('NEWSLETTER_API_KEY'), 'endpoint' => env('NEWSLETTER_ENDPOINT'), ], /* * The list name to use when no list name is specified in a method. */ 'default_list_name' => 'subscribers', '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' => [ /* * When using the Mailcoach driver, this should be Email list UUID * which is displayed in the Mailcoach UI * * When using the MailChimp driver, this should be a MailChimp list id. * http://kb.mailchimp.com/lists/managing-subscribers/find-your-list-id. */ 'id' => env('NEWSLETTER_LIST_ID'), ], ], ];
To let this package work with Mailcoach, you need to install the Mailcoach SDK.
composer require spatie/mailcoach-sdk-php
Next, you must provide values for the API key, endpoint and
list.subscribers.id in the config file. You'll find the API key and endpoint in the Mailcoach settings screen. The value for
list.subscribers.id must be the UUID of an email list on Mailcoach. You'll find this value on the settings screen of an email list
To use MailChimp, install this extra package.
composer require drewm/mailchimp-api
driver key of the
newsletter config file must be set to
Next, you must provide values for the API key and
list.subscribers.id. You'll find these values in the MailChimp UI.
endpoint config value can be set to an empty string.
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, updating and unsubscribing
Subscribing an email address can be done like this:
use Newsletter; Newsletter::subscribe('email@example.com');
Let's unsubscribe someone:
For Mailcoach, you can pass extra attributes as the second argument:
Newsletter::subscribe('firstname.lastname@example.org', ['first_name' => 'Rince', 'last_name' => 'Wind']);
For MailChimp you can pass merge variables as the second argument:
Newsletter::subscribe('email@example.com', ['FNAME'=>'Rince', 'LNAME'=>'Wind']);
You can subscribe someone to a specific list by passing a list name:
Newsletter::subscribe('firstname.lastname@example.org', listName: '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', ['first_name' => 'Rince', 'last_name' => 'Wind']);
For MailChimp, 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.
Here's how to 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:
Getting subscriber info
You can get information on a subscriber by using the
For MailCoach, this will return an instance of
For MailChimp, 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
Need something else?
If you need more functionality you get an instance of the underlying API with
$api = Newsletter::getApi();
If you're having troubles getting the MailChimp integration, you can see the last error with:
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 email@example.com 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.