jan-suchanek/smart-emailing-v3

Wrapper for SmartEmailing API

v0.3.1 2021-02-03 08:54 UTC

Requires

• php: >=7.2
• ext-json: *
• guzzlehttp/guzzle: >=6.2

Requires (Dev)

• phpunit/phpunit: ^7.5
• vlucas/phpdotenv: ^2.4

MIT

• Martin Kluska

README

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

Requirements

This package requires PHP 7.3 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->import()->addContact(new Contact('[e-mail]'))->send();

or

// Creates a new instance
$import = $api->import();
$contact = new Contact('[e-mail]');
$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('[e-mail]');
$contact2->setName('Test');

// Create new contact that will be inserted in the contact list
$import->newContact('[e-mail]')->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

• Import$api->import() or new Import($api)
• Ping $api->ping() or new Ping($api)
• Credentials $api->credentials() or new Credentials($api)
• Contactlist Retrieve list $api->contactlist()->lists() or detail $api->contactlist()->get($id) - wrapper for 2 Request objects
• CustomFields - exists: A quick way how to get custom field by it's name. $api->customFields()->exists('name') : CustomField|bool
• Customfields - create create request $api->customFields()->createRequest() or send create request $api->customFields()->create(new CustomField('test', CustomField::TEXT))
• Customfields - search / list search request $api->customFields()->searchRequest($page = 1, $limit = 100) or send search request $api->customFields()->search($page = 1, $limit = 100)
• Customfields - rest Similar concept as contact-list - already started
• Customfiels options
• Contacts Similar concept as contact-list
• Contacts in list Similar concept as contact-list
• Custom emails
• Emails
• Newsletter
• Webhooks

Advanced docs

Import

The import holds 2 main data points:

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

Example of usage is above.

Contact

The import holds 3 main data points:

1. All data accessible via public properties. Fluent set method has basic validation and date convert logic
2. CustomFields $contact->customFields() for adding new fields
3. 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;

or

$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);
}

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 = new TransactionalEmails($api);

$credentials = new SenderCredentials();
$credentials->setFrom('[e-mail]');
$credentials->setReplyTo('[e-mail]');
$credentials->setSenderName('Jean-Luc Picard');

$recipient = new Recipient();
$recipient->setEmailAddress('[e-mail]');

$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 transactional email example

$transactionEmail = new BulkCustomEmails($api);

$credentials = new SenderCredentials();
$credentials->setFrom('[e-mail]');
$credentials->setReplyTo('[e-mail]');
$credentials->setSenderName('Jean-Luc Picard');

$recipient = new Recipient();
$recipient->setEmailAddress('[e-mail]');

$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();

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.

Copyright (c) 2016 Martin Kluska