PHPackages                             invia-de/emarsys - 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. invia-de/emarsys

ActiveLibrary[API Development](/categories/api)

invia-de/emarsys
================

Emarsys RestFull API client

v2.0.0(2y ago)01311MITPHPPHP >=5.6

Since Jan 13Pushed 2y ago2 watchersCompare

[ Source](https://github.com/invia-de/Emarsys)[ Packagist](https://packagist.org/packages/invia-de/emarsys)[ RSS](/packages/invia-de-emarsys/feed)WikiDiscussions master Synced today

READMEChangelog (3)Dependencies (3)Versions (24)Used By (0)

Emarsys, PHP HTTP client for Emarsys webservice
===============================================

[](#emarsys-php-http-client-for-emarsys-webservice)

Emarsys is a PHP HTTP client based on the official Emarsys web service documentation and based on

At the time of writing, **only methods related to contacts are production ready**.

**All the other methods** have been implemented following the documentation but **not yet tested**.

### Installing via Composer

[](#installing-via-composer)

The recommended way to install Emarsys is through [Composer](http://getcomposer.org).

```
# Install Composer
curl -sS https://getcomposer.org/installer | php

# Add Emarsys as a dependency
php composer.phar require snowcap/emarsys:*
```

After installing, you need to require Composer's autoloader:

```
require 'vendor/autoload.php';
```

### Basics

[](#basics)

To use the client, you need to instantiate a new one with your credentials. Emarsys is shipped with Guzzle HTTP client.

```
$username = 'your_username';
$secret = 'your_secret';

$client = new \Emarsys\Client($username, $secret);
```

At this point, you have access to all the methods implemented by the Emarsys API

For example :

```
// Retrieve a contact from his email address
$response = $client->getContact(array(3 => 'example@example.com'));

// Create a contact with just his email information
$response = $client->createContact(array(3 => 'example@example.com'));

// Create a more complex contact
$response = $client->createContact(array(
    'email'      => 'johndoe@gmail.com',
    'gender'     => $client->getChoiceId('gender', 'male'),
    'salutation' => $client->getChoiceId('salutation', 'mr'),
    'firstName'  => 'John',
    'lastName'   => 'Doe',
    'birthDate'  => '2014-03-27',
    'address'    => 'Forgotten street 85B',
    'zip'        => '1000',
    'city'       => 'Brussels',
    'country'    => 17,
    'language'   => 3,
));
```

### GuzzleClient

[](#guzzleclient)

Emarsys is shipped with the Guzzle HTTP client. You can pass your configured guzzleclient as the third parameter while creating the emarsys client. This is the most time only needed for tests or set specific configurations. Don't pass a baseUrl into your own client, this one should pass as fourth parameter.

### BaseUrl

[](#baseurl)

The Url of the client is set to `https://api.emarsys.net/api/v2/`. While creating the client you can pass a other url as the fourth parameter.

### Custom field mapping

[](#custom-field-mapping)

As explained in the Emarsys documentation, each field is referenced by an ID.

You can do a `$response = $client->getFields();` to get the complete list with their ids and names.

But dealing with IDs is not always the easiest way to work.

So, extra methods have been implemented to handle custom mapping.

First of all, a default (non-exhaustive) mapping has been set for the Emarsys pre-defined fields. You can find it in `src/Emarsys/ini/fields.ini`

But you can add your own by calling :

```
$client->addFieldsMapping(array('petName' => 7849, 'twitter' => 7850));`
```

In that way, the default mapping and your own are merged and become available instantly as a replacement of these boring IDs.

It means that you can use both IDs and custom names to reference fields, so the two samples below do the same :

```
$response = $client->createContact(array(1 => 'John', 2 => 'Doe', 3 => 'example@example.com'));
$response = $client->createContact(array('firstName' => 'John', 'lastName' => 'Doe', 'email' => 'example@example.com'));
```

You also have access to additional methods to retrieve a particular ID by name and vice versa.

```
$fieldId = $client->getFieldId('firstName');
// will return 1;
$fieldName= $client->getFieldName(1);
// will return 'firstName';
```

Last but not least, you can completely override the default mappings by passing an array as the fifth argument of the constructor.

```
$client = new Client($username, $secret, null, array('firstName' => 1, 'lastName' => 2));
```

You just have to refer to the official Emarsys documentation or the `getFields()` method to identify the right IDs.

### Custom field choice mapping

[](#custom-field-choice-mapping)

When we use choice fields, each choice has its own ID, like a field.

You can do a `$response = $client->getFieldChoices(5);` to get the complete list of choices with their ids and names for a specific field (the gender for instance \[5\]).

But dealing with IDs is still not the easiest way to work.

So, extra methods have been implemented to handle custom mapping.

First of all, a default (non-exhaustive) mapping has been set for the Emarsys pre-defined field choices. You can find it in `src/Emarsys/ini/choices.ini`

But you can add your own by calling :

```
$client->addChoicesMapping(array('gender' => array('male' => 1, 'female' => 2)));
```

It means that you can use both IDs and custom names to reference field choices, so the two samples below do the same :

```
$response = $client->getFieldChoices(5);
$response = $client->getFieldChoices('gender');
```

You also have access to additional methods to retrieve a particular ID by name and vice versa.

```
$choiceId = $client->getChoiceId('gender', 'male');
// will return 1;
$choiceName= $client->getChoiceName('gender', 1);
// will return 'male';
```

You can of course override it completely the default mappings by passing an array as the sixth argument of the constructor.

```
$client = new Client($username, $secret, null, null, [], array('gender' => array('male' => 1, 'female' => 2)));
```

You just have to refer to the official Emarsys documentation or the `getFieldChoices()` method to identify the right IDs.

### The response

[](#the-response)

Almost every methods implementing the API return a new Response object.

This response is a simple class with three properties :

- a *replyCode*
- a *replyText*
- and the *data*

This matches the json response sent by the Emarsys API.

The reply code and reply text are the official reply returned by the Emarsys API. The data become an associative array representing the actual data (read the official Emarsys documentation, check the inline documentation in the code or var\_dump the response)

### Exceptions

[](#exceptions)

The client throws 2 types of exceptions

- a *ClientException* : which is related to wrong usage of this client
- a *ServerException* : which is related to wrong usage of the API itself

The *ServerException* is carrying the original reply text and reply code sent by the API.

Some of the reply codes have already been handled as constants, but not all.

This could be very useful, for example : we could check the exception code to see if the contact was not found, then we could create it.

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity11

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor3

3 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 ~146 days

Recently: every ~166 days

Total

23

Last Release

911d ago

Major Versions

v1.5.8 → v2.0.02023-11-10

PHP version history (2 changes)v1.0.0PHP >=5.3.3

v1.5.1PHP >=5.6

### Community

Maintainers

![](https://www.gravatar.com/avatar/59c813eeb0b57a907699a276db66516019115bede29bc638ea10bdcc771643a3?d=identicon)[Darkmatus](/maintainers/Darkmatus)

---

Top Contributors

[![webarchitect609](https://avatars.githubusercontent.com/u/11293610?v=4)](https://github.com/webarchitect609 "webarchitect609 (12 commits)")[![tim-bezhashvyly](https://avatars.githubusercontent.com/u/462687?v=4)](https://github.com/tim-bezhashvyly "tim-bezhashvyly (10 commits)")[![otzy](https://avatars.githubusercontent.com/u/11853333?v=4)](https://github.com/otzy "otzy (8 commits)")[![Moinax](https://avatars.githubusercontent.com/u/679904?v=4)](https://github.com/Moinax "Moinax (5 commits)")[![jerome-arzel](https://avatars.githubusercontent.com/u/4091943?v=4)](https://github.com/jerome-arzel "jerome-arzel (5 commits)")[![darkmatus](https://avatars.githubusercontent.com/u/2587708?v=4)](https://github.com/darkmatus "darkmatus (4 commits)")[![MironowDW](https://avatars.githubusercontent.com/u/1997615?v=4)](https://github.com/MironowDW "MironowDW (3 commits)")[![Jamiewarb](https://avatars.githubusercontent.com/u/2754728?v=4)](https://github.com/Jamiewarb "Jamiewarb (3 commits)")[![phoenix-bjoern](https://avatars.githubusercontent.com/u/846569?v=4)](https://github.com/phoenix-bjoern "phoenix-bjoern (2 commits)")[![mbm80](https://avatars.githubusercontent.com/u/19147241?v=4)](https://github.com/mbm80 "mbm80 (1 commits)")[![WaffelWeib](https://avatars.githubusercontent.com/u/13387272?v=4)](https://github.com/WaffelWeib "WaffelWeib (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/invia-de-emarsys/health.svg)

```
[![Health](https://phpackages.com/badges/invia-de-emarsys/health.svg)](https://phpackages.com/packages/invia-de-emarsys)
```

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