Communications

Search communications

This service returns the list of sent communications for the given filters, ordered by request time in descending order

GET /orgs/{org}/communications

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name as it is registered in Mas-Stack
destinationEmail	query	string	true	Queried communication’s email destination address
terminatingNumber	query	integer(int64)	true	Queried communication’s SMS terminating number without country code
countryCode	query	integer(int64)	false	Queried communication’s SMS country code without + symbol
requestTime[gt]	query	string	false	Return requests with request time greater (later) than the one specified
requestTime[lt]	query	string	false	Return requests with request time lower (earlier) than the one specified
clientId	query	string	false	Queried communication’s client id taken from audience header
limit	query	integer(int64)	false	Limit of results in the response
offset	query	integer(int64)	false	Offset applied to results for pagination
externalId	query	string	true	Internal reference provided by the client system that could be used in later queries

Request example

1
2
3
4
5



curl -X GET https://communications.masstack.com/v2/orgs/yoigo/communications?destinationEmail='diego.mateos@masmovil.com'&terminatingNumber='666123123'&countryCode='34'&requestTime[gt]='2020-01-01T14:00:00+01:00'&requestTime[lt]='2020-12-01T14:00:00+01:00'&clientId='mysim-sa'&limit='20'&offset='0'&externalId='sale-12512321'?destinationEmail=diego.mateos%40masmovil.com&terminatingNumber=666123123&externalId=sale-12512321 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}"

Responses

Code	Meaning	Description	Schema
200	OK	Successful communications search	CommunicationListResponse
400	Bad Request	Client error on request	ResponseErrorDto
500	Internal Server Error	Server error	ResponseErrorDto

Send communication

Send a communication of certain type in the specified language via the required channels

POST /orgs/{org}/communications

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name as it is registered in Mas-Stack
body	body	CommunicationRequestDto	true	Information needed to send a communication

Request body - instance of CommunicationRequestDto

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


{
  "type": "password_reset",
  "language": "en",
  "channels": "[sms]",
  "scheduledTime": "2022-04-25T12:00:00",
  "smsInput": {
    "countryCode": "54",
    "terminatingNumber": "623196241"
  },
  "emailInput": {
    "destinationEmail": "recipient@masmovil.es",
    "destinationName": "Diego"
  },
  "externalId": "string",
  "arguments": {
    "name": "Juan",
    "subscriptions": [
      "ftth",
      "mobile",
      "health"
    ],
    "resetLink": "https://password.com/reset/123456",
    "birthDate": "2022-04-25 12:00:00",
    "vipClient": false,
    "balance": 45.7,
    "birthCountry": "US",
    "attached.txt": "SG9sYSBQYWJsbyA6KQo=",
    "embedded_image_png": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
    "qrArgument": "Text to convert into QR Code",
    "pdfAttachments": {
      "apple.pdf": "VGhpcyBpcyBhIFBERiBjb250ZW50",
      "pear.pdf": "VGhpcyBpcyBhIFBERiBjb250ZW50"
    }
  }
}

Name	Type	Required	Description
type	string	true	Communication type code according to the ones previously defined in the system
language	string	true	Communication language(ISO 639-1)
channels	[string]	false	Channels list through which the communication will be sent, allowed values are: “sms”, “email”. If not specified, all channels with a defined template are used
scheduledTime	string	false	Programmed time for the communication to be sent that can be reprogrammed to fit delivery window.
smsInput	CommunicationRequestSmsDto	false	Specific parameters needed for SMS channel, mandatory if SMS channel requested. No need to provide it when previewing a communication
emailInput	CommunicationRequestEmailDto	false	Specific parameters needed for email channel, mandatory if email channel requested. No need to provide it when previewing a communication
externalId	string	false	Client internal reference
arguments	object	false	Parameters and assigned values that are required to render the specified template. Depending on the argument type they can be a string, a number, a boolean or an array
» additionalProperties	object	false	Parameters and assigned values that are required to render the specified template. Depending on the argument type they can be a string, a number, a boolean or an array

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41



curl -X POST https://communications.masstack.com/v2/orgs/yoigo/communications \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'type': 'password_reset',
  'language': 'en',
  'channels': '[sms]',
  'scheduledTime': '2022-04-25T12:00:00',
  'smsInput': {
    'countryCode': '54',
    'terminatingNumber': '623196241'
  },
  'emailInput': {
    'destinationEmail': 'recipient@masmovil.es',
    'destinationName': 'Diego'
  },
  'externalId': 'string',
  'arguments': {
    'name': 'Juan',
    'subscriptions': [
      'ftth',
      'mobile',
      'health'
    ],
    'resetLink': 'https://password.com/reset/123456',
    'birthDate': '2022-04-25 12:00:00',
    'vipClient': false,
    'balance': 45.7,
    'birthCountry': 'US',
    'attached.txt': 'SG9sYSBQYWJsbyA6KQo=',
    'embedded_image_png': 'iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==',
    'qrArgument': 'Text to convert into QR Code',
    'pdfAttachments': {
      'apple.pdf': 'VGhpcyBpcyBhIFBERiBjb250ZW50',
      'pear.pdf': 'VGhpcyBpcyBhIFBERiBjb250ZW50'
    }
  }
}" 

Responses

Code	Meaning	Description	Schema
202	Accepted	Successfully sent communication	CommunicationResponse
206	Partial Content	Communication sent with with some kind of failure, e.g:the e-mail has been successfully sent but the SMS failed in a multi-channel communication	CommunicationResponse
400	Bad Request	The response for client error when some field in the request is missing or invalid	ResponseErrorDto
500	Internal Server Error	Server error	ResponseErrorDto

Get communication qr image

Retrieve a qr image related to a sent communication

GET /qr

Parameters

Name	In	Type	Required	Description
qrToken	path	string	true	The communication encrypted data for generating QR Image

Request example

1
2
3
4
5



curl -X GET https://communications.masstack.com/v2/qr \
  -H "Accept: image/png" \
  -H "Authorization: Bearer {access-token}"

Responses

Code	Meaning	Description	Schema
200	OK	Successfully created QR code image	None
400	Bad Request	Invalid, missing or expired QR token	ResponseErrorDto
500	Internal Server Error	Server error while retrieving image	ResponseErrorDto

400 - instance of ResponseErrorDto

Custom schema example

1
2
3
4
5
6


{
  "commit": "v2.0.0",
  "error": {
    "message": "QR code expired or malformed"
  }
}

Name	Type	Required	Description
commit	string	false	Service version handling the request
error	ErrorDto	false	Error info

500 - instance of ResponseErrorDto

Custom schema example

1
2
3
4
5
6


{
  "commit": "v2.0.0",
  "error": {
    "message": "Error retrieving image"
  }
}

Name	Type	Required	Description
commit	string	false	Service version handling the request
error	ErrorDto	false	Error info

Get communication

Get latest info of a sent communication

GET /orgs/{org}/communications/{communicationId}

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name as it is registered in Mas-Stack
communicationId	path	string	true	The communication identifier

Request example

1
2
3
4
5



curl -X GET https://communications.masstack.com/v2/orgs/yoigo/communications/57cff118-984f-473c-a6ad-5ba51baed0dd \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}"

Responses

Code	Meaning	Description	Schema
200	OK	Successfully found communication	CommunicationResponse
404	Not Found	Sent communication not found	ResponseErrorDto
500	Internal Server Error	Server error	ResponseErrorDto

Preview a communication

Preview a communication of certain type in the specified language for provided channels

POST /orgs/{org}/communications/preview

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name as it is registered in Mas-Stack
body	body	CommunicationRequestDto	true	Information needed to preview a communication

Request body - instance of CommunicationRequestDto

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


{
  "type": "password_reset",
  "language": "en",
  "channels": "[sms]",
  "scheduledTime": "2022-04-25T12:00:00",
  "smsInput": {
    "countryCode": "54",
    "terminatingNumber": "623196241"
  },
  "emailInput": {
    "destinationEmail": "recipient@masmovil.es",
    "destinationName": "Diego"
  },
  "externalId": "string",
  "arguments": {
    "name": "Juan",
    "subscriptions": [
      "ftth",
      "mobile",
      "health"
    ],
    "resetLink": "https://password.com/reset/123456",
    "birthDate": "2022-04-25 12:00:00",
    "vipClient": false,
    "balance": 45.7,
    "birthCountry": "US",
    "attached.txt": "SG9sYSBQYWJsbyA6KQo=",
    "embedded_image_png": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
    "qrArgument": "Text to convert into QR Code",
    "pdfAttachments": {
      "apple.pdf": "VGhpcyBpcyBhIFBERiBjb250ZW50",
      "pear.pdf": "VGhpcyBpcyBhIFBERiBjb250ZW50"
    }
  }
}

Name	Type	Required	Description
type	string	true	Communication type code according to the ones previously defined in the system
language	string	true	Communication language(ISO 639-1)
channels	[string]	false	Channels list through which the communication will be sent, allowed values are: “sms”, “email”. If not specified, all channels with a defined template are used
scheduledTime	string	false	Programmed time for the communication to be sent that can be reprogrammed to fit delivery window.
smsInput	CommunicationRequestSmsDto	false	Specific parameters needed for SMS channel, mandatory if SMS channel requested. No need to provide it when previewing a communication
emailInput	CommunicationRequestEmailDto	false	Specific parameters needed for email channel, mandatory if email channel requested. No need to provide it when previewing a communication
externalId	string	false	Client internal reference
arguments	object	false	Parameters and assigned values that are required to render the specified template. Depending on the argument type they can be a string, a number, a boolean or an array
» additionalProperties	object	false	Parameters and assigned values that are required to render the specified template. Depending on the argument type they can be a string, a number, a boolean or an array

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41



curl -X POST https://communications.masstack.com/v2/orgs/yoigo/communications/preview \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'type': 'password_reset',
  'language': 'en',
  'channels': '[sms]',
  'scheduledTime': '2022-04-25T12:00:00',
  'smsInput': {
    'countryCode': '54',
    'terminatingNumber': '623196241'
  },
  'emailInput': {
    'destinationEmail': 'recipient@masmovil.es',
    'destinationName': 'Diego'
  },
  'externalId': 'string',
  'arguments': {
    'name': 'Juan',
    'subscriptions': [
      'ftth',
      'mobile',
      'health'
    ],
    'resetLink': 'https://password.com/reset/123456',
    'birthDate': '2022-04-25 12:00:00',
    'vipClient': false,
    'balance': 45.7,
    'birthCountry': 'US',
    'attached.txt': 'SG9sYSBQYWJsbyA6KQo=',
    'embedded_image_png': 'iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==',
    'qrArgument': 'Text to convert into QR Code',
    'pdfAttachments': {
      'apple.pdf': 'VGhpcyBpcyBhIFBERiBjb250ZW50',
      'pear.pdf': 'VGhpcyBpcyBhIFBERiBjb250ZW50'
    }
  }
}" 

Responses

Code	Meaning	Description	Schema
200	OK	Communication previewed successfully	CommunicationPreviewResponse
206	Partial Content	The request could be successfully processed but some alteration in the process	CommunicationPreviewResponse
400	Bad Request	The response for client error when some field in the request is missing or invalid	ResponseErrorDto
500	Internal Server Error	Server error	ResponseErrorDto