digitalcrm/newsletter

Newsletter package

dev-master 2019-10-21 13:30 UTC

Requires

• php: ^7.2
• drewm/mailchimp-api: ^2.4
• illuminate/support: ^6.2

MIT

• digitalcrm

README

Install package
Create Controller, view, and rotues for this
Run

This package provides an easy way to integrate MailChimp with Laravel "5.8.*".

// at the top of your class
use Newsletter;

// ...

Newsletter::subscribe('[e-mail]');

Newsletter::unsubscribe('[e-mail]');

//Merge variables can be passed as the second argument
Newsletter::subscribe('[e-mail]', ['firstName'=>'Sam', 'lastName'=>'Vines']);

//Subscribe someone to a specific list by using the third argument:
Newsletter::subscribe('[e-mail]', ['firstName'=>'Nanny', 'lastName'=>'Ogg'], 'Name of your list');

//Subscribe someone to a specific list and require them to confirm via email:
Newsletter::subscribePending('[e-mail]', ['firstName'=>'Nanny', 'lastName'=>'Ogg'], 'Name of your list');

//Subscribe or update someone
Newsletter::subscribeOrUpdate('[e-mail]', ['firstName'=>'Foo', 'lastName'=>'Bar']);

// Change the email address of an existing subscriber
Newsletter::updateEmailAddress('[e-mail]', '[e-mail]');

//Get some member info, returns an array described in the official docs
Newsletter::getMember('[e-mail]');

//Get the member activity, returns an array with recent activity for a given user
Newsletter::getMemberActivity('[e-mail]');

//Get the members for a given list, optionally filtered by passing a second array of parameters
Newsletter::getMembers();

//Check if a member is subscribed to a list
Newsletter::isSubscribed('[e-mail]');

//Returns a boolean
Newsletter::hasMember('[e-mail]');

// Get the tags for a member in a given list
Newsletter::getTags('[e-mail]');

// Add tags for a member in a given list, any new tags will be created
Newsletter::addTags(['tag-1', 'tag-2'], '[e-mail]');

// Remove tags for a member in a given list
Newsletter::removeTags(['tag-1', 'tag-2'], '[e-mail]');

//If you want to do something else, you can get an instance of the underlying API:
Newsletter::getApi();

Installation

You can install this package via composer using:

composer require digitalcrm/newsletter

The package will automatically register itself.

To publish the config file to config/newsletter.php run:

php artisan vendor:publish --provider="Digitalcrm\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,
];

Usage

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, updating and unsubscribing

Subscribing an email address can be done like this:

use Newsletter;

Newsletter::subscribe('[e-mail]');

Let's unsubscribe someone:

Newsletter::unsubscribe('[e-mail]');

You can pass some merge variables as the second argument:

Newsletter::subscribe('[e-mail]', ['firstName'=>'Rince', 'lastName'=>'Wind']);

Please note the at the time of this writing the default merge variables in MailChimp are named FNAME and LNAME. In our examples we use firstName and lastName for extra readability.

You can subscribe someone to a specific list by using the third argument:

Newsletter::subscribe('[e-mail]', ['firstName'=>'Rince', 'lastName'=>'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('[e-mail]', ['firstName'=>'Foo', 'lastname'=>'Bar']);

You can subscribe someone to one or more specific group(s)/interest(s) by using the fourth argument:

Newsletter::subscribeOrUpdate('[e-mail]', ['firstName'=>'Rince','lastName'=>'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('[e-mail]', 'subscribers');

Deleting 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('[e-mail]');

Deleting subscribers permanently

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('[e-mail]');

Getting subscriber info

You can get information on a subscriber by using the getMember function:

Newsletter::getMember('[e-mail]');

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('[e-mail]'); //returns a boolean

In addition to this you can also check if a user is subscribed to your list:

Newsletter::isSubscribed('[e-mail]'); //returns a boolean

Creating a campaign

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 mails will be sent out.

Handling errors

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

Need something else?

If you need more functionality you get an instance of the underlying MailChimp Api with:

$api = Newsletter::getApi();