Send a message to your subscribers via text messaging (SMS/MMS) or email.
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.
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. |
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. |
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.
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());
}
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.
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. |
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. |