pion / smart-emailing-v3
Wrapper for SmartEmailing API
Fund package maintenance!
pionl
revolut.me/martinpv7n
Installs: 110 377
Dependents: 0
Suggesters: 0
Security: 0
Stars: 13
Watchers: 7
Forks: 14
Open Issues: 0
Requires
- php: >=7.4
- ext-json: *
- guzzlehttp/guzzle: >=7.5
Requires (Dev)
- phpstan/phpstan: ^1.10.14
- phpstan/phpstan-deprecation-rules: ^1.0.0
- phpstan/phpstan-mockery: ^1.1.0
- phpstan/phpstan-phpunit: ^1.1.1
- phpunit/phpunit: 9.6
- rector/rector: 0.15.1
- slevomat/coding-standard: ~8.0
- symplify/easy-coding-standard: 11.1.20
- vlucas/phpdotenv: ^2.4
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();
or
// 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
- Import contacts
- Import orders
- Ping
- Credentials
- Contactlist
- Customfields
- Contacts
- Contacts in list
- Custom emails
- Emails
- Newsletter
- Webhooks
- (DEPRECATED) E-shops
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;
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(); $data = $response->data(); $customFieldId = $data->id;
Search / List
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 inMetaDataInterface
)
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.
Copyright (c) 2016 - 2022 Martin Kluska and contributors