PHPackages                             qerys/emarsys-mailer - 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. qerys/emarsys-mailer

Active

qerys/emarsys-mailer
====================

00PHP

Pushed 5y ago1 watchersCompare

[ Source](https://github.com/PLMartin/emarsys-mailer)[ Packagist](https://packagist.org/packages/qerys/emarsys-mailer)[ RSS](/packages/qerys-emarsys-mailer/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersionsUsed 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.

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. You also need to create an HTTP client and inject it into Emarsys Client. Snowcap/Emarsys is shipped with cURL HTTP client but it can be replaced with any other custom implementation.

```
define('EMARSYS_API_USERNAME', 'your_username');
define('EMARSYS_API_SECRET', 'your_secret');

$httpClient = new CurlClient();
$client = new Client($httpClient, EMARSYS_API_USERNAME, EMARSYS_API_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,
));
```

### 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/Snowcap/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 third argument of the constructor.

```
$client = new Client(EMARSYS_API_USERNAME, EMARSYS_API_SECRET, 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/Snowcap/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 completely the default mappings by passing an array as the fourth argument of the constructor.

```
$client = new Client(EMARSYS_API_USERNAME, EMARSYS_API_SECRET, array(), 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

8

—

LowBetter than 0% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity0

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity8

Early-stage or recently created project

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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/20b00da1326db1e4d00f015c92e29e2b79fb77be51fc89c1cd1136a72f8ef489?d=identicon)[Sotarkopa](/maintainers/Sotarkopa)

### Embed Badge

![Health badge](/badges/qerys-emarsys-mailer/health.svg)

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

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)