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.
You can install this package via composer using:
composer require pomeloproductions/laravel-newsletter
The package will automatically register itself.
To publish the config file to config/newsletter.php
run:
php artisan vendor:publish --provider="PomeloProductions\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'),
],
],
/*
* 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.
use Newsletter;
Subscribing an email address can be done like this:
use Newsletter;
Newsletter::subscribe('rincewind@discworld.com');
Let's unsubscribe someone:
Newsletter::unsubscribe('the.luggage@discworld.com');
You can pass some merge variables as the second argument:
Newsletter::subscribe('rincewind@discworld.com', ['FNAME'=>'Rince', 'LNAME'=>'Wind']);
Please note the at the time of this writing the default merge variables in MailChimp are named
FNAME
andLNAME
. In our examples we usefirstName
andlastName
for extra readability.
You can subscribe someone to a specific list by using the third argument:
Newsletter::subscribe('rincewind@discworld.com', ['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('rincewind@discworld.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('rincewind@dscworld.com', ['FNAME'=>'Rince','LNAME'=>'Wind'], 'subscribers', ['interests'=>['interestId'=>true, 'interestId'=>true]])
Simply add false
if you want to remove someone from a group/interest.
You can also unsubscribe someone from a specific list:
Newsletter::unsubscribe('rincewind@discworld.com', 'subscribers');
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 delete
.
Here's how to perform a delete:
Newsletter::delete('rincewind@discworld.com');
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:
Newsletter::deletePermanently('rincewind@discworld.com');
You can get information on a subscriber by using the getMember
function:
Newsletter::getMember('lord.vetinari@discworld.com');
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 false
There's also a convenience method to check if someone is already subscribed:
Newsletter::hasMember('nanny.ogg@discworld.com'); //returns a boolean
In addition to this you can also check if a user is subscribed to your list:
Newsletter::isSubscribed('lord.vetinari@discworld.com'); //returns a boolean
This the signature of createCampaign
:
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 something went wrong you can get the last error with:
Newsletter::getLastError();
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:
vendor/bin/phpunit
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email bryce@pomeloproductions.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.