EmailOctopus SDKs for PHP and Laravel
Tags: laravel, php, api, newsletter
Published: 2024-03-05 00:28:41

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.

<br>
<h2 class="subheading">PHP SDK</h2>
<br>

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

<br>

```bash
composer require goran-popovic/email-octopus-php
```

<br>

Next, in order to get started you would need to create an <a title="Email Octopus API key" href="https://help.emailoctopus.com/article/165-how-to-create-and-delete-api-keys" target="_blank" rel="noopener noreferrer">Email Octopus API key</a> by following the instructions from their knowledge base.

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

<br>

```bash
EMAIL_OCTOPUS_API_KEY=YOUR_API_KEY
```

<br>

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

<br>

```php
$apiKey = getenv('EMAIL_OCTOPUS_API_KEY');

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

<br>

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:

<br>

```php
$client->lists()->createContact(
    '00000000-0000-0000-0000-000000000000',
    [
        'email_address' => 'goran.popovic@geoligard.com'
    ]
);
```

<br>

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:


<a title="List ID" href="https://geoligard.com/storage/posts/February2024/list-settings.png" target="_blank"><img title="List ID" src="https://geoligard.com/storage/posts/February2024/list-settings.png" alt="List ID" width="100%" height="auto"></a>


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 the contact first, and if the contact exists, update it, and if it doesn't exist, create a new one:

<br>

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

if(isset($response['error'])) { // contact doesn't exist
    // create contact
    $response = $client->lists()->createContact(
        '00000000-0000-0000-0000-000000000000',
        [
            'email_address' => 'goran.popovic@geoligard.com'
        ]
    );
} else {
    // update existing contact
    $client->lists()->updateContact(
        '00000000-0000-0000-0000-000000000000',
        md5('goran.popovic@geoligard.com'),
        [
            'status' => 'SUBSCRIBED'
        ]
    );
}
```

<br>

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

<br>

```php
$response = $client->lists()->createContact(
    '00000000-0000-0000-0000-000000000000',
    [
        'email_address' => 'goran.popovic@geoligard.com'
    ]
);

// creating a contact failed
if(($response['error']['code'] ?? '') === 'MEMBER_EXISTS_WITH_EMAIL_ADDRESS') {
    // update existing contact
    $client->lists()->updateContact(
        '00000000-0000-0000-0000-000000000000',
        md5('goran.popovic@geoligard.com'),
        [
            'status' => 'SUBSCRIBED'
        ]
    );
}
```

<br>

Check out the repo and the docs for all of the remaining routes on <a title="PHP SDK" href="https://github.com/goran-popovic/email-octopus-php" target="_blank" rel="noopener noreferrer nofollow">GitHub</a>.

<br>
<h2 class="subheading">Laravel SDK</h2>
<br>

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:

<br>

```bash
composer require goran-popovic/email-octopus-laravel
```

<br>

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:

<br>

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

<br>

Like I mentioned already in the previous section, make sure to get your <a title="Email Octopus API key" href="https://help.emailoctopus.com/article/165-how-to-create-and-delete-api-keys" target="_blank" rel="noopener noreferrer">Email Octopus API key</a> and add it to your `.env` file:

<br>

```bash
EMAIL_OCTOPUS_API_KEY=YOUR_API_KEY
```

<br>

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

<br>

```php
use GoranPopovic\EmailOctopus\Facades\EmailOctopus;
```

<br>

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

<br>

```php
EmailOctopus::lists()->createContact(
    '00000000-0000-0000-0000-000000000000', 
    [
        'email_address' => 'goran.popovic@geoligard.com'
    ]
);
```

<br>

Check out the repo of the <a title="Laravel SDK" href="https://github.com/goran-popovic/email-octopus-laravel" target="_blank" rel="noopener noreferrer nofollow">Laravel SDK</a> for further instructions and details.

<br>
<h2 class="subheading">Conclusion</h2>
<br>

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.

---

_Enjoyed the article? Consider subscribing to my <a href="https://geoligard.com/newsletter" target="_blank">newsletter</a> for future updates._

---

_Originally published at <a href="https://geoligard.com/emailoctopus-sdks-for-php-and-laravel" target="_blank">geoligard.com</a>._