PHPackages                             jan-suchanek/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. jan-suchanek/smart-emailing-v3

ActiveLibrary[API Development](/categories/api)

jan-suchanek/smart-emailing-v3
==============================

Wrapper for SmartEmailing API

v0.3.1(5y ago)012.2k↓41.7%MITPHPPHP >=7.2

Since Feb 17Pushed 5y agoCompare

[ Source](https://github.com/ebrana/smart-emailing-v3)[ Packagist](https://packagist.org/packages/jan-suchanek/smart-emailing-v3)[ RSS](/packages/jan-suchanek-smart-emailing-v3/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (3)Versions (13)Used By (0)

Smart Emailing API v3
=====================

[](#smart-emailing-api-v3)

API wrapper for [Smart emailing](http://smartemailing.cz) API. Currenlty in development.

[![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)[![Build Status](https://camo.githubusercontent.com/07c318eab606a09de302bf3717ab934799f1b6a3476b0953e020efd7c8d0b95d/68747470733a2f2f7472617669732d63692e6f72672f70696f6e6c2f736d6172742d656d61696c696e672d76332e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/pionl/smart-emailing-v3)

- [Installation](#installation)
- [Usage](#usage)
- [Supports](#supports)
- [Advanced docs](#advanced-docs)
- [Changelog](#changelog)
- [Contribution or overriding](#contribution-or-overriding)
- [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.3 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->import()->addContact(new Contact('test@test.cz'))->send();
```

or

```
// Creates a new instance
$import = $api->import();
$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 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
--------

[](#supports)

- [Import](https://app.smartemailing.cz/docs/api/v3/index.html#api-Import-Import_contacts)`$api->import()` or `new Import($api)`
- [Ping](https://app.smartemailing.cz/docs/api/v3/index.html#api-Tests-Aliveness_test) `$api->ping()` or `new Ping($api)`
- [Credentials](https://app.smartemailing.cz/docs/api/v3/index.html#api-Tests-Login_test_with_GET) `$api->credentials()` or `new Credentials($api)`
- [Contactlist](https://app.smartemailing.cz/docs/api/v3/index.html#api-Contactlists-Get_Contactlists) 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](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields) create request `$api->customFields()->createRequest()` or send create request `$api->customFields()->create(new CustomField('test', CustomField::TEXT))`
- [Customfields - search / list](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields) search request `$api->customFields()->searchRequest($page = 1, $limit = 100)` or send search request `$api->customFields()->search($page = 1, $limit = 100)`
- [Customfields - rest](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields) Similar concept as contact-list - already started
- [Customfiels 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) Similar concept as contact-list
- [Contacts in list](https://app.smartemailing.cz/docs/api/v3/index.html#api-Contacts_in_lists) Similar concept as contact-list
- [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)

Advanced docs
-------------

[](#advanced-docs)

Import
------

[](#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](./src/Request/Import/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/Request/Import/Holder/CustomFields.php) and [ContactLists](./src/Request/Import/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')
```

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\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

[](#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 `CustomField\CustomField` by calling `$response->data()`.

#### Response

[](#response)

- data() returns an array `CustomField\CustomField`
- meta() returns a `stdClass` with properties (defined in `MetaDataInterface`)

#### Get a list without advanced setup

[](#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

[](#advanced-setup---filtersortetc)

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

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

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

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

### Exists

[](#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

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

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

[](#full-transactional-email-example-1)

```
$transactionEmail = new BulkCustomEmails($api);

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

Changelog
---------

[](#changelog)

### 0.1.8

[](#018)

- Added purposes for contacts.

### 0.1.7

[](#017)

- Fix incorrect namespace for confirmation request.

### 0.1.6

[](#016)

- Added confirmation request to import settings.

### 0.1.5

[](#015)

- Removed deprecated API usage in Contact.php: `addContactList` and `newContactList`

### 0.1.4

[](#014)

- CustomFields can be imported only once (unique by id)

### 0.1.3

[](#013)

- 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

[](#012)

- 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

[](#011)

- 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

[](#01)

- Added Custom-fields create request

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 Martin Kluska

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity23

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 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 ~144 days

Recently: every ~248 days

Total

11

Last Release

1924d ago

PHP version history (3 changes)v0.1.0PHP >=5.5

v0.2.0PHP >=7.3

v0.3.1PHP >=7.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/b086a6c086062dd312808a47a590b3265667bd20f369139eac17722f73502833?d=identicon)[jan-suchanek](/maintainers/jan-suchanek)

---

Top Contributors

[![ebrana-devs](https://avatars.githubusercontent.com/u/7850167?v=4)](https://github.com/ebrana-devs "ebrana-devs (4 commits)")[![pionl](https://avatars.githubusercontent.com/u/1878831?v=4)](https://github.com/pionl "pionl (3 commits)")[![stanislav-janu](https://avatars.githubusercontent.com/u/5769861?v=4)](https://github.com/stanislav-janu "stanislav-janu (3 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)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jan-suchanek-smart-emailing-v3/health.svg)

```
[![Health](https://phpackages.com/badges/jan-suchanek-smart-emailing-v3/health.svg)](https://phpackages.com/packages/jan-suchanek-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)