SmsMessage v1.2

Describes the content and supporting attributes of an SMS message.

What can I do with smsMessage?

Tasks require messages when scheduling a send to your subscribers:

  • A message_id must be provided when creating a new task.
  • A message is not editable if a task references its id. Filter by editable to show a list of messages which can or cannot be modified.
  • You can sort and filter messages by the name field.
  • Messages can be created for both email and SMS channels.

Concatenation and credits

An smsMessage can be a standard message (1 part) or a concatenated message comprising of 2 or 3 parts.

  • 1 part - approx. 160 GSM characters = 1 credit per recipient.
  • 2 parts - approx. 306 GSM characters = 2 credits per recipient.
  • 3 parts - approx. 459 GSM characters = 3 credits per recipient.

If true, the subinfo attribute will add 30 bytes to your total message length.

SMS Network quirks

Some SMS networks (also known as gateways or aggregators) have unique quirks which may affect your integration:

  • Some networks ignore non-alphanumeric characters in fromname (characters other than [a-zA-Z0-9] may be omitted).
  • Optus (AU only) has a specific policy on alphanumeric fromname. Any alphanumeric fromname which contains characters other than [a-zA-Z0-9] will be overwritten with a random AU MSISDN.

GET /smsMessage or /smsMessage/:id

AttributeTypeFilterSortDescription
id
intYesYesUnique ID of the message.
editable
intYesNoMessages are editable until a 'task' has been scheduled.
fromname
stringNoNoThe sender's display name - 11 alphanumeric characters or an MSISDN.
message
stringNoNoSMS message content.
name
stringYesYesName of the message - this attribute is for reference only and isn't sent.
subinfo
boolNoNoWhether to include SMS unsubscription information in the message. Default is 'false'.
used
boolYesNoWhether a message has been used in a scheduled task.
cdate
decimalNoYesCreation timestamp.
mdate
decimalNoNoLast modification timestamp.

HEAD /smsMessage or /smsMessage/:id

AttributeTypePresenceDescription
id
intOptionalUnique ID of the message.
editable
intOptionalMessages are editable until a 'task' has been scheduled.
name
stringOptionalName of the message - this attribute is for reference only and isn't sent.
used
boolOptionalWhether a message has been used in a scheduled task.

POST /smsMessage

AttributeTypePresenceDescription
fromname
stringRequiredThe sender's display name - 11 alphanumeric characters or an MSISDN.
message
stringRequiredSMS message content.
name
stringRequiredName of the message - this attribute is for reference only and isn't sent.
subinfo
boolOptionalWhether to include SMS unsubscription information in the message. Default is 'false'.

Please note, personalisation is not currently supported in SMS messages.

PUT /smsMessage or /smsMessage/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the message.
fromname
stringOptionalThe sender's display name - 11 alphanumeric characters or an MSISDN.
message
stringOptionalSMS message content.
name
stringOptionalName of the message - this attribute is for reference only and isn't sent.
subinfo
boolOptionalWhether to include SMS unsubscription information in the message. Default is 'false'.

Please note, personalisation is not currently supported in SMS messages.

DELETE /smsMessage or /smsMessage/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the message.

If a message is referenced by a task when DELETE is issued, the associated task will not be cancelled. The message is made available to the task (soft deleted) but cannot be requested by any subsequent GET requests. In this case, it could be considered good practice to cancel a task before issuing the DELETE.

Error codes

CodeSubcodeMessageDescription
423
10
Message $id is lockedThis message is scheduled to be sent or has been sent.

Please see error handling for more information on error codes.

Examples

JSON response

{
    "id":                101010101,
    "editable":          false,
    "fromname":          "447101010101",
    "message"            "sms message",
    "name":              "Example sms",
    "subinfo":           true,
    "used":              true,
    "cdate":             1234966741,
    "mdate":             1234966741
 }