EmailOctopus SDKs for PHP and Laravel

When I wanted to start a newsletter and send regular updates to the subscribers of my blog, and since I didn't have that much experience with sending email campaigns, I needed a service that is simple to use, easy to integrate, has a good reputation, and has transparent and affordable pricing plans (possibly with a free plan with essential options to try things out and get started).

I went through some usual (and some less usual) suspects like Mailchimp, MailerLite, ConvertKit, Brevo, Campaign Monitor, and so on. But none of those really clicked for me at first glance, they were either too advanced and with too many options for my needs, the prices were too steep, or some of their free and starter plans were too restrictive.

That's when I discovered EmailOctopus. I found it to be the most appropriate email marketing platform for my current needs. I really like the simplicity of their dashboard and the UI. They have a well-maintained and informative knowledge base where I was able to find anything that was possibly unclear to me. Later on, I discovered that their support is also pretty responsive. They have a very decent API as well, which is easy to use, and they offer a really generous free plan to get you started.

They achieve their affordable pricing by focusing on a single service—providing you with a way to send marketing emails. So, for example, that means that they currently don't offer an option to use a SMTP connection to set up transactional emails. All of the emails you plan on sending must be created and sent through their dashboard.

This is by no means a sponsored article, I'm speaking from my own experience and related to my particular use case. Your situation might be completely different, and you are free to stick to any service that suits your needs best.

That being said, EmailOctopus is by no means perfect; there are improvements that could be made (i.e., IDs of different resources needed for the API could be more prominent), but I found it to be near-perfect in my scenario.

Anyway, as I browsed through different integrations and community-maintained libraries and SDKs, I noticed there isn't a PHP or Laravel-based API wrapper, so I thought it would be helpful to create a PHP API client that will allow others to easily communicate with the EmailOctopus's API in their PHP applications. Using the packages I created, you can easily subscribe or unsubscribe users to your newsletter, trigger automations, and view various data about your campaigns.

PHP SDK

If you want to interact with the API in a framework-agnostic way, you can install the Email Octopus SDK for PHP using Composer:

composer require goran-popovic/email-octopus-php

Next, in order to get started you would need to create an Email Octopus API key by following the instructions from their knowledge base.

You could store your API key in an .env file, like this for example:

EMAIL_OCTOPUS_API_KEY=YOUR_API_KEY

Then you can instantiate the client easily with one or two lines of code, like so:

$apiKey = getenv('EMAIL_OCTOPUS_API_KEY');

$client = EmailOctopus::client($apiKey);

The most usual use case will probably be to add/subscribe a contact to your list when someone fills out the newsletter form on your website. This can be easily done with a few lines of code by providing a list ID and the email address of the contact:

$client->lists()->createContact(
    '00000000-0000-0000-0000-000000000000',
    [
        'email_address' => '[email protected]'
    ]
);

The ID of the list (00000000-0000-0000-0000-000000000000) can be found when editing the list in the settings tab, or in the URL in the dashboard:

IDs of other resources can also be found directly in the URL, like the automation ID, campaign ID, contact ID, and so on. So be sure to keep an eye on those.

If the contact is already subscribed to your list, or if a contact attempts to re-subscribe, the createContact API call will fail since that email already exists.

In order to handle that use case, you could check if the contact is already subscribed by trying to get it through the API first. If the contact doesn't exist, create a new one, and if the contact does exist and its status is UNSUBSCRIBED, update the status:

$response = $client->lists()->getContact(
    '00000000-0000-0000-0000-000000000000',
    '00000000-0000-0000-0000-000000000000'
);

if (isset($response['error'])) { // contact doesn't exist
    // create contact
    $client->lists()->createContact(
        '00000000-0000-0000-0000-000000000000',
        [
            'email_address' => '[email protected]'
        ]
    );
} elseif (($response['status'] ?? '') === 'UNSUBSCRIBED') {
    // update existing contact
    $client->lists()->updateContact(
        '00000000-0000-0000-0000-000000000000',
        md5('[email protected]'),
        [
            'status' => 'PENDING'
        ]
    );
}

or you could just try to create a contact every time, and if that fails with a specific error code, then update it:

$response = $client->lists()->createContact(
    '00000000-0000-0000-0000-000000000000',
    [
        'email_address' => '[email protected]'
    ]
);

// creating a contact failed
if(($response['error']['code'] ?? '') === 'MEMBER_EXISTS_WITH_EMAIL_ADDRESS') {
    // get the contact
    $response = $client->lists()->getContact(
        '00000000-0000-0000-0000-000000000000',
        '00000000-0000-0000-0000-000000000000'
    );

    if (($response['status'] ?? '') === 'UNSUBSCRIBED') {
        // update existing contact
        $client->lists()->updateContact(
            '00000000-0000-0000-0000-000000000000',
            md5('[email protected]'),
            [
                'status' => 'PENDING'
            ]
        );
    }
}

Check out the repo and the docs for all of the remaining routes on GitHub.

Laravel SDK

Now, when it comes to the Email Octopus SDK for Laravel, as you may have guessed, it's basically another wrapper around the PHP version of the SDK, and all of the routes that are available in the PHP SDK are also available in the Laravel one. The Laravel package will allow you to easily interact with the API Client through the use of Facades.

First, we should install the package:

composer require goran-popovic/email-octopus-laravel

Please note that if you are using the Laravel SDK, you don't need to install the PHP SDK separately, since it is already included as a dependency for the Laravel package.

Now that we have installed the package, you can optionally publish the config files with this command:

php artisan vendor:publish --tag="email-octopus-config"

Like I mentioned already in the previous section, make sure to get your Email Octopus API key and add it to your .env file:

EMAIL_OCTOPUS_API_KEY=YOUR_API_KEY

Now, just just need to use the Facade in your file:

use GoranPopovic\EmailOctopus\Facades\EmailOctopus;

and you can perform the same operations as with the PHP SDK through the Facade, like so:

EmailOctopus::lists()->createContact(
    '00000000-0000-0000-0000-000000000000', 
    [
        'email_address' => '[email protected]'
    ]
);

Check out the repo of the Laravel SDK  for further instructions and details.

Conclusion

As I already mentioned, EmailOctopus has worked well for me so far, and I'm pretty satisfied with their service. If you ever decide to try them out for yourself, I hope both SDKs will prove to be useful assets when interacting with the EmailOctopus's API from your PHP applications.

For any bugs and improvements, feel free to create a pull request or open an issue on GitHub.