PHPackages 2ur1st/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. 2ur1st/emarsys ActiveLibrary[API Development](/categories/api) 2ur1st/emarsys ============== Emarsys RestFull API client forked from snowcap for custom project v1.6.0(7y ago)08MITPHPPHP >=5.3.3 Since Jan 13Pushed 6y agoCompare [ Source](https://github.com/2ur1st/Emarsys)[ Packagist](https://packagist.org/packages/2ur1st/emarsys)[ RSS](/packages/2ur1st-emarsys/feed)WikiDiscussions master Synced 2mo ago READMEChangelogDependencies (2)Versions (17)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. 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 28 — LowBetter than 54% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity4 Limited adoption so far Community14 Small or concentrated contributor base Maturity66 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 ~88 days Recently: every ~138 days Total 15 Last Release 2893d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/4beea0f41745ebd03663b1f1008da2271970543b42149c333b975827a2f81f4f?d=identicon)[2ur1st](/maintainers/2ur1st) --- 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 (11 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)")[![Jamiewarb](https://avatars.githubusercontent.com/u/2754728?v=4)](https://github.com/Jamiewarb "Jamiewarb (3 commits)")[![MironowDW](https://avatars.githubusercontent.com/u/1997615?v=4)](https://github.com/MironowDW "MironowDW (3 commits)")[![phoenix-bjoern](https://avatars.githubusercontent.com/u/846569?v=4)](https://github.com/phoenix-bjoern "phoenix-bjoern (2 commits)")[![mehabox](https://avatars.githubusercontent.com/u/299009?v=4)](https://github.com/mehabox "mehabox (1 commits)")[![mbm80](https://avatars.githubusercontent.com/u/19147241?v=4)](https://github.com/mbm80 "mbm80 (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/2ur1st-emarsys/health.svg) ``` [![Health](https://phpackages.com/badges/2ur1st-emarsys/health.svg)](https://phpackages.com/packages/2ur1st-emarsys) ``` ### Alternatives [tinify/tinify PHP client for the Tinify API. Tinify compresses your images intelligently. Read more at https://tinify.com. 2515.2M72](/packages/tinify-tinify)[corsinvest/cv4pve-api-php Corsinvest Proxmox VE Client API PHP 801.4M](/packages/corsinvest-cv4pve-api-php)[zzantares/proxmoxve A simple PHP 5.5+ Proxmox API client. 17761.8k4](/packages/zzantares-proxmoxve)[snowcap/emarsys Emarsys RestFull API client 381.2M](/packages/snowcap-emarsys)[shortpixel/shortpixel-php ShortPixel PHP SDK. Read more at https://shortpixel.com/api-tools 37531.5k10](/packages/shortpixel-shortpixel-php)[mrkampf/proxmox-ve Proxmox VE API Client 6238.2k](/packages/mrkampf-proxmox-ve) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)