goran-popovic/email-octopus-laravel

Email Octopus SDK for Laravel

v1.0.1 2024-03-30 19:49 UTC

Requires

• php: ^7.2.5|^8.0
• goran-popovic/email-octopus-php: ^v1.0.1
• guzzlehttp/guzzle: ^7.0.1
• illuminate/support: ^7.0|^8.0|^9.0|^10.0|^11.0

MIT

• Goran Popović

• php
• newsletter
• email
• sdk
• laravel
• campaign
• marketing
• mailing list
• email octopus

README

Email Octopus SDK for Laravel is a PHP API client that allows you to interact with the API provided by Email Octopus. Using the package you can easily subscribe/unsubscribe users to your newsletter, trigger automations and view various data about your campaigns.

Note

This repository contains the code that is most suited to be used with Laravel framework. If you want to use the PHP API client in a framework-agnostic way, check out the goran-popovic/email-octopus-php repository.

PHP Version Support

• >= 7.2.5

Laravel Version Support

• >= 7.29.0

Installation

You can install the package via composer:

composer require goran-popovic/email-octopus-laravel

If you wish to publish the config file to config/email-octopus.php run:

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

Getting Started

API key

Before being able to use the SDK, you would need to create an Email Octopus API key.

.env settings

After creating the key by following the instructions above, edit your .env file and add the API key there:

EMAIL_OCTOPUS_API_KEY=YOUR_API_KEY

Facade

Package will register a Facade that you can use in your app to make API calls, just make sure to include it at the top of the file:

use GoranPopovic\EmailOctopus\Facades\EmailOctopus;

Basic implementation

Then, you can interact with Email Octopus's API like so:

use GoranPopovic\EmailOctopus\Facades\EmailOctopus;

$response = EmailOctopus::lists()->createContact('00000000-0000-0000-0000-000000000000', [
    'email_address' => '[e-mail]', // required
    'fields' => [ // optional
        'FirstName' => 'Goran',
        'LastName' => 'Popović',
    ],
    'tags' => [ // optional
        'lead'
    ],
    'status' => 'SUBSCRIBED', // optional
]);

echo $response['status']; // SUBSCRIBED

Configuration

Other available config settings include the ability to set the base URI of the API, timeout and connect timeout. For most use cases the defaults are just fine, but if you want, you can set those params in either the config file (config/email-octopus) or by using environment variables.

Usage

This wrapper tends to follow the logic and classification found in the official Email Octopus API docs. All the routes, and available params for each route are explained in greater detail in those docs.

All the methods are assigned into 3 main resources:

• Automation Resource
• Campaign Resource
• List Resource

Automation Resource

You can find an ID of the automation you are currently viewing in the dashboard URL, like so: https://emailoctopus.com/automations/<automationId>

start(string $automationId, array $params)

EmailOctopus::automations()->start('00000000-0000-0000-0000-000000000000', [ 
    'list_member_id' => '00000000-0000-0000-0000-000000000000', 
]);

Campaign Resource

You can find an ID of the campaign you are currently viewing in the dashboard URL, like so: https://emailoctopus.com/reports/campaign/<campaignId>

get(string $campaignId)

EmailOctopus::campaigns()->get('00000000-0000-0000-0000-000000000000');

getAll(array $params = [])

EmailOctopus::campaigns()->getAll([
    'limit' => 1, // optional 
    'page' => 2 // optional 
]);

getReportSummary(string $campaignId)

EmailOctopus::campaigns()->getReportSummary('00000000-0000-0000-0000-000000000000');

getReportLinks(string $campaignId)

EmailOctopus::campaigns()->getReportLinks('00000000-0000-0000-0000-000000000000');

getReportBounced(string $campaignId, array $params)

EmailOctopus::campaigns()->getReportBounced('00000000-0000-0000-0000-000000000000', [
    'limit' => 1 // optional 
]);

getReportClicked(string $campaignId, array $params)

EmailOctopus::campaigns()->getReportClicked('00000000-0000-0000-0000-000000000000', [
    'limit' => 1 // optional 
]);

getReportComplained(string $campaignId, array $params)

EmailOctopus::campaigns()->getReportComplained('00000000-0000-0000-0000-000000000000', [
    'limit' => 1 // optional 
]);

getReportOpened(string $campaignId, array $params)

EmailOctopus::campaigns()->getReportOpened('00000000-0000-0000-0000-000000000000', [
    'limit' => 1 // optional 
]);

getReportSent(string $campaignId, array $params)

EmailOctopus::campaigns()->getReportSent('00000000-0000-0000-0000-000000000000', [
    'limit' => 1 // optional 
]);

getReportUnsubscribed(string $campaignId)

EmailOctopus::campaigns()->getReportUnsubscribed('00000000-0000-0000-0000-000000000000');

getReportNotClicked(string $campaignId, array $params)

EmailOctopus::campaigns()->getReportNotClicked('00000000-0000-0000-0000-000000000000', [
    'limit' => 1 // optional 
]);

getReportNotOpened(string $campaignId, array $params)

EmailOctopus::campaigns()->getReportNotOpened('00000000-0000-0000-0000-000000000000', [
    'limit' => 1 // optional 
]);

List Resource

To find the list ID, go to your Email Octopus dashboard, find the Lists tab, select a list by clicking on its title, and when you open a single list simply go to the settings tab and copy the ID from there. Alternatively, you can find an ID of the list or any other resource you are currently viewing in the dashboard URL, like so: https://emailoctopus.com/lists/<listId>

get(string $listId)

EmailOctopus::lists()->get('00000000-0000-0000-0000-000000000000');

getAll(array $params = [])

EmailOctopus::lists()->getAll([
    'limit' => 1, // optional
    'page' => 2 // optional
]);

create(array $params)

EmailOctopus::lists()->create([
    'name' => 'Api test'
]);

update(string $listId, array $params)

EmailOctopus::lists()->update('00000000-0000-0000-0000-000000000000', [
    'name' => 'New name'
]);

delete(string $listId)

EmailOctopus::lists()->delete('00000000-0000-0000-0000-000000000000');

getAllTags(string $listId)

EmailOctopus::lists()->getAllTags('00000000-0000-0000-0000-000000000000');

getContact(string $listId, string $memberId)

EmailOctopus::lists()->getContact(
    '00000000-0000-0000-0000-000000000000', 
    '00000000-0000-0000-0000-000000000000', 
);

getAllContacts(string $listId, array $params = [])

EmailOctopus::lists()->getAllContacts('00000000-0000-0000-0000-000000000000', [
    'limit' => 1, // optional
    'page' => 2 // optional
]);

getSubscribedContacts(string $listId, array $params = [])

EmailOctopus::lists()->getSubscribedContacts('00000000-0000-0000-0000-000000000000', [
    'limit' => 1, // optional
    'page' => 2 // optional
]);

getUnsubscribedContacts(string $listId, array $params = [])

EmailOctopus::lists()->getUnsubscribedContacts('00000000-0000-0000-0000-000000000000', [
    'limit' => 1, // optional
    'page' => 2 // optional
]);

getContactsByTag(string $listId, string $listTag, array $params = [])

EmailOctopus::lists()->getContactsByTag('00000000-0000-0000-0000-000000000000', 'lead', [
    'limit' => 1
]);

createContact(string $listId, array $params)

EmailOctopus::lists()->createContact('00000000-0000-0000-0000-000000000000', [
    'email_address' => '[e-mail]', // required
    'fields' => [ // optional
        'FirstName' => 'Goran',
        'LastName' => 'Popović',
    ],
    'tags' => [ // optional
        'lead'
    ],
    'status' => 'SUBSCRIBED', // optional
]);

updateContact(string $listId, string $memberId, array $params)

Note: For member ID you can either use the ID of the list contact that you can find in the URL in the dashboard: https://emailoctopus.com/lists/<listId>/contacts/<contactId>, or an MD5 hash of the lowercase version of the list contact's email address.

EmailOctopus::lists()->updateContact('00000000-0000-0000-0000-000000000000', md5('[e-mail]'), [
    'email_address' => '[e-mail]', // optional
    'fields' => [ // optional
        'FirstName' => 'New name',
        'LastName' => 'New lastname',
    ],
    'tags' => [ // optional
        'vip' => true,
        'lead' => false
    ],
    'status' => 'UNSUBSCRIBED', // optional
]);

deleteContact(string $listId, string $memberId)

Note: For member ID you can either use the ID of the list contact that you can find in the URL in the dashboard: https://emailoctopus.com/lists/<listId>/contacts/<contactId>, or an MD5 hash of the lowercase version of the list contact's email address.

EmailOctopus::lists()->deleteContact(
    '00000000-0000-0000-0000-000000000000',
    md5('[e-mail]')
);

createField(string $listId, array $params)

EmailOctopus::lists()->createField('00000000-0000-0000-0000-000000000000', [
    'label' => 'What is your hometown?',
    'tag' => 'Hometown',
    'type' => 'TEXT',
    'fallback' => 'Unknown' // optional
]);

updateField(string $listId, string $listFieldTag, array $params)

EmailOctopus::lists()->updateField('00000000-0000-0000-0000-000000000000', 'Hometown', [
    'label' => 'New label',
    'tag' => 'NewTag',
    'fallback' => 'New fallback' // optional
]);

deleteField(string $listId, string $listFieldTag)

EmailOctopus::lists()->deleteField('00000000-0000-0000-0000-000000000000', 'NewTag');

createTag(string $listId, array $params)

EmailOctopus::lists()->createTag('00000000-0000-0000-0000-000000000000', [
    'tag' => 'vip'
]);

updateTag(string $listId, string $listTag, array $params)

EmailOctopus::lists()->updateTag('00000000-0000-0000-0000-000000000000', 'vip', [
    'tag' => 'New Tag Name'
]);

deleteTag(string $listId, string $listTag)

EmailOctopus::lists()->deleteTag('00000000-0000-0000-0000-000000000000', 'New Tag Name');

Changelog

Please see CHANGELOG for more information on what has changed recently.