suite-js-sdk
v21.1.7
Published
[![Codeship Status for emartech/suite-js-sdk](https://codeship.com/projects/754d4680-a546-0132-cbce-72e52541da30/status?branch=master)](https://codeship.com/projects/66642) [![Dependency Status](https://david-dm.org/emartech/suite-js-sdk.svg)](https://dav
Downloads
2,229
Keywords
Readme
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
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);
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);