README.md

suite-js-sdk

Simple Javascript wrapper for the Emarsys API.

Important: This library does not support WSSE authentication. It is intended only to be used by Emarsys add-ons and internal services.

Installation

npm install --save suite-js-sdk

Testing

npm test

Release

Releases are automatized with semantic-release. Whether a release is triggered, and whether it is major, minor, or patch increase, is based the on commit message, follow the conventions.

Emarsys API Hint

This wrapper tries to implement all available methods of the Emarsys API in a node fashion, exposing a Promise-only interface.

However, the Emarsys API lacks a decent amount of methods that you expect an API to provide. Thus, if methods are missing or a certain implementation style was chosen it is most likely due to the inconsistency of the API itself. Feel free to get in touch or submit a pull request if you encounter any problems.

Configuration and Setup

Debug

If you want to debug. Set your environment variables

DEBUG=suite-sdk,suiterequest

Authentication middleware

Prerequisites

The koa bodyparser module should be installed and in use before the use of the koaMiddleware.

npm install koa-bodyparser -S

In application configuration:

var bodyParser = require('koa-bodyparser');

var app = koa();
app.use(bodyParser());

Configuration

Set your environment variables

SUITE_ESCHER_SECRET=yourEscherSecret
SUITE_ESCHER_CREDENTIAL_SCOPE=yourEscherCredentialScope

Usage

var middleware = require('suite-js-sdk').authentication.koaMiddleware.getMiddleware();

If the authentication fails it throws an error with 401 code. If the authentication success it decorates the request with a validatedData property. It contains the signed parameters.

Translation middleware

Configuration

var middleware = require('suite-js-sdk').translations.koaMiddleware.decorateRenderWithTranslations();

The middleware use 'validatedData' from the request. 'validatedData' must contain an 'environment' property. If you want to load an admins language then 'validatedData' must contain a 'customer_id' and an 'admin_id' properties. If you want to load a specific language then 'validatedData' must contain a 'language' property.

Usage

Middleware decorates the render method. It will add 'translations' object as render data. It also adds a '_' method as render data. So you can use it for translations.

translations = {
    dialogs: {
        invitation: {
            confirmation: {
                message: 'test string with %s and with %s'
            }
        }
    }
}

in your jade file

p.message= _('dialogs.invitation.confirmation.message', [ 'firstParameter', 'second parameter'])

Interacting with the API

Authentication

Authenticate with the api credentials provided by your Emarsys account manager.

Set your environment variables

SUITE_API_KEY=yourApiKey
SUITE_API_SECRET=yourSecretKey

After in your Codebase

var SuiteAPI = require('suite-js-sdk').api;
var suiteAPI = SuiteAPI.create(options);

Options

• {String} customerId: the id of the customer
• {String} apiKey: API key
• {String} apiSecret: API secret
• {String} environment: API environment

SDK methods

Each of the following methods take a last options parameter as a last argument. With this options set you can override the customerId, escherOptions, etc. that you had defined when created an instance from the API client, like:

var SuiteAPI = require('suite-js-sdk').api;
var suiteAPI = SuiteAPI.create({
   customerId: 1083232
});

suiteAPI.administrator.getAdministrators({}, {
    customerId: 20234245
});

In the example above, the API will be called with customerId = 20234245.

Administrators

List

suiteAPI.administrator.getAdministrators(payload, options);

Get By Name

Data of an admin can be queried by providing its name.

suiteAPI.administrator.getAdministratorByName(payload, options);

Patch

suiteAPI.administrator.patchAdministrator(payload, options);

Create

suiteAPI.administrator.createAdministrator(payload, options);

Delete

suiteAPI.administrator.deleteAdministrator(payload, options);

Disable

Changes the status of the admin to disabled so logging in will not be possible.

suiteAPI.administrator.disableAdministrator(payload, options);

Enable

Changes the status of the disabled admin back to enabled so logging in becomes possible.

suiteAPI.administrator.enableAdministrator(payload, options);

Get Interface Languages

suiteAPI.administrator.getInterfaceLanguages(payload, options);

Get Start Pages

Returns the start pages of an administrator.

suiteAPI.administrator.getStartPages(payload, options);

Get Access Levels

suiteAPI.administrator.getAccessLevels(payload, options);

Promote to Superadmin

Levels up an admin to a superadmin.

suiteAPI.administrator.promoteToSuperadmin(payload, options);

Create Superadmin

Creates a superadmin.

suiteAPI.administrator.createSuperadmin(payload, options);

Invite Existing Administrator

Sets the status of the admin to disabled and invites the admin again. The admin can log in only after completing the necessary data on the invitation form.

suiteAPI.administrator.inviteExistingAdministrator(payload, options);

AutomationCenter

ProgramResource

suiteAPI.automationCenter.programResource(payload, options);

ProgramsEntrypoints

suiteAPI.automationCenter.programsEntrypoints(payload, options);

Campaign

create

suiteAPI.campaign.create(payload, options);

update

suiteAPI.campaign.update(payload, options);

Condition

List

suiteAPI.condition.list(payload, options);

List with contact fields

suiteAPI.condition.listWithContactFields(payload, options);

Contact

GetData

suiteAPI.contact.getData(payload, options);

To return the contacts with string field ids, specify { stringIds: true } in the options.

suiteAPI.contact.getData(payload, { stringIds: true });

Create

suiteAPI.contact.create(payload, options);

Merge

suiteAPI.contact.merge(payload, options);

Update

suiteAPI.contact.update(payload, options);

Create or update

suiteAPI.contact.createOrUpdate(payload, options);

Delete

suiteAPI.contact.delete(payload, options);

Check IDs

suiteAPI.contact.checkIds(payload, options);

Query Field Changes

suiteAPI.contact.lastChange(payload, options);

Contact List

Create

suiteAPI.contactList.create(payload, options);

List

suiteAPI.contactList.list(payload, options);

Fetch

suiteAPI.contactList.fetch(payload, options);

Add

suiteAPI.contactList.add(payload, options);

ListContactLists

suiteAPI.contactList.listContactLists(payload, options);

Count

suiteAPI.contactList.count(payload, options);

GetContactsData

suiteAPI.contactList.getContactsData(payload, options);

DeleteList

suiteAPI.contactList.deleteList(payload, options);

ExternalEvent

Create

suiteAPI.externalEvent.create(payload, options);

List

suiteAPI.externalEvent.list(payload, options);

Get Event Details

suiteAPI.externalEvent.get(payload, options);

Update

suiteAPI.externalEvent.update(payload, options);

Delete

suiteAPI.externalEvent.delete(payload, options);

Trigger

suiteAPI.externalEvent.trigger(payload, options);

Language

Translate

Lists available languages for a customer in the customer's own language.

suiteAPI.language.translate(payload, options);

Settings

Get

suiteAPI.settings.getSettings(payload, options);

Get Corporate Domains

Lists the permitted corporate domains of the customer. If corporate domains are set, registration is possible only with those email addresses which meet these requirements.

suiteAPI.settings.getCorporateDomains(payload, options);

Set Corporate Domains

Accepted corporate domains can be defined.

suiteAPI.settings.setCorporateDomains(payload, options);

Get IP Restrictions

Lists the permitted IP address rules (e.g. 192.168.* allows IP addresses which start with these two numbers and can end in any numbers).

suiteAPI.settings.getIpRestrictions(payload, options);

Set IP Restrictions

Possible IP address rules can be defined.

suiteAPI.settings.setIpRestrictions(payload, options);

Get available languages

suiteAPI.settings.getLanguages(payload, options);

Get security settings

Get security settings (IP whitelisting enabled option)

suiteAPI.settings.getSecuritySettings(payload, options);

Set security settings

Set security settings (IP whitelisting enabled option)

suiteAPI.settings.setSecuritySettings(payload, options);

Get sender domains

suiteAPI.settings.getDeliverabilitySenderDomains(payload, options);

Set sender domain

suiteAPI.settings.setDeliverabilitySenderDomain(payload, options);

Email

Create

suiteAPI.email.create(payload, options);

Copy

suiteAPI.email.copy(payload, options);

Update source

suiteAPI.email.updateSource(payload, options);

Launch

suiteAPI.email.launch(payload, options);

Launch list

suiteAPI.email.launchList(payload, options);

List

suiteAPI.email.list(payload, options);

Get

suiteAPI.email.get(payload, options);

Patch

suiteAPI.email.patch(payload, options);

Sending a Test Email

suiteAPI.email.sendTestMail(payload, options);

Broadcast an email to virtual contact

The payload must contain an email_id, which is the broadcast campaign id

suiteAPI.email.broadcast(payload, options);

Delivery Status

suiteAPI.email.getDeliveryStatus(payload, options);

Response

suiteAPI.email.responses(payload, options);

getResponseSummary

Returns the summary of the responses of a launched, paused, activated or deactivated email campaign.

suiteAPI.email.getResponseSummary(payload, options);

Querying Email Personalizations

Lists all possible alternate texts with their email campaigns. Alternate texts are defined for a specific field, and displayed in the email campaign if this field has no value.

suiteAPI.email.getPersonalizations(payload, options);

Updating Email Personalizations

Updates alternate texts.

suiteAPI.email.setPersonalizations(payload, options);

Creating a Tracked Link

suiteAPI.email.createTrackedLink(payload, options);

Querying Tracked Links

suiteAPI.email.getTrackedLinks(payload, options);

Updating a Tracked Link

suiteAPI.email.updateTrackedLink(payload, options);

Deleting Tracked Links

suiteAPI.email.deleteTrackedLinks(payload, options);

Export contact list

suiteAPI.email.getContacts(payload, options);

Deleting Tracked Links

suiteAPI.email.deleteTrackedLinksBySource(payload, options);

Listing Programs Email is used in

suiteAPI.email.listPrograms(payload, options);

Segment

List contacts

suiteAPI.segment.listContacts(payload, options);

Count contacts

suiteAPI.segment.countContacts(payload, options);

List segments

suiteAPI.segment.listSegments(payload, options);

Get Segment

suiteAPI.segment.getSegment(payload, options);

Create new segment

suiteAPI.segment.create(payload, options);

Querying contact criteria of a segment

suiteAPI.segment.getContactCriteria(payload, options);

Updating contact criteria of a segment

suiteAPI.segment.updateContactCriteria(payload, options);

Run Segment for Single Contact

suiteAPI.segment.runForSingleContact(payload, options);

Get Segment Run Status for Single Contact

suiteAPI.segment.singleContactRunStatus(payload, options);

Run Segment for Multiple Contacts

suiteAPI.segment.runForMultipleContacts(payload, options);

Get Segment Run Status for Multiple Contacts

suiteAPI.segment.multipleContactsRunStatus(payload, options);

Combined Segment

List combined segments

suiteAPI.combinedSegment.list(payload, options);

Create new combined segment

suiteAPI.combinedSegment.create(payload, options);

Querying a combined segment

suiteAPI.combinedSegment.get(payload, options);

Updating a combined segment

suiteAPI.combinedSegment.update(payload, options);

Purchases

List

Lists the purchases of customer for a date range.

suiteAPI.purchase.list(payload, options);

Stats

Statistics about the purchases of customer.

suiteAPI.purchase.stats(payload, options);

Contact Fields

Create

suiteAPI.field.create(payload, options);

Listing Available Fields

suiteAPI.field.get(payload, options);

Listing Available Fields Choices

suiteAPI.field.getChoices(payload, options);

Listing Available Fields Choices for multiple fields

suiteAPI.field.getMultipleChoices(payload, options);

Delete Field

suiteAPI.field.delete(payload, options);

Export

Downloading export data

suiteAPI.export.getData(payload, options);

Get Changes

suiteAPI.export.getChanges(payload, options);

Keyring

Manage customer PKI options

list

suiteAPI.keyring.list(payload, options);

get

suiteAPI.keyring.get(payload, options);

create

suiteAPI.keyring.create(payload, options);

delete

suiteAPI.keyring.delete(payload, options);

Contact Sources

Create

suiteAPI.source.create(payload, options);

Listing Sources

suiteAPI.source.listSources(payload, options);