NAV

Message API(Last Updated : 01/11/2017)

Send a message to your subscribers via text messaging (SMS/MMS) or email.

Sending Message

You can send messages to multiple Distribution Lists or Subscriptions. You must pass the following parameters to the function to send a message. For more details you can refer to the REST API Documentations.

Fields

Field Name Description
Description Description of the message for your reference.
Messages per each Channel A message for at least one channel (SMS/MMS/email) must be specified. Refer to the Channels Object below.
Organization name ID The ID of the organization name you wish to use for your message. Only verified organization names can be used.
Scheduled Message time The scheduled date and time for your message.
Recipients The IDs of the lists or subscriptions that should receive the message.
Default values for Mail merge You can specify a replacement value for null data if your message contains mail merge variables such as first name and last name.

SMS Object

Field Name Description
Message Content for the SMS.

MMS Object

Field Name Description
Subject Subject for the MMS.
Message Content for the MMS.
Resource The URL for the media file you would like to include in your MMS message.

Email Object

Field Name Description
Subject Subject of the email.
Body Content for the email message.
Reply to Email address that will receive responses.
Shareable Toggles the presence of a "Share on Social Sites" link in the footer of your email.
Forwardable Toggles the presence of a "Forward Email" link in the footer of your email.

ApiClient apiClient = ... ApiContext apiContext = ... Message message = new Message.Builder() .description("My first message via SDK") .email(/*subject*/ "Greetings", /*message*/ "Hello World!") .sms(/*message*/ "Hello World!") .mms(/*subject*/ "Greetings", /*message*/ "Hello World!") .recipients(Message.Subscriptions.of(12345L, 67890L)) // For distribution lists //.recipients(Message.DistributionLists.of(23456L, 78901L)) .build(); try { MessageCompositionResult result = MessageApi.with(apiContext) .compose(message) .executeOn(apiClient); // Process with result... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The returned MessageCompositionResult object contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getId(): long Message ID The message's unique ID number.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.

Final results will be pushed to the URL that you specified via Push Notifications. For more details, please refer to this page.

Retrieve Information for a Specific Message

Once you have a Message ID, additional details can be retrieved for the message.

ApiClient apiClient = ... ApiContext apiContext = ... try { long messageId = 12345L; MessageInfo messageInfo = MessageApi.with(apiContext) .get(messageId) .executeOn(apiClient); // Process with message info... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The returned MessageInfo object contains the following fields:

Fields

Method Name Data Returned Description
getStatus(): String status Status of the message (sent/sending/scheduled/canceled).
getCreatedAt(): DateTime createdAt Time the message was created.
getProcessedAt(): DateTime prossedAt Time the message was processed.
getScheduledAt(): DateTime scheduledAt Scheduled time of the message.
getEmailSendingStatus(): MessageInfo.SendingStatus emailSendingStatus Status of the sent email message.
getSmsSendingStatus: MessageInfo.SendingStatus smsSendingStatus Status of the sent SMS message.
getUsedCreditInfo(): MessageInfo.UsedCreditInfo usedCredit Amount of domestic/international credits used for the message.
getCoupons(): List<MessageInfo.CouponInfo> Coupon List of coupons issued in the message.

Retrieve Scheduled Messages

You can retrieve scheduled messages after creation. When creating the request, you must pass the following parameters:

Fields

Field Name Description
Order The chronological order of the retrieved messages.
Offset This is the offset for the list. The value specified here will be the number of messages skipped in the retrieval.
Limit The limit is the number of items in the response.

ApiClient apiClient = ... ApiContext apiContext = ... try { long messageId = 12345L; ScheduledMessagesInfo messagesInfo = MessageApi.with(apiContext) .listAllScheduled(0, 20) // You can specify the order you want //.listAllScheduled(0, 20, Ordering.of(SortableField.SCHEDULED_AT, Order.DESC)) .executeOn(apiClient); int totalCount = messagesInfo.getTotalCount(); List<ScheduledMessageSummary> messageInfoList = messagesInfo.getMessages(); // Process with message info... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The returned ScheduledMessagesInfo object contains the following fields:

Fields

Method Name Data Returned Description
getTotalCount(): int totalCount Number of messages retrieved in the response.
getMessages(): List<ScheduledMessageSummary> ScheduledMessageInfo Detailed information for each retrieved message. See Scheduled Message Information Object below.

Scheduled Message Information Object

Method Name Data Returned Description
getMessageId(): long messageId The message's unique ID number.
getDescription(): String description Description of the message for your reference.
getScheduledAt(): DateTime scheduledAt Scheduled message time.
getSmsCount(): int smsCount Number of scheduled SMS messages.
getMmsCount(): int mmsCount Number of scheduled MMS messages.
getEmailCount(): int emailCount Number of scheduled email messages.

Cancel Scheduled Message

The following is an example of how you can cancel scheduled messages:

ApiClient apiClient = ... ApiContext apiContext = ... try { long scheduledMessageId = 12345L; MessageCancellationResult result = MessageApi.with(apiContext) .cancelScheduled(scheduledMessageId) .executeOn(apiClient); // Process with result... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The returned BasicApiResult object contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.

Final results will be pushed to the URL that you specified via Push Notifications. For more details, please refer to this page.

Report Retrieval

You can retrieve the status of your message creation/update/deletion request. The following example shows how you can use the Result object from your API request to make a call which will fetch the status of that request.

ApiClient apiClient = ... ApiContext apiContext = ... try { MessageCompositionResult compositionResult = MessageApi.with(getApiContext()) .compose(message) .executeOn(getApiClient()); VariableResult<MessageCompositionReport, ApiStatusReport> report = compositionResult.getReportRequest(getApiContext()) .executeOn(getApiClient()); // Process the report... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

VariableResult

After retrieving the report, you will receive an VariableResult object that is either a success or a failure status. For more details please refer to the javadoc.

Message Sent Report

If the message was sent successfully, a report request will return a VariableResult object with a MessageCompositionReport object which contains the following fields:

Fields

Method Name Data Returned Description
getStatus(): String status Status of the message (sent/sending/scheduled/canceled).
getCreatedAt(): DateTime createdAt Time the message was created.
getProcessedAt(): DateTime prossedAt Time the message was processed.
getScheduledAt(): DateTime scheduledAt Scheduled time of the message.
getEmailSendingStatus(): MessageInfo.SendingStatus emailSendingStatus Status of the sent email message.
getSmsSendingStatus: MessageInfo.SendingStatus smsSendingStatus Status of the sent SMS message.
getUsedCreditInfo(): MessageInfo.UsedCreditInfo usedCredit Amount of domestic/international credits used for the message.
getCoupons(): List<MessageInfo.CouponInfo> Coupon List of coupons issued in the message.

If the message was not sent successfully, a report request will return a VariableResult object with a ApiStatusReport object which contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getPushId(): long Push ID The key for the specific push message.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.
Scheduled Message Cancel Report

If the message was canceled successfully, a report request will return a VariableResult object with a MessageCancellationReport object which contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getMessageId(): long Message ID The message’s unique ID number.

If the message was not canceled successfully, a report request will return a VariableResult object with a ApiStatusReport object which contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.