README

API wrapper for Smart emailing API.

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

Installation

Requirements

This package requires PHP 7.4 and higher.

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->importRequest()->addContact(new Contact('test@test.cz'))->send();

// Creates a new instance
$import = $api->importRequest();
$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 sending any request you can catch the error exception RequestException.

use SmartEmailing\v3\Exceptions\RequestException;

try {
    $api->ping();
} 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 contacts

The import holds 2 main data points:

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

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')

Import orders

The import holds 2 main data points:

Settings $import->settings()->setSkipInvalidOrders(true)
Orders $import->newOrder() : Order, $import->orders() : array and $import->addOrder($order) : self

Example of usage is above.

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\Models\CustomFieldDefinition;

...
// Create the new customField and send the request now.
$customField = new CustomFieldDefinition('test', CustomFieldDefinition::TEXT);
$data = $api->customFields()->create($customField);

 // Get the customField in data
$customFieldId = $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();
$data = $response->data();
$customFieldId = $data->id;

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 Models\CustomFieldDefinition by calling $response->data().

Response

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

Get a list without advanced search

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

$data = $api->customFields()->list();

/** @var \SmartEmailing\v3\Models\CustomFieldDefinition $customField */
foreach ($data as $customField) {
    echo $customField->id;
    echo $customField->name;
    echo $customField->type;
}

Advanced search - filter/sort/etc

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

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

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

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)

Get by name

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()->getByName('name')) {
    return $customField->id;
} else {
    throw new Exception('Not found!', 404);
}

Send / Transactional emails

The implementation of API call send/transactional-emails-bulk: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_transactional_emails

Full transactional email example

$transactionEmail = $api->transactionalEmailsRequest();

$credentials = new SenderCredentials();
$credentials->setFrom('from@example.com');
$credentials->setReplyTo('to@example.com');
$credentials->setSenderName('Jean-Luc Picard');

$recipient = new Recipient();
$recipient->setEmailAddress('kirk@example.com');

$replace1 = new Replace();
$replace1->setKey('key1');
$replace1->setContent('content1');

$replace2 = new Replace();
$replace2->setKey('key2');
$replace2->setContent('content2');

$templateVariable = new TemplateVariable();
$templateVariable->setCustomData([
    'foo' => 'bar',
    'products' => [
        ['name' => 'prod1', 'desc' => 'desc1'],
        ['name' => 'prod1', 'desc' => 'desc2']
    ]
]);

$attachment1 = new Attachment();
$attachment1->setContentType('image/png');
$attachment1->setFileName('picture.png');
$attachment1->setDataBase64('data1');

$attachment2 = new Attachment();
$attachment2->setContentType('image/gif');
$attachment2->setFileName('sun.gif');
$attachment2->setDataBase64('data2');

$task = new Task();
$task->setRecipient($recipient);
$task->addReplace($replace1);
$task->addReplace($replace2);
$task->setTemplateVariables($templateVariable);
$task->addAttachment($attachment1);
$task->addAttachment($attachment2);

$messageContents = new MessageContents();
$messageContents->setTextBody('text_body');
$messageContents->setHtmlBody('html_body');
$messageContents->setSubject('subject');

$transactionEmail->setTag('tag_tag');
$transactionEmail->setEmailId(5);
$transactionEmail->setSenderCredentials($credentials);
$transactionEmail->addTask($task);
$transactionEmail->setMessageContents($messageContents);

$transactionEmail->send();

Send / Bulk custom emails

The implementation of API call send/custom-emails-bulk: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_emails

Full custom email example

$transactionEmail = $api->customEmailsBulkRequest();

$credentials = new SenderCredentials();
$credentials->setFrom('from@example.com');
$credentials->setReplyTo('to@example.com');
$credentials->setSenderName('Jean-Luc Picard');

$recipient = new Recipient();
$recipient->setEmailAddress('kirk@example.com');

$replace1 = new Replace();
$replace1->setKey('key1');
$replace1->setContent('content1');

$replace2 = new Replace();
$replace2->setKey('key2');
$replace2->setContent('content2');

$templateVariable = new TemplateVariable();
$templateVariable->setCustomData([
    'foo' => 'bar',
    'products' => [
        ['name' => 'prod1', 'desc' => 'desc1'],
        ['name' => 'prod1', 'desc' => 'desc2']
    ]
]);

$task = new Task();
$task->setRecipient($recipient);
$task->addReplace($replace1);
$task->addReplace($replace2);
$task->setTemplateVariables($templateVariable);

$transactionEmail->setTag('tag_tag');
$transactionEmail->setEmailId(5);
$transactionEmail->setSenderCredentials($credentials);
$transactionEmail->addTask($task);

$transactionEmail->send();

Send / Bulk custom sms

The implementation of API call send/custom-sms-bulk: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_SMS

Full send sms example

$bulkCustomSms = $api->customSmsBulkRequest();

$recipient = new Recipient();
$recipient->setEmailAddress('kirk@example.com');
$recipient->setCellphone('+420777888777');

$replace1 = new Replace();
$replace1->setKey('key1');
$replace1->setContent('content1');

$replace2 = new Replace();
$replace2->setKey('key2');
$replace2->setContent('content2');

$task = new Task();
$task->setRecipient($recipient);
$task->addReplace($replace1);
$task->addReplace($replace2);

$bulkCustomSms->setTag('tag_tag');
$bulkCustomSms->setSmsId(5);
$bulkCustomSms->addTask($task);

$bulkCustomSms->send();

Upgrading

See UPGRADE.md for how to upgrade to newer versions.

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.

pion / smart-emailing-v3

Maintainers

Details