Developing batch email capabilities using REST APIs

The mailing list REST APIs provided by NexJ Systems enable external systems to:

1. Retrieve a collection of entity lists (saved lists) from NexJ CRM for a given user.
2. Email content generated in the external system to the entities in a saved list that was retrieved in the previous step.
   

Retrieving a user's entity lists

You can use the following REST API to retrieve a collection of entity lists for a given NexJ CRM user.

Your administrator must grant you the NexJ CRM EntityListView privilege before you can use the API to read entity lists.

API specification

This API has the following properties:

Example

The following code shows an example of a GET request to retrieve entity lists, and a response.

Request URL:
GET http://localhost:7080/nexj/channel/rest:REST/entityLists

Response Body:
{
   "pageSize": 2,
   "size": 2,
   "values": [
      {
         "name": "Birthday List",
         "$id": "10ABC0616BEC8A40E9ACE797008CB5E828"
      },
      {
         "name": "Monthly interactions",
         "$id": "10DB06A51B5ECD46E99467A7AFFA1D327C"
      }
   ],
   "links": {
      "first": {
         "href": "http://localhost:7080/nexj/channel/rest:REST/entityLists"
      },
      "self": {
         "href": "http://localhost:7080/nexj/channel/rest:REST/entityLists"
      }
   }
}

Sending an email to an entity list

You can use the following REST API to send a batch email to an entity list.

Your administrator must grant you the NexJ CRM BatchProcessManage privilege before you can use the REST API to send a batch email to an entity list.

API specification

This API has the following properties:

Example

The following code shows an example of a POST request to send a batch email to an entity list, and a response.

Request URL:
POST http://localhost:7080/nexj/channel/rest:REST/sendEmailToEntityList

Request Body:
{
  "emailBody" : "Email body",
   "entityList": {
      "$id" : "101CB52AD48E2F4F1883BEF65C311DA91F"
    },
   "emailSubject" : "Email subject",
   "addLogItem" : false
}

Response Body:
{
   "data": {
      "emailSubject": "Email Subject",
      "entityList": {
         "name": "Sample entity list",
         "$id": "101CB52AD48E2F4F1883BEF65C311DA91F"
      },
      "$commit-hash": 1792823380,
      "addLogItem": false,
      "emailBody": "Email Body"
   },
}

When the user making the request does not have an email configured in NexJ CRM, an error is thrown in the API response.

If the batch email fails because one or more contacts do not have email configured, the errors are visible only in NexJ CRM. The API response does not indicate when the batch email process has failures.

Sample UI configuration using APIs

A set of sample configuration artifacts are available to implement user interface features using the APIs in the \etc\restapi\mailinglist directory of the inform project. The instructions for setting up the sample configuration are provided in the README.md file in the same directory. The sample code demonstrates the following:

• Service persisted meta classes that use the APIs to provide a collection of entity lists.
• User interface configuration, including a picker, to select an entity list using the meta class.
• How to send an email using the API to the entity list selected from the picker.

Related link

Enabling and configuring REST API v2