Smart Emailing API v3

API wrapper for Smart emailing API. Currenlty in development.

Installation
Usage
Supports
Advanced docs
Changelog
Contribution or overriding
Copyright and License
Smart emailing API

Installation

Install via composer

composer require pion/smart-emailing-v3

Usage

Create an Api instance with your username and apiKey.

use SmartEmailing\v3\Api;

...
$api = new Api('username', 'api-key');

then use the $api with desired method/component.

// Creates a new instance
$api->import()->addContact(new Contact('test@test.cz'))->send();

// Creates a new instance
$import = $api->import();
$contact = new Contact('test@test.cz');
$contact->setName('Martin')->setNameDay('2017-12-11 11:11:11');
$import->addContact($contact);

// Create new contact that will be inserted in the contact list
$contact2 = $import->newContact('test2@test.cz');
$contact2->setName('Test');

// Create new contact that will be inserted in the contact list
$import->newContact('test3@test.cz')->setName('Test');
$import->send();

Error handling

When using the send() method in any request class you can catch the error exception RequestException.

use SmartEmailing\v3\Exceptions\RequestException;

try {
    $api->ping()->send();
} catch (RequestException $exception) {
    $exception->response(); // to get the real response, will hold status and message (also data if provided)
    $exception->request(); // Can be null if the request was 200/201 but API returned error status text
}

Supports

Advanced docs

Import

The import holds 2 main data points:

Settings $import->settings()->setUpdate(true)
Contacts $import->newContact() : Contact, $import->contacts() : array and $import->addContact() : $this

Example of usage is above.

Contact

The import holds 3 main data points:

All data accessible via public properties. Fluent set method has basic validation and date convert logic
CustomFields $contact->customFields() for adding new fields
ContactLists $contact->contactLists() for adding new contact list

See source code for all methods/properties that you can use

CustomFields and ContactLists

Uses a data holder with create/add/get/isEmpty/toArray/jsonSerialize methods.

$field = $contact->customFields()->create(12, 'test')
$list = $contact->contactLists()->create(12, 'confirmed')

CustomFields

The customFields uses a wrapper for each request related to custom-fields. To create a new instance call $api->customFields(). On this object you can create any request that is currently implemented. See below.

Create

Quick way that will create request with required customField

use SmartEmailing\v3\Request\CustomFields\CustomField;
use SmartEmailing\v3\Request\CustomFields\Create\Response;

...
// Create the new customField and send the request now.
$response = $api->customFields()->create(new CustomField('test', CustomField::TEXT));
    
 // Get the customField in data
$customFieldId = $response->data()->id;

$request = $api->customFields()->createRequest(); // You can pass the customField object

// Setup customField
$customField = new CustomField();
$request->setCustomField($customField);

// Setup data
$customField->setType(CustomField::RADIO)->setName('test');

// Send the request
$response = $request->send();

Search / List

API DOCS

Enables searching threw the custom fields with a filter/sort support. Results are limited by 100 per page. The response returns meta data (MetaDataInterface) and an array of CustomField\CustomField by calling $response->data().

Response

data() returns an array CustomField\CustomField
meta() returns a stdClass with properties (defined in MetaDataInterface)

Get a list without advanced setup

Creates a search request and setups only $page or $limit. The full response from api with customfield_options_url or

$response = $api->customFields()->search($page = 1);

/** @var \SmartEmailing\v3\Request\CustomFields\CustomField $customField */
foreach ($response->data() as $customField) {
    echo $customField->id;
    echo $customField->name;
    echo $customField->type;
}

Advanced setup - filter/sort/etc

$request = $api->customFields()->searchRequest(1);

// Search by name
$request->filter()->byName('test');
$request->sortBy('name');

// Send the request
$response = $request->send();

Request methods

Getters are via public property
- page
- limit
- select
- expand
- sort
Fluent Setters (with a validation) - more below.
filter() returns a Filters setup - more below

expandBy(string : $expand)

Using this parameter, "customfield_options_url" property will be replaced by "customfield_options" contianing expanded data. See examples below For more information see "/customfield-options" endpoint.

Allowed values: "customfield_options"

select(string : $select)

Comma separated list of properties to select. eg. "?select=id,name" If not provided, all fields are selected.

Allowed values: "id", "name", "type"

sortBy(string : $sort)

Comma separated list of sorting keys from left side. Prepend "-" to any key for desc direction, eg. "?sort=type,-name"

Allowed values: "id", "name", "type"

setPage(int : $page)

Sets the current page

limit(int : $limit)

Sets the limit of result in single query

filter()

Allows filtering custom fields with multiple filter conditions.

Getters are via public property
- name
- type
- id
Fluent Setters (with a validation)
- byName($value)
- byType($value)
- byId($value)

Exists

Runs a search query with name filter and checks if the given name is found in customFields. Returns false or the CustomFields\CustomField. Uses send logic (throws RequestException).

// Can throw RequestException - uses send.
if ($customField = $api->customFields()->exists('name')) {
    return $customField->id;
} else {
    throw new Exception('Not found!', 404);
}

Changelog

0.1.8

Added purposes for contacts.

0.1.7

Fix incorrect namespace for confirmation request.

0.1.6

Added confirmation request to import settings.

0.1.5

Removed deprecated API usage in Contact.php: addContactList and newContactList

0.1.4

CustomFields can be imported only once (unique by id)

0.1.3

Added automatic chunk send for contact import - when number of contacts exceeds 500, the send() method will send multiple request (chunk's the contact array)

0.1.2

Added exists custom field request. A quick way how to get custom field by it's name. $api->customFields()->exists('name') : CustomField|bool
Contacts list allows only unique id's (when already added ignores the value)

0.1.1

Removed deprecated methods for Import\Contact\CustomField (newCustomField, setCustomFields, addCustomField)
Added createValue to CustomFields\CustomField to enable quick creating of CustomField for import.
Moved the CustomField Create request and response to its own namespace SmartEmailing\v3\Request\CustomFields\Create and renamed to only Request class
Changed the JSON structure from array to stdClass. Update all the json() usage
Added search request for custom fields

0.1

Added Custom-fields create request

Contribution or overriding

See CONTRIBUTING.md for how to contribute changes. All contributions are welcome.

Copyright and License

smart-emailing-v3 was written by Martin Kluska and is released under the MIT License.

adamtyron / smart-emailing-v3