This APS type represents the platform built-in email messenger manager as explained in the Mail Notifications concepts.
In this document:
The considered APS type (download
)
extends the Resource APS type(s) and looks as follows:
{
"name": "MessengerManager",
"id": "http://www.parallels.com/pa/pa-core-services/messenger-manager/1.0",
"apsVersion": "2.0",
"implements": [
"http://aps-standard.org/types/core/resource/1.0"
],
"access": {
"global": true
},
"operations": {
"sendMessage": {
"path": "/messenger/send",
"verb": "POST",
"errorResponse": {
"type": "object"
},
"parameters": {
"message": {
"kind": "body",
"type": "Message"
}
}
},
"sendMessageToUser": {
"path": "/messenger/sendToUser",
"verb": "POST",
"errorResponse": {
"type": "object"
},
"parameters": {
"message": {
"kind": "body",
"type": "Message"
}
}
},
"getSubscriptions": {
"path": "/messenger/subscriptions",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "NotificationSubscription"
}
},
"errorResponse": {
"type": "object"
}
},
"createSubscription": {
"path": "/messenger/subscriptions",
"verb": "POST",
"response": {
"type": "NotificationSubscription"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"subscription": {
"kind": "body",
"type": "NotificationSubscription"
}
}
},
"getMessageTypes": {
"path": "/messenger/messagetypes",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "MessageType"
}
},
"errorResponse": {
"type": "object"
}
},
"addMessageType": {
"path": "/messenger/messagetypes",
"verb": "POST",
"response": {
"type": "MessageType"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"event": {
"kind": "body",
"type": "MessageType"
}
}
},
"deleteMessageType": {
"path": "/messenger/messagetypes/{msgTypeId}",
"verb": "DELETE",
"errorResponse": {
"type": "object"
},
"parameters": {
"msgTypeId": {
"kind": "path",
"type": "integer"
}
}
}
},
"structures": {
"Message": {
"type": "object",
"properties": {
"msgTypeId": {
"type": "integer"
},
"name": {
"type": "string"
},
"userId": {
"type": "string"
},
"accountId": {
"type": "string"
},
"params": {
"type": "object",
"required": true
}
}
},
"NotificationSubscription": {
"type": "object",
"properties": {
"msgTypeId": {
"type": "integer",
"required": true
},
"userId": {
"type": "string",
"required": true
}
}
},
"Template": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"from": {
"type": "string"
},
"subject": {
"type": "string",
"required": true
},
"body": {
"type": "string",
"required": true
},
"contentType": {
"type": "string"
}
}
},
"MessageType": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"required": true,
"readonly": true,
"final": true
},
"name": {
"type": "string",
"required": true,
"final": true
},
"description": {
"type": "string"
},
"templates": {
"type": "array",
"items": {
"type": "Template"
}
},
"subscribeByDefault": {
"type": "boolean"
},
"contentType": {
"type": "string",
"enum": [
"text/plain",
"text/html"
]
}
}
}
}
}
The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:
POST /aps/2/services/messenger-manager/<operation-path>?<query-params>
{/*<body params>*/}
In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
POST |
/messenger/send |
If successful, this method returns the 200 OK standard status code. |
Send the specified message through the messenger manager to all staff members of the account explicitly specified by the |
|
POST |
/messenger/sendToUser |
If successful, this method returns the 200 OK standard status code. |
Send the required message to the user specified by the |
|
GET |
/messenger/subscriptions |
If successful, this method returns a list of NotificationSubscription objects in the response body. |
Get notification subscriptions. |
|
POST |
/messenger/subscriptions |
If successful, this method returns the NotificationSubscription object in the response body. |
Subscribe the user that calls the method to the specified notification. |
|
GET |
/messenger/messagetypes |
If successful, this method returns a list of MessageType objects in the response body. |
Get a list of the registered message types. |
|
POST |
/messenger/messagetypes |
If successful, this method returns the MessageType object in the response body. |
Register a message type. |
|
DELETE |
/messenger/messagetypes/{msgTypeId} |
If successful, this method returns the 200 OK standard status code. |
Delete the specified message type (by APS ID). |
HTTP Request
POST /aps/2/services/messenger-manager/messenger/send
Description
Send the specified message through the messenger manager to all staff members of the account explicitly specified by the accountId
or implicitly by the userId
in the Message structure. If a user is specified in the message
structure by the userId
property, this is used to determine the account.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
message |
The Message structure. |
Returns
If successful, this method returns the 200 OK standard status code.
HTTP Request
POST /aps/2/services/messenger-manager/messenger/sendToUser
Description
Send the required message to the user specified by the userId
property in the Message structure.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
message |
Returns
If successful, this method returns the 200 OK standard status code.
HTTP Request
GET /aps/2/services/messenger-manager/messenger/subscriptions
Description
Get notification subscriptions.
Returns
If successful, this method returns a list of NotificationSubscription objects in the response body.
HTTP Request
POST /aps/2/services/messenger-manager/messenger/subscriptions
Description
Subscribe the user that calls the method to the specified notification.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
subscription |
Notification subscription NotificationSubscription |
Returns
If successful, this method returns the NotificationSubscription object in the response body.
HTTP Request
GET /aps/2/services/messenger-manager/messenger/messagetypes
Description
Get a list of the registered message types.
Returns
If successful, this method returns a list of MessageType objects in the response body.
HTTP Request
POST /aps/2/services/messenger-manager/messenger/messagetypes
Description
Register a message type.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
event |
Message type MessageType |
Returns
If successful, this method returns the MessageType object in the response body.
HTTP Request
DELETE /aps/2/services/messenger-manager/messenger/messagetypes/{msgTypeId}
Description
Delete the specified message type (by APS ID).
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
msgTypeId |
Integer |
Message type ID |
Returns
If successful, this method returns the 200 OK standard status code.
Message.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
msgTypeId |
Integer |
Not Required |
ID of the registered message type. |
|
name |
String |
Not Required |
Short description of the message type as displayed in the list of email templates in the provider control panel. |
|
userId |
String |
Not Required |
User ID is alernative to |
|
accountId |
String |
Not Required |
Account ID is alternative to |
|
params |
Object |
Required |
The list of the message specific parameters with values assigned to them. |
The structure used in the custom operations with notification subscriptions.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
msgTypeId |
Integer |
Required |
ID of the subscribed message type. |
|
userId |
String |
Required |
ID of the subscribed user. |
A template is created for a locale (language) and includes the translated subject and the message body.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
locale |
String |
Not Required |
Speifies a locale, for example, ‘de_DE’. |
|
from |
String |
Not Required |
It is the email |
|
subject |
String |
Required |
The translated subject of the email notification. |
|
body |
String |
Required |
The translated notification body of the email notification. This is the actual description of the occasion. |
|
contentType |
String |
Not Required |
Specifies if the content is a plain text (‘text/plain’) or an HTML code (‘text/html’). |
The structure used to register a message type.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
id |
Integer |
Required Read Only Final |
ID assigned by the platform. |
|
name |
String |
Required Final |
The name of the message type as displayed in the list of email templates in the provider control panel. |
|
description |
String |
Not Required |
Full description of the email template as displayed in the open email template in the provider control panel. |
|
templates |
Array of Template |
Not Required |
A list of the Template objects. |
|
subscribeByDefault |
Boolean |
Not Required |
Specifies if by default a new user will be subscribed (true) to the notification of this type or not (false). |
|
contentType |
Enum |
Not Required |
An enum variable that can be either “text/html” or “text/plain”. It informs the system whether the message body should be interpreted as a plain text or parsed as an HTML code. |
Note
Registration and modification of message types is allowed to APS applications only.
To get a list of registered message types, send the following request:
GET /aps/2/services/messenger-manager/messenger/messagetypes
The response will look as follows (shortened for brevity):
HTTP/1.1 200 OK
[
{
"id": 2,
"name": "Register domain method failed",
"description": "Register domain method failed",
"subscribeByDefault": false
},
{
"id": 5,
"name": "Check availability domains method failed",
"description": "Check availability domains method failed",
"subscribeByDefault": false
},
{
"id": 1,
"name": "License was suspended or terminated",
"description": "License was suspended or terminated",
"subscribeByDefault": false
},
{
"id": 6,
"name": "License update failed",
"description": "License update failed",
"subscribeByDefault": false
},
/* ... */
]
To get a list of subscriptions to mail notifications, send the following request:
GET /aps/2/services/messenger-manager/messenger/subscriptions
The response will look as follows (shortened for brevity):
HTTP/1.1 200 OK
[
{
"msgTypeId": 2,
"userId": "4cd4f457-9f4d-4ce7-88c5-a5818441a773"
},
{
"msgTypeId": 5,
"userId": "4cd4f457-9f4d-4ce7-88c5-a5818441a773"
},
/* ... */
]
To register a custom message type, an application must send a request similar to the following:
POST /aps/2/services/messenger-manager/messenger/messagetypes/
{
"id": null,
"name": "New VPS demo subscription",
"description": "New VPS demo subscription is created",
"templates": [
{
"locale": "en",
"from": "\"${vendor_company_name}\" <${vendor_tech_email}>",
"subject": "New VPS Demo subscription",
"body": "The customer ${customerName} subscribed to the VPS Demo application. Subscription APS ID - ${subscriptionId}",
"contentType":null
}
],
"subscribeByDefault": true,
"contentType": "text/plain"
}
The response will look as follows:
HTTP/1.1 200 OK
{
"id": 46,
"name": "New VPS demo subscription",
"description": "New VPS demo subscription is created",
"templates": [
{
"locale": "en",
"from": "\"${vendor_company_name}\" <${vendor_tech_email}>",
"subject": "New VPS Demo subscription",
"body": "The customer ${customerName} subscribed to the VPS Demo application. Subscription APS ID - ${subscriptionId}"
}
],
"subscribeByDefault": true,
"contentType": "text/plain"
}
To send a notification by email, an application must request it as follows:
POST /aps/10.1/resources/36948aca-ab2c-4a01-8766-668eaf655583//messenger/send
{
"msgTypeId": "46",
"name": null,
"userId": null,
"accountId": "0e34371a-ac67-48ff-89e1-c5200a90baa2",
"params": {
"customerName": "John Smith",
"subscriptionId":"38cd2bf8-6077-4e9a-b25c-c4cb5826490e"
}
}
The response will look as follows:
HTTP/1.1 200 OK
{
"msgTypeId": 46,
"accountId": "0e34371a-ac67-48ff-89e1-c5200a90baa2",
"params": {
"customerName": "John Smith",
"subscriptionId": "38cd2bf8-6077-4e9a-b25c-c4cb5826490e",
"message_type": "46",
"account_id_list": "1000001"
}
}
To remove a message type, for example, during removal of the APS application instance, the application must send the following request:
DELETE /aps/2/services/messenger-manager/messenger/messagetypes/46
The response must be as follows:
HTTP/1.1 200 OK
The Mail Notifications document explains the concepts and provides examples on the messenger operations for an APS connector based on the APS PHP framework.