php-omnisend

A library for interacting with the Omnisend API.

This library is in early release and is pending unit tests.

Table of Contents

• Installation
• Usage
  • Creating a Client
  • Contacts
    • Create Contact
    • Update Contact
    • Retrieve Contact
    • List Contacts
    • Subscribe Contact
    • Unsubscribe Contact
  • Events
    • List Events
    • Retrieve Event
    • Trigger Event
  • Misc Calls
• Laravel Integration
  • Configuration
  • Job Handlers
    • CreateContact
    • UpdateContact
    • TriggerEvent

Installation

composer require balfour/php-omnisend

Usage

Please see https://api-docs.omnisend.com/v3 for full API documentation.

Creating a Client

use GuzzleHttp\Client;
use Balfour\Omnisend\Omnisend;

$client = new Client();
$omnisend = new Omnisend($client, 'your-api-key');

Contacts

Create Contact

use Carbon\Carbon;
use Balfour\Omnisend\ContactGender;
use Balfour\Omnisend\ContactStatus;

$response = $omnisend->createContact([
    'email' => '[email protected]',
    'firstName' => 'John',
    'lastName' => 'Doe',
    'tags' => [
        'source: Test',
    ],
    'gender' => ContactGender::MALE,
    'phone' => '+27721111111',
    'birthdate' => '1987-03-28',
    'customProperties' => [
        'group' => 'ADMIN',
    ],
]);

// you can also pass an implementation of ContactInterface instead of an array
// of attributes
// eg: assuming $contact is a model which implements ContactInterface
$response = $omnisend->createContact($contact);

// specifying opt-in status & optional params
$response = $omnisend->createContact(
    [
        'email' => '[email protected]',
        'firstName' => 'John',
        'lastName' => 'Doe',
        'tags' => [
            'source: Test',
        ],
        'gender' => ContactGender::MALE,
        'phone' => '+27721111111',
        'birthdate' => '1987-03-28',
        'customProperties' => [
            'group' => 'ADMIN',
        ],
    ],
    ContactStatus::UNSUBSCRIBED,
    Carbon::now(), // status date
    true, // send welcome email
    '127.0.0.1', // opt-in ip address (ipv4 or ipv6)
    Carbon::now(), // opt-in date & time
);

Update Contact

$response = $omnisend->updateContact('5d5be5635c3762bd644e947c', [
    'firstName' => 'John',
    'lastName' => 'Doe',
]);

// you can also pass an implementation of ContactInterface instead of an array
// of attributes
// eg: assuming $contact is a model which implements ContactInterface
$response = $omnisend->updateContact('5d5be5635c3762bd644e947c', $contact);

// update contact using email address as identifier
$response = $omnisend->updateContactByEmail('[email protected]', [
    'firstName' => 'John',
    'lastName' => 'Doe',
]);

Retrieve Contact

$response = $omnisend->getContact('5d5be5635c3762bd644e947c');

List Contacts

use Balfour\Omnisend\ContactStatus;

$response = $omnisend->listContacts();

// list contacts from offset with limit
$response = $omnisend->listContacts(
    50, // starting from offset 50
    100 // limit to 100 results
);

// list contacts by status
$response = $omnisend->listContactsByStatus(ContactStatus::SUBSCRIBED);

Subscribe Contact

$response = $omnisend->subscribeContact('5d5be5635c3762bd644e947c');

// or via email address
$response = $omnisend->subscribeContactByEmail('[email protected]');

Unsubscribe Contact

$response = $omnisend->unsubscribeContact('5d5be5635c3762bd644e947c');

// or via email address
$response = $omnisend->unsubscribeContactByEmail('[email protected]');

Events

List Events

$response = $omnisend->listEvents();

Retrieve Event

``php $response = $omnisend->getEvent('5d5cf4d98653ed49cd7f1bd2');

// you can also retrieve an event by name // the function will return 'null' if no matching event is found $response = $omnisend->getEventByName('Payment Complete'); ``

Trigger Event

use Balfour\Omnisend\Event;

$omnisend->triggerEvent(
    '5d5cf4d98653ed49cd7f1bd2',
    '[email protected]',
    [
        'payment_method' => 'CREDIT CARD',
        'amount' => 'R1200.00',
    ]
);

// you can also pass in an implementation of EventInterface
$paymentCompleteEvent = new Event(
    '5d5cf4d98653ed49cd7f1bd2',
    [
        'payment_method' => 'CREDIT CARD',
        'amount' => 'R1200.00',
    ]
);

$omnisend->triggerEvent($paymentCompleteEvent, '[email protected]');

Misc Calls

For any other API calls which don't have class functions, you can call the following methods directly on the client.

// examples:
$omnisend->get('products');
$omnisend->get('products', ['sort' => 'createdAt']);

$omnisend->post('products', [
    'productId' => '1234',
    'title' => 'My Product',
    // .....
]);

$omnisend->put('products', [
    'productId' => '1234',
    'title' => 'My Product',
    // .....
]);

$omnisend->delete('products/1234');

Laravel Integration

This package comes bundled with a Laravel ServiceProvider & utility classes for easy integration into a Laravel project.

use Balfour\Omnisend\Laravel\Event;
use Balfour\Omnisend\Laravel\NamedEvent;
use Balfour\Omnisend\Omnisend;

// resolving client from ioc container
$omnisend = app(Omnisend::class);

// triggering an event
$paymentCompleteEvent = new Event(
    '5d5cf4d98653ed49cd7f1bd2',
    [
        'payment_method' => 'CREDIT CARD',
        'amount' => 'R1200.00',
    ]
);
$paymentCompleteEvent->fire();

// queue an event
// this will use the configured queue (omnisend by default)
$paymentCompleteEvent->enqueue('[email protected]');

// the queue name can be overridden
$paymentCompleteEvent->enqueue('[email protected]', 'my_queue');

// the laravel integration also comes with a NamedEvent class, where can event
// can be triggered by name instead of id
// the event id is resolved at trigger time from the name, and is cached for subsequent
// triggers
$paymentCompleteEvent = new NamedEvent(
    'Payment Complete',
    [
        'payment_method' => 'CREDIT CARD',
        'amount' => 'R1200.00',
    ]
);
$paymentCompleteEvent->fire();

Configuration

The config can be published using php artisan vendor:publish.

The following environment variables are supported:

OMNISEND_ENABLED - Enable or disable Omnisend integration (defaults to false)

OMNISEND_API_KEY - Your Omnisend API key

OMNISEND_QUEUE - The queue on which jobs will be processed (defaults to omnisend)

OMNISEND_SEND_WELCOME_EMAIL - If true, a welcome email will be sent to a contact upon creation (defaults to false)

OMNISEND_DEFAULT_CONTACT_STATUS - The default status when a contact is created. (defaults to subscribed)

Job Handlers

The following job handlers are included:

CreateContact

use Balfour\Omnisend\ContactStatus;
use Balfour\Omnisend\Laravel\Jobs\CreateContact;
use Carbon\Carbon;

// eg: assuming $contact is a model which implements ContactInterface
CreateContact::enqueue($contact);

// or
CreateContact::enqueue(
    $contact,
    ContactStatus::SUBSCRIBED,
    true, // send welcome email
    '127.0.0.1', // opt-in ip
    Carbon::now() // opt-in date
);

UpdateContact

use Balfour\Omnisend\Laravel\Jobs\UpdateContact;

// eg: assuming $contact is a model which implements ContactInterface
UpdateContact::enqueue($contact);

TriggerEvent

use Balfour\Omnisend\Laravel\Event;
use Balfour\Omnisend\Laravel\Jobs\TriggerEvent;

$paymentCompleteEvent = new Event(
    '5d5cf4d98653ed49cd7f1bd2',
    [
        'payment_method' => 'CREDIT CARD',
        'amount' => 'R1200.00',
    ]
);

TriggerEvent::enqueue($event, '[email protected]');