Introducing our SDKs for PHP and Laravel

Both self-hosted Mailcoach and Mailcoach Cloud offer a powerful API to integrate Mailcoach's functionalities in your app.

To hit the ground running, we now offer a framework agnostic SDK and a Laravel specific SDK to use our API easily.

Using the SDK

By requiring this package, you can start using the SDK in your PHP project.

composer require spatie/mailcoach-SDK-php

To get started, you must first new up an instance of Spatie\MailcoachSdk\Mailcoach.

use Spatie\MailcoachSdk\Mailcoach;

$mailcoach = new Mailcoach('<your-api-key>', '<your-mailcoach-api-endpoint>')

You can find both the API key and the Mailcoach API endpoint in the "API Tokens" screen of the Mailcoach settings.

Most endpoints of our API require a UUID to fetch subscribers, email lists, and campaigns. Those UUIDs are displayed across the Mailcoach UI.

Adding a subscriber to an email list is easy:

$mailcoach->createSubscriber([
   'email_list_uuid' => '<email-list-uuid>',
   'email' => 'john@example',
]);

Here is how to get the details of an email list:

$emailList = $mailcoach->emailList('<email-list-uuid>');

// you can get various properties of that returned object
$emailList->name; // returns the name of the mail list

Updating stuff is equally easy. Just update the property and call save().

$emailList->name = 'Updated name';
$emailList->save();

You can get all subscribers of that list by calling subscribers().

$subscribers = $mailcoach
   ->emailList('<uuid-of-email-list>')
   ->subscribers();

Optionally, you can pass filters to subscribers(). Here is how to get all subscribers with a Gmail address.

$subscribers = $mailcoach
   ->emailList('<uuid-of-email-list>')
   ->subscribers(['filter[email]=gmail.com']);

Alternatively, you can call subscribers() on $mailcoach

$subscribers = $mailcoach->subscribers('<uuid-of-email-list>', $optionalFilters);

By default, Mailcoach's endpoints are paginated with a limit of 1000. In other SDKs working with paginated data can be painful. Not so in the Mailcoach SDK! Just call ->next() to get to the next page.

Here's how you would display the email of all subscribers. This code will work, even with lists with thousands of subscribers.

// listing all subscribers of a list
$subscribers = $mailcoach->emailList('use-a-real-email-list-uuid-here')->subscribers();

do {
    foreach($subscribers as $subscriber) {
        echo $subscriber->email;
    }
} while($subscribers = $subscribers->next())

You can also create a campaign using the SDK:

$campaign = $mailcoach->createCampaign([
    'email_list_uuid' => '<email-list-uuid>',
    'name' => 'My new campaign'
    
		// optionally, you can specify the UUID of a template
   'template_uuid' => '<template-uuid'>
   
   // if that template has field, you can pass the values
   // in the `fields` array. If you use the markdown editor,
   // we'll automatically handle any passed markdown
   'fields' => [
        'title' => 'Content for the title placeholder',
        'content' => '# My title',
    ],    
]);

In fact, this same code is used to generate a new edition of the freek.dev newsletter.

Sending a test of a campaign is straightforward:

// sending a test of the campaign to the given email address
$campaign->sendTest('john@example.com');

After having verified that everything is ok, you can send the campaign:

// sending a campaign
$campaign->send();

There are a couple more methods available in the SDK. To learn more, head to the repo on GitHub.

The Laravel SDK

We also made a Laravel specific SDK that uses the framework agnostic one under the hood.

The big difference is that in the Laravel one, you don't have to new a Spatie\MailcoachSdk\Mailcoach instance yourself.

Instead, just fill in the values in the mailcoach-sdk config file (or provide a value for them in the .env file)

return [
    /*
     *  You'll find both the API token and endpoint on Mailcoach'
     *  API tokens screen in the Mailcoach settings.
     */
    'api_token' => env('MAILCOACH_API_TOKEN'),

    'endpoint' => env('MAILCOACH_API_ENDPOINT'),
];

With that out of the way, you can use the Mailcoach facade to call various methods.

$subscriber = Mailcoach::createSubscriber([
    'email' => 'john@example.com',
    'email_list_uuid' => '<email-list-uuid>',
]);

In closing

Our SDKs are the easiest way to consume our API in your app. Take a look at the readme's of both packages to learn more:

Mailcoach is the best service for sending out email campaigns. We also offer email automation that allows you to easily build a drip campaign. You can manage your content and templates via powerful HTML and Markdown editors. Start your free trial now.