{"id":16458483,"url":"https://github.com/pionl/smart-emailing-v3","last_synced_at":"2025-09-13T07:14:01.766Z","repository":{"id":17440616,"uuid":"81979957","full_name":"pionl/smart-emailing-v3","owner":"pionl","description":"Wrapper for SmartEmailing API v3 version in PHP","archived":false,"fork":false,"pushed_at":"2024-04-11T09:59:20.000Z","size":265,"stargazers_count":13,"open_issues_count":0,"forks_count":16,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-17T22:08:01.750Z","etag":null,"topics":["api-wrapper","php","php-library"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pionl.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-02-14T19:14:41.000Z","updated_at":"2024-07-13T12:45:03.000Z","dependencies_parsed_at":"2023-11-10T14:13:33.894Z","dependency_job_id":"87363105-9894-4823-ad48-aa47c885ef66","html_url":"https://github.com/pionl/smart-emailing-v3","commit_stats":{"total_commits":51,"total_committers":9,"mean_commits":5.666666666666667,"dds":0.2941176470588235,"last_synced_commit":"6fd7282eb58751427b08dfde6d5d813ae4a5c80c"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pionl%2Fsmart-emailing-v3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pionl%2Fsmart-emailing-v3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pionl%2Fsmart-emailing-v3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pionl%2Fsmart-emailing-v3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pionl","download_url":"https://codeload.github.com/pionl/smart-emailing-v3/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244745666,"owners_count":20503044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","php","php-library"],"created_at":"2024-10-11T10:45:23.038Z","updated_at":"2025-03-21T05:30:53.694Z","avatar_url":"https://github.com/pionl.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smart Emailing API v3\nAPI wrapper for [Smart emailing](http://smartemailing.cz) API. \n\n![img](https://img.shields.io/badge/PHPStan-8-blue)\n![php](https://img.shields.io/badge/PHP-7.4%20to%208.2-B0B3D6)\n![coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/pionl/acb2fd9298c1faa461c2a60b54b673ed/raw/coverage.json)\n[![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)\n[![Total Downloads](https://poser.pugx.org/pion/smart-emailing-v3/downloads?format=flat)](https://packagist.org/packages/pion/smart-emailing-v3)\n[![Latest Stable Version](https://poser.pugx.org/pion/smart-emailing-v3/v/stable?format=flat)](https://packagist.org/packages/pion/smart-emailing-v3)\n[![Latest Unstable Version](https://poser.pugx.org/pion/smart-emailing-v3/v/unstable?format=flat)](https://packagist.org/packages/pion/smart-emailing-v3)\n\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [Supports](#supports)\n* [Advanced docs](#advanced-docs)\n* [Contribution or overriding](#contribution-or-overriding)\n* [Upgrading](#upgrading)\n* [Copyright and License](#copyright-and-license)\n* [Smart emailing API](https://app.smartemailing.cz/docs/api/v3/index.html)\n\n## Installation\n\n**Requirements**\n\nThis package requires PHP 7.4 and higher.\n\n**Install via composer**\n\n```\ncomposer require pion/smart-emailing-v3\n```\n\n## Usage\n\nCreate an Api instance with your username and apiKey.\n\n```php\nuse SmartEmailing\\v3\\Api;\n\n...\n$api = new Api('username', 'api-key');\n\n```\n\nthen use the `$api` with desired method/component.\n\n```php\n// Creates a new instance\n$api-\u003eimportRequest()-\u003eaddContact(new Contact('test@test.cz'))-\u003esend();\n```\n\nor\n\n```php\n// Creates a new instance\n$import = $api-\u003eimportRequest();\n$contact = new Contact('test@test.cz');\n$contact-\u003esetName('Martin')-\u003esetNameDay('2017-12-11 11:11:11');\n$import-\u003eaddContact($contact);\n\n// Create new contact that will be inserted in the contact list\n$contact2 = $import-\u003enewContact('test2@test.cz');\n$contact2-\u003esetName('Test');\n\n// Create new contact that will be inserted in the contact list\n$import-\u003enewContact('test3@test.cz')-\u003esetName('Test');\n$import-\u003esend();\n```\n### Error handling\n\nWhen sending any request you can catch the error exception `RequestException`.\n\n```php\nuse SmartEmailing\\v3\\Exceptions\\RequestException;\n\ntry {\n    $api-\u003eping();\n} catch (RequestException $exception) {\n    $exception-\u003eresponse(); // to get the real response, will hold status and message (also data if provided)\n    $exception-\u003erequest(); // Can be null if the request was 200/201 but API returned error status text\n}\n```\n\n## Supports\n\n* [x] [Import contacts](https://app.smartemailing.cz/docs/api/v3/index.html#api-Import-Import_contacts)\n* [x] [Import orders](https://app.smartemailing.cz/docs/api/v3/index.html#api-Import-Import_orders)\n* [x] [Ping](https://app.smartemailing.cz/docs/api/v3/index.html#api-Tests-Aliveness_test)\n* [x] [Credentials](https://app.smartemailing.cz/docs/api/v3/index.html#api-Tests-Login_test_with_GET)\n* [x] [Contactlist](https://app.smartemailing.cz/docs/api/v3/index.html#api-Contactlists-Get_Contactlists)\n* [ ] [Customfields](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields)\n  * [x] [Customfields - create](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields)\n  * [x] [Customfields - search / list](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields)\n  * [ ] [Customfields - rest](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields)\n  * [ ] [Customfields - options](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfield_Options)\n* [x] [Contacts](https://app.smartemailing.cz/docs/api/v3/index.html#api-Contacts)\n* [ ] [Contacts in list](https://app.smartemailing.cz/docs/api/v3/index.html#api-Contacts_in_lists)\n* [ ] [Custom emails](https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_emails)\n* [x] [Emails](https://app.smartemailing.cz/docs/api/v3/index.html#api-Emails)\n* [x] [Newsletter](https://app.smartemailing.cz/docs/api/v3/index.html#api-Newsletter)\n* [ ] [Webhooks](https://app.smartemailing.cz/docs/api/v3/index.html#api-Webhooks)\n* [x] (DEPRECATED) [E-shops](https://app.smartemailing.cz/docs/api/v3/index.html#api-E_shops)\n\n## Advanced docs\n\n## Import contacts\n\nThe import holds 2 main data points:\n1. Settings `$import-\u003esettings()-\u003esetUpdate(true)`\n2. Contacts `$import-\u003enewContact() : Contact`, `$import-\u003econtacts() : array` and `$import-\u003eaddContact($contact) : self`\n\nExample of usage is above.\n\n### [Contact](./src/Models/Contact.php)\n\nThe import holds 3 main data points:\n1. All data accessible via public properties. Fluent set method has basic validation and date convert logic\n2. CustomFields `$contact-\u003ecustomFields()` for adding new fields\n3. ContactLists `$contact-\u003econtactLists()` for adding new contact list\n\nSee source code for all methods/properties that you can use\n\n#### [CustomFields](./src/Models/Holder/CustomFields.php) and [ContactLists](./src/Models/Holder/ContactLists.php)\n\nUses a data holder with `create`/`add`/`get`/`isEmpty`/`toArray`/`jsonSerialize` methods.\n\n```php\n$field = $contact-\u003ecustomFields()-\u003ecreate(12, 'test')\n$list = $contact-\u003econtactLists()-\u003ecreate(12, 'confirmed')\n```\n\n## Import orders\n\nThe import holds 2 main data points:\n1. Settings `$import-\u003esettings()-\u003esetSkipInvalidOrders(true)`\n2. Orders `$import-\u003enewOrder() : Order`, `$import-\u003eorders() : array` and `$import-\u003eaddOrder($order) : self`\n\nExample of usage is above.\n\n## CustomFields\n\nThe customFields uses a wrapper for each request related to custom-fields. To create a new instance call `$api-\u003ecustomFields()`.\nOn this object you can create any request that is currently implemented. See below.\n\n### Create\n\nQuick way that will create request with required customField\n\n```php\nuse SmartEmailing\\v3\\Models\\CustomFieldDefinition;\n\n...\n// Create the new customField and send the request now.\n$customField = new CustomFieldDefinition('test', CustomFieldDefinition::TEXT);\n$data = $api-\u003ecustomFields()-\u003ecreate($customField);\n\n // Get the customField in data\n$customFieldId = $data-\u003eid;\n```\n\nor\n\n```php\n$request = $api-\u003ecustomFields()-\u003ecreateRequest(); // You can pass the customField object\n\n// Setup customField\n$customField = new CustomField();\n$request-\u003esetCustomField($customField);\n\n// Setup data\n$customField-\u003esetType(CustomField::RADIO)-\u003esetName('test');\n\n// Send the request\n$response = $request-\u003esend();\n$data = $response-\u003edata();\n$customFieldId = $data-\u003eid;\n```\n\n### Search / List\n[API DOCS](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields-Get_Customfields)\n\nEnables searching threw the custom fields with a filter/sort support. Results are limited by 100 per page. The response\nreturns meta data (MetaDataInterface) and an array of `Models\\CustomFieldDefinition` by calling `$response-\u003edata()`.\n\n#### Response\n\n* data() returns an array `Models\\CustomFieldDefinition`\n* meta() returns a `stdClass` with properties (defined in `MetaDataInterface`)\n\n#### Get a list without advanced search\nCreates a search request and setups only `$page` or `$limit`. The full response from api with `customfield_options_url` or\n\n```php\n$data = $api-\u003ecustomFields()-\u003elist();\n\n/** @var \\SmartEmailing\\v3\\Models\\CustomFieldDefinition $customField */\nforeach ($data as $customField) {\n    echo $customField-\u003eid;\n    echo $customField-\u003ename;\n    echo $customField-\u003etype;\n}\n```\n\n#### Advanced search - filter/sort/etc\n\n```php\n$request = $api-\u003ecustomFields()-\u003esearchRequest(1);\n\n// Search by name\n$request-\u003efilter()-\u003ebyName('test');\n$request-\u003esortBy('name');\n\n// Send the request\n$response = $request-\u003esend();\n$data = $response-\u003edata();\n```\n##### Request methods\n\n* Getters are via public property\n    * page\n    * limit\n    * select\n    * expand\n    * sort\n* Fluent Setters (with a validation) - more below.\n* `filter()` returns a Filters setup - more below\n\n###### expandBy(string : $expand)\nUsing this parameter, \"customfield_options_url\" property will be replaced by \"customfield_options\" contianing\nexpanded data. See examples below For more information see \"/customfield-options\" endpoint.\n\nAllowed values: \"customfield_options\"\n\n###### select(string : $select)\nComma separated list of properties to select. eg. \"?select=id,name\" If not provided, all fields are selected.\n\nAllowed values: \"id\", \"name\", \"type\"\n\n###### sortBy(string : $sort)\nComma separated list of sorting keys from left side. Prepend \"-\" to any key for desc direction, eg.\n\"?sort=type,-name\"\n\nAllowed values: \"id\", \"name\", \"type\"\n\n###### setPage(int : $page)\nSets the current page\n\n###### limit(int : $limit)\nSets the limit of result in single query\n\n###### filter()\nAllows filtering custom fields with multiple filter conditions.\n\n* Getters are via public property\n    * name\n    * type\n    * id\n* Fluent Setters (with a validation)\n    * byName($value)\n    * byType($value)\n    * byId($value)\n\n### Get by name\nRuns a search query with name filter and checks if the given name is found in customFields. Returns `false` or the `CustomFields\\CustomField`.\nUses send logic (throws RequestException).\n\n```php\n// Can throw RequestException - uses send.\nif ($customField = $api-\u003ecustomFields()-\u003egetByName('name')) {\n    return $customField-\u003eid;\n} else {\n    throw new Exception('Not found!', 404);\n}\n```\n## Send / Transactional emails\nThe implementation of API call ``send/transactional-emails-bulk``: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_transactional_emails\n### Full transactional email example\n```php\n$transactionEmail = $api-\u003etransactionalEmailsRequest();\n\n$credentials = new SenderCredentials();\n$credentials-\u003esetFrom('from@example.com');\n$credentials-\u003esetReplyTo('to@example.com');\n$credentials-\u003esetSenderName('Jean-Luc Picard');\n\n$recipient = new Recipient();\n$recipient-\u003esetEmailAddress('kirk@example.com');\n\n$replace1 = new Replace();\n$replace1-\u003esetKey('key1');\n$replace1-\u003esetContent('content1');\n\n$replace2 = new Replace();\n$replace2-\u003esetKey('key2');\n$replace2-\u003esetContent('content2');\n\n$templateVariable = new TemplateVariable();\n$templateVariable-\u003esetCustomData([\n    'foo' =\u003e 'bar',\n    'products' =\u003e [\n        ['name' =\u003e 'prod1', 'desc' =\u003e 'desc1'],\n        ['name' =\u003e 'prod1', 'desc' =\u003e 'desc2']\n    ]\n]);\n\n$attachment1 = new Attachment();\n$attachment1-\u003esetContentType('image/png');\n$attachment1-\u003esetFileName('picture.png');\n$attachment1-\u003esetDataBase64('data1');\n\n$attachment2 = new Attachment();\n$attachment2-\u003esetContentType('image/gif');\n$attachment2-\u003esetFileName('sun.gif');\n$attachment2-\u003esetDataBase64('data2');\n\n$task = new Task();\n$task-\u003esetRecipient($recipient);\n$task-\u003eaddReplace($replace1);\n$task-\u003eaddReplace($replace2);\n$task-\u003esetTemplateVariables($templateVariable);\n$task-\u003eaddAttachment($attachment1);\n$task-\u003eaddAttachment($attachment2);\n\n$messageContents = new MessageContents();\n$messageContents-\u003esetTextBody('text_body');\n$messageContents-\u003esetHtmlBody('html_body');\n$messageContents-\u003esetSubject('subject');\n\n$transactionEmail-\u003esetTag('tag_tag');\n$transactionEmail-\u003esetEmailId(5);\n$transactionEmail-\u003esetSenderCredentials($credentials);\n$transactionEmail-\u003eaddTask($task);\n$transactionEmail-\u003esetMessageContents($messageContents);\n\n$transactionEmail-\u003esend();\n```\n\n## Send / Bulk custom emails\nThe implementation of API call ``send/custom-emails-bulk``: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_emails\n### Full custom email example\n```php\n$transactionEmail = $api-\u003ecustomEmailsBulkRequest();\n\n$credentials = new SenderCredentials();\n$credentials-\u003esetFrom('from@example.com');\n$credentials-\u003esetReplyTo('to@example.com');\n$credentials-\u003esetSenderName('Jean-Luc Picard');\n\n$recipient = new Recipient();\n$recipient-\u003esetEmailAddress('kirk@example.com');\n\n$replace1 = new Replace();\n$replace1-\u003esetKey('key1');\n$replace1-\u003esetContent('content1');\n\n$replace2 = new Replace();\n$replace2-\u003esetKey('key2');\n$replace2-\u003esetContent('content2');\n\n$templateVariable = new TemplateVariable();\n$templateVariable-\u003esetCustomData([\n    'foo' =\u003e 'bar',\n    'products' =\u003e [\n        ['name' =\u003e 'prod1', 'desc' =\u003e 'desc1'],\n        ['name' =\u003e 'prod1', 'desc' =\u003e 'desc2']\n    ]\n]);\n\n$task = new Task();\n$task-\u003esetRecipient($recipient);\n$task-\u003eaddReplace($replace1);\n$task-\u003eaddReplace($replace2);\n$task-\u003esetTemplateVariables($templateVariable);\n\n$transactionEmail-\u003esetTag('tag_tag');\n$transactionEmail-\u003esetEmailId(5);\n$transactionEmail-\u003esetSenderCredentials($credentials);\n$transactionEmail-\u003eaddTask($task);\n\n$transactionEmail-\u003esend();\n```\n## Send / Bulk custom sms\nThe implementation of API call ``send/custom-sms-bulk``: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_SMS\n\n### Full send sms example\n\n```php\n$bulkCustomSms = $api-\u003ecustomSmsBulkRequest();\n\n$recipient = new Recipient();\n$recipient-\u003esetEmailAddress('kirk@example.com');\n$recipient-\u003esetCellphone('+420777888777');\n\n$replace1 = new Replace();\n$replace1-\u003esetKey('key1');\n$replace1-\u003esetContent('content1');\n\n$replace2 = new Replace();\n$replace2-\u003esetKey('key2');\n$replace2-\u003esetContent('content2');\n\n$task = new Task();\n$task-\u003esetRecipient($recipient);\n$task-\u003eaddReplace($replace1);\n$task-\u003eaddReplace($replace2);\n\n$bulkCustomSms-\u003esetTag('tag_tag');\n$bulkCustomSms-\u003esetSmsId(5);\n$bulkCustomSms-\u003eaddTask($task);\n\n$bulkCustomSms-\u003esend();\n```\n\n## Upgrading\nSee [UPGRADE.md](UPGRADE.md) for how to upgrade to newer versions.\n\n\n## Contribution or overriding\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute changes. All contributions are welcome.\n\n## Copyright and License\n\n[smart-emailing-v3](https://github.com/pionl/smart-emailing-v3)\nwas written by [Martin Kluska](http://kluska.cz) and is released under the\n[MIT License](LICENSE.md).\n\nCopyright (c) 2016 - 2022 Martin Kluska and contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpionl%2Fsmart-emailing-v3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpionl%2Fsmart-emailing-v3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpionl%2Fsmart-emailing-v3/lists"}