PHPackages pion/smart-emailing-v3 - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. pion/smart-emailing-v3 ActiveLibrary[API Development](/categories/api) pion/smart-emailing-v3 ====================== Wrapper for SmartEmailing API v1.0.0(2y ago)14176.8k↓26.1%16[1 PRs](https://github.com/pionl/smart-emailing-v3/pulls)MITPHPPHP >=7.4CI failing Since Feb 17Pushed 2y ago6 watchersCompare [ Source](https://github.com/pionl/smart-emailing-v3)[ Packagist](https://packagist.org/packages/pion/smart-emailing-v3)[ Fund](https://revolut.me/martinpv7n)[ GitHub Sponsors](https://github.com/pionl)[ RSS](/packages/pion-smart-emailing-v3/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (10)Versions (18)Used By (0) Smart Emailing API v3 ===================== [](#smart-emailing-api-v3) API wrapper for [Smart emailing](http://smartemailing.cz) API. [![img](https://camo.githubusercontent.com/ca93034b4d57a7539be7e1d840a3ba84a75d450e60081aa65e2dd1a6aae842fb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d382d626c7565)](https://camo.githubusercontent.com/ca93034b4d57a7539be7e1d840a3ba84a75d450e60081aa65e2dd1a6aae842fb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d382d626c7565)[![php](https://camo.githubusercontent.com/6de57f8cc9a20d0244954a014aa7a0929f8881f584a783ee6ed34c7ceca5bcd4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d372e34253230746f253230382e322d423042334436)](https://camo.githubusercontent.com/6de57f8cc9a20d0244954a014aa7a0929f8881f584a783ee6ed34c7ceca5bcd4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d372e34253230746f253230382e322d423042334436)[![coverage](https://camo.githubusercontent.com/3db42f099875098c9df86dd49a73fe842255c397ca3be010d2ac8486d8d3d209/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f75726c3d68747470733a2f2f676973742e67697468756275736572636f6e74656e742e636f6d2f70696f6e6c2f61636232666439323938633166616134363163326136306235346236373365642f7261772f636f7665726167652e6a736f6e)](https://camo.githubusercontent.com/3db42f099875098c9df86dd49a73fe842255c397ca3be010d2ac8486d8d3d209/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f75726c3d68747470733a2f2f676973742e67697468756275736572636f6e74656e742e636f6d2f70696f6e6c2f61636232666439323938633166616134363163326136306235346236373365642f7261772f636f7665726167652e6a736f6e)[![CI](https://github.com/pionl/smart-emailing-v3/actions/workflows/check.yml/badge.svg)](https://github.com/pionl/smart-emailing-v3/actions/workflows/check.yml)[![Total Downloads](https://camo.githubusercontent.com/fd6009c732f171918663969567f2cce77808f1e5f1c607d1227b6ee75149ef4d/68747470733a2f2f706f7365722e707567782e6f72672f70696f6e2f736d6172742d656d61696c696e672d76332f646f776e6c6f6164733f666f726d61743d666c6174)](https://packagist.org/packages/pion/smart-emailing-v3)[![Latest Stable Version](https://camo.githubusercontent.com/fdc37b35dd04e18413af3285ef99c351b5fd22fd12517383d787313165d44f13/68747470733a2f2f706f7365722e707567782e6f72672f70696f6e2f736d6172742d656d61696c696e672d76332f762f737461626c653f666f726d61743d666c6174)](https://packagist.org/packages/pion/smart-emailing-v3)[![Latest Unstable Version](https://camo.githubusercontent.com/34a082a66b53fa555ecc5ad498af2bb33dcb753e6fe48294c44af011fbec76e3/68747470733a2f2f706f7365722e707567782e6f72672f70696f6e2f736d6172742d656d61696c696e672d76332f762f756e737461626c653f666f726d61743d666c6174)](https://packagist.org/packages/pion/smart-emailing-v3) - [Installation](#installation) - [Usage](#usage) - [Supports](#supports) - [Advanced docs](#advanced-docs) - [Contribution or overriding](#contribution-or-overriding) - [Upgrading](#upgrading) - [Copyright and License](#copyright-and-license) - [Smart emailing API](https://app.smartemailing.cz/docs/api/v3/index.html) Installation ------------ [](#installation) **Requirements** This package requires PHP 7.4 and higher. **Install via composer** ``` composer require pion/smart-emailing-v3 ``` Usage ----- [](#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 [](#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 -------- [](#supports) - [Import contacts](https://app.smartemailing.cz/docs/api/v3/index.html#api-Import-Import_contacts) - [Import orders](https://app.smartemailing.cz/docs/api/v3/index.html#api-Import-Import_orders) - [Ping](https://app.smartemailing.cz/docs/api/v3/index.html#api-Tests-Aliveness_test) - [Credentials](https://app.smartemailing.cz/docs/api/v3/index.html#api-Tests-Login_test_with_GET) - [Contactlist](https://app.smartemailing.cz/docs/api/v3/index.html#api-Contactlists-Get_Contactlists) - [Customfields](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields) - [Customfields - create](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields) - [Customfields - search / list](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields) - [Customfields - rest](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields) - [Customfields - options](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfield_Options) - [Contacts](https://app.smartemailing.cz/docs/api/v3/index.html#api-Contacts) - [Contacts in list](https://app.smartemailing.cz/docs/api/v3/index.html#api-Contacts_in_lists) - [Custom emails](https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_emails) - [Emails](https://app.smartemailing.cz/docs/api/v3/index.html#api-Emails) - [Newsletter](https://app.smartemailing.cz/docs/api/v3/index.html#api-Newsletter) - [Webhooks](https://app.smartemailing.cz/docs/api/v3/index.html#api-Webhooks) - (DEPRECATED) [E-shops](https://app.smartemailing.cz/docs/api/v3/index.html#api-E_shops) Advanced docs ------------- [](#advanced-docs) Import contacts --------------- [](#import-contacts) The import holds 2 main data points: 1. Settings `$import->settings()->setUpdate(true)` 2. Contacts `$import->newContact() : Contact`, `$import->contacts() : array` and `$import->addContact($contact) : self` Example of usage is above. ### [Contact](./src/Models/Contact.php) [](#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](./src/Models/Holder/CustomFields.php) and [ContactLists](./src/Models/Holder/ContactLists.php) [](#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 ------------- [](#import-orders) The import holds 2 main data points: 1. Settings `$import->settings()->setSkipInvalidOrders(true)` 2. Orders `$import->newOrder() : Order`, `$import->orders() : array` and `$import->addOrder($order) : self` Example of usage is above. CustomFields ------------ [](#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 [](#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 [](#search--list) [API DOCS](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields-Get_Customfields) 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 [](#response) - data() returns an array `Models\CustomFieldDefinition` - meta() returns a `stdClass` with properties (defined in `MetaDataInterface`) #### Get a list without advanced search [](#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 [](#advanced-search---filtersortetc) ``` $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 [](#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) [](#expandbystring--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) [](#selectstring--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) [](#sortbystring--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) [](#setpageint--page) Sets the current page ###### limit(int : $limit) [](#limitint--limit) Sets the limit of result in single query ###### filter() [](#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 [](#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 --------------------------- [](#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](https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_transactional_emails) ### Full transactional email example [](#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 ------------------------- [](#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](https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_emails) ### Full custom email example [](#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 ---------------------- [](#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](https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_SMS) ### Full send sms example [](#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 --------- [](#upgrading) See [UPGRADE.md](UPGRADE.md) for how to upgrade to newer versions. Contribution or overriding -------------------------- [](#contribution-or-overriding) See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute changes. All contributions are welcome. Copyright and License --------------------- [](#copyright-and-license) [smart-emailing-v3](https://github.com/pionl/smart-emailing-v3)was written by [Martin Kluska](http://kluska.cz) and is released under the [MIT License](LICENSE.md). Copyright (c) 2016 - 2022 Martin Kluska and contributors ### Health Score 43 — FairBetter than 91% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity44 Moderate usage in the ecosystem Community21 Small or concentrated contributor base Maturity72 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~153 days Recently: every ~107 days Total 17 Last Release 920d ago Major Versions v0.4.1 → v1.0.0-rc2023-07-04 PHP version history (3 changes)v0.1.0PHP >=5.5 v0.2.0PHP >=7.3 v1.0.0-rcPHP >=7.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/ad0f2a11e630f5f386cb8544d42f0c56c2b89258172dae581a33dddcc5de1d83?d=identicon)[pionl](/maintainers/pionl) --- Top Contributors [![MartinMystikJonas](https://avatars.githubusercontent.com/u/2094752?v=4)](https://github.com/MartinMystikJonas "MartinMystikJonas (14 commits)")[![pionl](https://avatars.githubusercontent.com/u/1878831?v=4)](https://github.com/pionl "pionl (11 commits)")[![stanislav-janu](https://avatars.githubusercontent.com/u/5769861?v=4)](https://github.com/stanislav-janu "stanislav-janu (5 commits)")[![keltuo](https://avatars.githubusercontent.com/u/2955345?v=4)](https://github.com/keltuo "keltuo (2 commits)")[![inDeev](https://avatars.githubusercontent.com/u/33215381?v=4)](https://github.com/inDeev "inDeev (2 commits)")[![kubec](https://avatars.githubusercontent.com/u/6186837?v=4)](https://github.com/kubec "kubec (1 commits)")[![PavelJurasek](https://avatars.githubusercontent.com/u/1270132?v=4)](https://github.com/PavelJurasek "PavelJurasek (1 commits)")[![james-fruhbauer](https://avatars.githubusercontent.com/u/18005378?v=4)](https://github.com/james-fruhbauer "james-fruhbauer (1 commits)") --- Tags api-wrapperphpphp-library ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Rector Code StyleECS Type Coverage Yes ### Embed Badge ![Health badge](/badges/pion-smart-emailing-v3/health.svg) ``` [![Health](https://phpackages.com/badges/pion-smart-emailing-v3/health.svg)](https://phpackages.com/packages/pion-smart-emailing-v3) ``` ### Alternatives [tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3731.2M42](/packages/tencentcloud-tencentcloud-sdk-php)[convertkit/convertkitapi Kit PHP SDK for the Kit API 2167.1k1](/packages/convertkit-convertkitapi)[mapado/rest-client-sdk Rest Client SDK for hydra API 1125.9k2](/packages/mapado-rest-client-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)