Skip to main content
Skip table of contents

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

HTTP methodEndpoint
GET/entityLists

This API has the following properties:

PropertyTypeDescription
$idstringUnique ID of the entity list
namestringName of the entity list

Example

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

Example request and response for using the /entityLists API
TEXT
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

HTTP methodEndpoint
POST/sendEmailToEntityList

This API has the following properties:

PropertyTypeDescriptionRequired?
emailBodystringBody of the email.No
emailSubjectstringSubject of the email.No
addLogItemboolean

Whether to create a log item for recipients.

Optional. Default behavior: true.

No
entityListObjectJSON object with the ID of the entity list to send the email to.

Yes

Example

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

Example request and response for using the /sendEmailToEntityList API
TEXT
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.

Enabling and configuring REST API v2

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.