Core - Messages

Module dedicated to communication message templates.

The base url for the APIs in this page is at:

/api/admin

A JSON file with OpenAPI data about all core-related admin APIs can be downloaded here.

Get message template

Gets details about a specific message template:

GET /v1/messages/templates/{id}

Gets details about a specific message template

Parameters

id (integer) – The id of the message template

Status Codes

200 OK – Success

DELETE /v1/messages/templates/{id}

Marks a message template as deleted

Parameters

id (integer) – The id of the message template

Status Codes

200 OK – Success

id: The id of the message template (Int)

The request returns a positive Json response and the data of the message template corresponding to the ID:

{
  ID: 1234,                               // Int
  Format: 1,                              // Int
  Type: 1,                                // Int
  LCID: 2057,                             // Int
  Language: "en-GB",                      // String
  Sender: "John Doe",                     // String
  Subject: "Subject of the message",      // String
  Body: "Body of the message",            // String
  HTMLBody: "HTML Body of the message"    // String
}

Value of the Format property can be one of the MessageFormat enumeration. Value of the Type property can be one of the MessageType enumeration.

Get HTML message templates list

Gets the list of message templates for the HTML e-mail channel (it’s a Paged List APIs, as explained in the introduction):

GET /v1/messages/templates/combined-email

Gets the list of message templates for the HTML e-mail channel

Status Codes

200 OK – Success

Returns the list of the message templates:

[
  {
    ID: 1234,                               // Int
    Format: 0,                              // Int
    Type: 1,                                // Int
    LCID: 2057,                             // Int
    Language: "en-GB",                      // String
    Sender: "John Doe",                     // String
    Subject: "Subject of the message",      // String
    Body: "Body of the message",            // String (nullable)
    HTMLBody: "HTML Body of the message"    // String (nullable)
  },
  ...
]

The Format property is always 0 (CombinedEmail), as in MessageFormat enumeration. Value of the Type property can be one of the MessageType enumeration.

Get simple text message templates list

Gets the list of message templates for the simple text e-mail channel (it’s a Paged List APIs, as explained in the introduction):

GET /v1/messages/templates/simple-text-email

Gets the list of message templates for the simple text e-mail channel

Status Codes

200 OK – Success

Returns a list like this:

[
  {
    ID: 1234,                               // Int
    Format: 1,                              // Int (enum MessageFormat)
    Type: 1,                                // Int (enum MessageType)
    LCID: 2057,                             // Int
    Language: "en-GB",                      // String
    Sender: "John Doe",                     // String
    Subject: "Subject of the message",      // String
    Body: "Body of the message",            // String
    HTMLBody: "HTML Body of the message"    // String (nullable)
  },
  ...
]

The Format property is always 1 (SimpleTextEmail), as in MessageFormat enumeration. Value of the Type property can be one of the MessageType enumeration.

Get SMS message templates list

Gets the list of message templates for the SMS channel (it’s a Paged List APIs, as explained in the introduction):

GET /v1/messages/templates/sms

Gets the list of message templates for the SMS channel

Status Codes

200 OK – Success

Returns a list like this:

[
  {
    ID: 1234,                               // Int
    Format: 2,                              // Int
    Type: 1,                                // Int (enum MessageType)
    LCID: 2057,                             // Int
    Language: "en-GB",                      // String
    Body: "Body of the message"             // String
  },
  ...
]

The Format property is always 2 (SMS), as in MessageFormat enumeration. Value of the Type property can be one of the MessageType enumeration.

Get push notification message templates list

Gets the list of message templates for the Push Notification channel (it’s a Paged List APIs, as explained in the introduction):

GET /v1/messages/templates/push-notification

Gets the list of message templates for the Push Notification channel

Status Codes

200 OK – Success

Returns a list like this:

[
  {
    ID: 1234,                               // Int
    Format: 3,                              // Int
    Type: 1,                                // Int
    LCID: 2057,                             // Int
    Language: "en-GB",                      // String
    Subject: "Subject of the message",      // String
    Body: "Body of the message"             // String
  },
  ...
]

The Format property is always 3 (PushNotification), as in MessageFormat enumeration. Value of the Type property can be one of the MessageType enumeration.

Get message template list

Gets list of all message templates (it’s a Paged List APIs, as explained in the introduction):

GET /v1/messages/templates/list

Gets list of all message templates

Status Codes

200 OK – Success

Returns a list like this:

[
  {
    ID: 1234,                               // Int
    Format: 1,                              // Int
    Type: 1,                                // Int
    LCID: 2057,                             // Int
    Language: "en-GB",                      // String
    Sender: "John Doe",                     // String
    Subject: "Subject of the message",      // String
    Body: "Body of the message",            // String
    HTMLBody: "HTML Body of the message"    // String
  },
  ...
]

Value of the Format property can be one of the MessageFormat enumeration. Value of the Type property can be one of the MessageType enumeration.

The Subject property can be null only for SMS formats.

The HTMLBody and Sender properties are valorized only for CombinedEmail and SimpleTextEmail formats.

Add new or edit existing message template

Persists edits about a new or existing message template:

POST /v1/messages/templates

Persists edits about a new or existing message template

Status Codes

200 OK – Success

With a request body like this:

{
  ID: 123,                                // Int
  Subject: "Subject of the message",      // String (nullable)
  Sender: "John Doe",                     // String (nullable)
  Type: 1,                                // Int
  Format: 1,                              // Int
  Language: "en-GB",                      // String
  Body: "Body of the message",            // String
  HTMLBody: "HTML Body of the message"    // String (nullable)
}

If ID is not provided or is set to 0, then the request will create a new record.

Value Formats can be one of the MessageFormat enumeration. Value Types can be one of the MessageType enumeration.

Depending on the message type, some template migth accept or need some specific placeholders words that will be substituted with actual data when sending the message to the user. Here you can find the list of message placeholders, their meaning and the type of messages that accepts them.

The Sender property is required for CombinedEmail and SimpleTextEmail formats. The Subject field is nullable only for SMS format.

Returns a positive Json plain response if the request was successful.

Possible error messages are:

err_InvalidElement: No message to edit has been found for the provided ID, no language or body has been provided, no subject has been provided for e-mail or push notification messages or no sender has been provided for e-mail messages.
err_DuplicateElement: The request is trying to add a record with different ID but with the same Type, Format and LCID as an existing one

Delete Message Template

Deletes a message template from the database:

GET /v1/messages/templates/{id}

Gets details about a specific message template

Parameters

id (integer) – The id of the message template

Status Codes

200 OK – Success

DELETE /v1/messages/templates/{id}

Marks a message template as deleted

Parameters

id (integer) – The id of the message template

Status Codes

200 OK – Success

id: The id of the message template (Int)

Returns a plain Json positive response if the record was successfully deleted, or a plain negative response in case of any error.

Test message

Tries sending a specific message template through the relevant channel:

POST /v1/messages/templates/{id}/test

Tries sending a specified message template through the relevant channel

Parameters

id (integer) – The id of the message template

Status Codes

200 OK – Success

id: The id of the message template (Int)

The body must be like this:

{
  Recipient: "test@email.com"   //Required
}

The Recipient property must be valorized with the recipient e-mail for CombinedEmail and SimpleTextEmail formats, with the recipient mobile phone number for SMS format and with the recipient user name for PushNotification format.

Returns a Json positive response with a true or false depending on whether the message was succesfully delivered or not:

{
  true or false
}

In case there are errors with the object, returns as Json negative response with one of the following messages:

err_TestNoRecipient: No recipient was specified
post_generic: No message template corresponds to the ID in the request or there was an error while sending the message
err_TestFormatNotTestable: The Message format was not recognized for the test

Get message log

Returns the list of messages sent to the specified user:

GET /v1/messages/logs/{user}

Returns the list of messages sent to the specified user

Parameters

user (integer) – User id

Status Codes

200 OK – Success

user: User ID (Int)

Returns a list of the messages that have been received by the specified ID of the user:

[
  {
    ID: 1234,                                      // Int
    CreatedDate: "2001-01-01T01:01:01Z",           // DateTime
    MessageFormat: 1,                              // Int
    NotificationType: 1,                           // Int
    LastSendingAttempt: "2001-01-01T01:01:01Z",    // DateTime  (nullable)
    SendingAttemptResult: true                     // Boolean (nullable)
  },
  ...
]

Value of the MessageFormat property can be one of the MessageFormat enumeration. Value of the NotificationType property can be one of the NotificationType enumeration.

Get system message preferences

Returns the list of preferences set by the administration for the system messages communication channel (it’s a Paged List APIs, as explained in the introduction):

GET /v1/messages/system-message-preferences

Returns the list of preferences specified for the user to receive notifications

Status Codes

200 OK – Success

POST /v1/messages/system-message-preferences

Persists edits about a new or existing preference

Status Codes

200 OK – Success

It will return a plain Json error response in case of errors, otherwise the paged list of the expressed preferences in the following format:

{
  [
    {
      CreatedDate: "2001-01-01T01:01:01Z",    // DateTime
      CreatedBy: "User Name",                 // String
      LastUpdated: "2001-01-01T01:01:01Z",    // DateTime
      LastUpdatedBy: "User Name",             // String (nullable)
      "Type": 1,                              // Int
      "Format": 2                             // Int
    },
    { ... }
  ]
}

Value of the Format property can be one of the MessageFormat enumeration. Value of the Type property can be one of the SystemMessageType enumeration.

Add new or edit existing system message preference

Persists edits about a new or existing system message preference:

GET /v1/messages/system-message-preferences

Returns the list of preferences specified for the user to receive notifications

Status Codes

200 OK – Success

POST /v1/messages/system-message-preferences

Persists edits about a new or existing preference

Status Codes

200 OK – Success

The API accepts a body request in the following format:

{
  ID: 123,                // Int (nullable)
  MessageType: 1,         // Int
  MessageFormat: 1        // Int
}

where value of the MessageFormat property can be one of the MessageFormat enumeration and value of the MessageType property can be one of the SystemMessageType enumeration.

If ID (system message preference id) is not provided or is set to 0, then the request will create a new record.

It will return a plain positive Json response, or one of the following errors:

err_InvalidElement: The body provided in the request has no value set for MessageFormat or MessageType
err_NoTemplateFound: No message template was found for the provided MessageFormat and MessageType combination.

Get notification preferences

Returns the list of preferences specifying the channel in which the user will receive notifications:

GET /v1/messages/preferences/{id}

Returns the list of preferences specified for the user to receive notifications

Parameters

id (integer) – User id

Status Codes

200 OK – Success

POST /v1/messages/preferences/{id}

Persists edits about a new or existing preference

Parameters

id (integer) – The id of the user

Status Codes

200 OK – Success

id: User ID (Int)

Returns a list of preferences for the user corresponding to the ID provided in the request:

[
  {
    ID: 1234,                               // Int
    UserId: 123,                            // Int
    LastUpdated: "2001-01-01T01:01:01Z",    // dateTime
    LastUpdatedBy: "Administrator",         // String
    NotificationType: 0,                    // Int
    IsEmail: false,                         // Boolean
    IsSMS: false,                           // Boolean
    IsPush true                             // Boolean
  }
]

Value of the NotificationType property can be one of the NotificationType enumeration.

Add new or edit existing notification preference

Persists edits about a new or existing preference for a specific user:

GET /v1/messages/preferences/{id}

Returns the list of preferences specified for the user to receive notifications

Parameters

id (integer) – User id

Status Codes

200 OK – Success

POST /v1/messages/preferences/{id}

Persists edits about a new or existing preference

Parameters

id (integer) – The id of the user

Status Codes

200 OK – Success

where id is the ID of the user for whom the preference is expressed.

With a request body like this:

{
  ID: 123,                // Int
  NotificationType: 1,    // Int
  IsEmail: true,          // Boolean (nullable)
  IsSMS: true,            // Boolean (nullable)
  IsPush: true            // Boolean (nullable)
}

If ID (notification preference id) is not provided or is set to 0, then the request will create a new record.

Value of the NotificationType property can be one of the NotificationType enumeration.

A value of null in the boolean properties will be handled as false.

Returns a plain Json positive response if the record was successfully added or edited, or a negative response if not.

Possible error messages are:

err_InvalidElement: The body provided in the request has all three boolean values set to null or false
err_NoEmailTemplateFound: The field IsEmail is set to true but no message template has been found for the specified NotificationType for CombinedEmail and SimpleTextEmail formats
err_NoSMSTemplateFound: The field IsSMS is set to true but no message template has been found for the specified NotificationType for the SMS format
err_NoEmailSMSTemplateFound: The field IsEmail and IsSMS are set to true but no message template has been found for the specified NotificationType for CombinedEmail, SimpleTextEmail and SMS formats
err_NoPushTemplateFound: The field IsPush is set to true but no message template has been found for the specified NotificationType for PushNotification format
err_NoEmailPushTemplateFound: The field IsEmail and IsPush` are set to true but no message template has been found for the specified NotificationType for CombinedEmail, SimpleTextEmail and PushNotification formats
err_NoSMSPushTemplateFound: The field IsSMS and IsPush` to true but no message template has been found for the specified NotificationType for SMS and PushNotification formats
err_NoNotificationTemplateFound: The three boolean fields are set to true but no message template has been found for the specified NotificationType for any of the formats
err_DuplicateElement: The request is trying to add a record with different ID but with the same Type as an existing one on the same user