BulkSMS Message API

A message record represents an SMS that has been sent or received. To send messages, create a `SubmissionEntry` and submit it to the Send Messages Operation. You can retrieve sent and received messages in a number of ways. ### Retrieving messages by status Messages are assigned a status as they progress through their lifecycle. You can use the List Messages Operation to filter by various statuses. For the status values used to filter, see the `status.type` and `status.subtype` values of the `Message` object. You supply a value for the `filter` query parameter following this pattern `status.type==SENT`. Since more than one messages are normally returned, you can also paginate the result using the `sortOrder` and `limit` query parameters. Note that `limit` is not the only way to limit the number of records. The result will also be limited by the `filter.submissionDate` property. The default value for this property is `NOW() - 7 days`. Messages can also be retrieved by the webhook mechanism. See the [webhooks page](/developer/webhooks/) for more information. ### Sending and receiving messages The examples shown in this section are for a single message submission. If you need to send a single text message to one or more recipients you will need to create a `SubmissionEntry` object and submit it to the Send Messages Operation. For more advanced submission types, make use of the [Send Messages Operation](#tag/message/POST/messages) which supports batch sending (by submitting an array) and scheduling (via the `schedule-date` query parameter). The following fields can be set for a `SubmissionEntry`: - the `to` field is required and contains the phone number or group details - the `body` field is required and contains the message content - other fields like `from`, `routingGroup`, `encoding`, etc. are optional ### Body Templates When sending a message you can use template fields to customise the message text. *Field based templates* allow you to create a message with place-holders for custom fields. Fields are identified by a zero based index; the first field is `F0`, the second is `F1` and so on. For example, if you want to send a message "Welcome Jack, you owe $200.00", supply the body as `"Welcome {F0######}, you owe {F1######}"` and send `"fields": ["Jack", "$200.00"]` in the relevant `to` entry. The `#` characters specify the maximum length of the field. If you are sending to contacts in your phonebook, you can use *Phonebook based templates*. The template for the contact's first name is `{fn######}` and the surname is `{sn######}`. See the [Send Messages Operation](#tag/message/POST/messages) for detailed examples.