--- title: "Send Messages" method: POST path: "/messages" tags: ["Message"] --- # Send Messages `POST /messages` Send messages to one or more recipients. You can post up to `50,000` messages in a batch. But note that the `deduplication-id` is set per submission, so it is recommended that you use a smaller number, like `4000` per submission in order to make resubmissions on network failures more practical. #### Repliability When a sent message is _repliable_, the BulkSMS system can process an SMS response sent by your recipient. The message sent by your customer is called a mobile originating (MO) message and would be available under `RECEIVED` messages. You can obtain a list of MOs using the [retrieve messages API call](#tag/Message%2Fpaths%2F~1messages%2Fget). In addition you can also get a list of the MOs that are associated with a specific sent message (see the [list related messages API call](#tag/Message%2Fpaths%2F~1messages~1%7Bid%7D~1relatedReceivedMessages%2Fget)). If you use a specific _sender id_ in the `from` property of the send message, the message will not be repliable. If you want a message to be repliable, you need to specify `REPLIABLE` in the `from.type` property. If you do not set the `from` property, your account settings are considered to determine whether or not the message is repliable. If the _default repliable_ setting on your account is _yes_ then the message will be repliable. If this setting is _no_, the message will not be repliable. #### 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, let's say you want to send a daily SMS message to all your clients that tell them what their current balance is. The `body` of the message could look something like this ``` Good morning {F0######}, your balance is {F1######} ``` In this message, the first field, `F0`, is the name of the customer and he second field `F1` is the balance for that customer. The `#` used to specify the maximum length of the field. Note that the maximum length allowed for the value includes the space taken by the braces, template name and hash symbol. For example, the value `{F0#}` specifies a maximum length of `5`. If the data is longer than this length, the data will be truncated when the message body is constructed. The data fields are provided in the property named `fields` in the `to` element. Here is a complete example of how this might look ``` { "body": "Good morning {F0######}, your balance is {F1######}", "to": [ {"address": "27456789","fields": ["Harry", "$1345.23"] }, {"address": "27456785","fields": ["Sally", "$2345.58"] } ] } ``` If you are sending to contacts (or to groups) in your phonebook, you can use the *Phonebook based templates*. These are similar to the templates described above, but they have specific names. The template for the contact's first name is identified by `fn` and the template for the contact's surname is identified by `sn`. Below in an example that will work if the numbers are registered in your phonebook. ``` { "body": "Hi {fn######} {sn######}, have a great day!", "to": [ {"address": "27456789" }, {"address": "27456785" } ] } ``` ## Query parameters - `deduplication-id` integer - `auto-unicode` boolean - `schedule-date` string, date-time - `schedule-description` string ## Request body - SubmissionEntry[] - `from` object — Identifies the sender. Instead of a structured object, you can supply a string value here. If you do this, the `type` of the sender is derived to be either INTERNATIONAL or ALPHANUMERIC. If the value does not begin with a `+` and it contains at least one character that is not a digit, the type is detected as ALPHANUMERIC. Otherwise, the type is detected as INTERNATIONAL. - `type` 'INTERNATIONAL' | 'ALPHANUMERIC' | 'SHORTCODE' | 'REPLIABLE', required — The type of the sender id. If you want BulkSMS to collect replies to this message on your behalf, specify the type as REPLIABLE. If the recipient is in a country where BulkSMS does not have a local reply number, the reply may incur costs that are more expensive than sending a local SMS in that country. If you operate a service from a shortcode in a locale that allows messaging from such a shortcode, you can specify SHORTCODE for the type. - `address` string — The address of the sender id. The validation for this field depends on the value of the `type`. INTERNATIONAL can start with `+`. It has a maximum length of 15 digits, and has to be longer than 6 digits. ALPHANUMERIC has a maximum length of 11 characters. SHORTCODE has a maximum length of 6 digits. REPLIABLE should not specify a value here. - `to` object[], required — Identifies the recipients Instead of an array of structured objects, you can also provide a single object, a simple string or an array of strings. If you supply a string, the `type` is taken as INTERNATIONAL. - `type` 'INTERNATIONAL' | 'GROUP' — Type of the recipient. The default value is INTERNATIONAL. - `address` string — The phone number of the recipient. It must be supplied if the `type` is INTERNATIONAL - `name` string — The name of a group in your phonebook. A value can be given if the `type` is GROUP. - `id` string — The id of a group in your phonebook. A value can be given if the `type` is GROUP. - `fields` string[] — Custom fields that can be used in the message body. A value can be given if the `type` is INTERNATIONAL Read the [body templates section](#tag/Message) for more information. - `routingGroup` 'ECONOMY' | 'STANDARD' | 'PREMIUM' — Allows you to choose routing. The default is STANDARD. - `encoding` 'TEXT' | 'UNICODE' | 'BINARY' — Describes the content of the message body. Typically this is TEXT, which is the default if no value is provided. If you need to send characters that are not covered by the [GSM 03.38](https://en.wikipedia.org/wiki/GSM_03.38) character set you will need to specify UNICODE. If you want to send a sequence of bytes, you must use BINARY. You can also or use the `auto-unicode` parameter of the Send Messages Operation. If you supply the value of `TEXT` while `auto-unicode` is `true` then your message may be converted to `UNICODE`. If you supply a value other than `TEXT` for this property while `auto-unicode` is `true` then no automatic conversion will take place. - `longMessageMaxParts` integer — The maximum number of message parts that can be used for a [concatenated message](https://en.wikipedia.org/wiki/Concatenated_SMS). The default is `3`. - `body` string, required — The message content as described in the `encoding`. If the `encoding` is BINARY, the body must contain only hexadecimal digits where one byte is represented as two digits. For example, if you want to send two bytes '0x05' and '0x1F', the message body must contain the text '051F'. The message content can also contain templates, read the [body templates section](#tag/Message) for more information. - `userSuppliedId` string — Correlate the messages created from this submission to your data. The value can contain no more than 20 characters. - `protocolId` 'IMPLICIT' | 'SHORT_MESSAGE_TYPE_0' | 'REPLACE_MESSAGE_1' | 'REPLACE_MESSAGE_2' | 'REPLACE_MESSAGE_3' | 'REPLACE_MESSAGE_4' | 'REPLACE_MESSAGE_5' | 'REPLACE_MESSAGE_6' | 'REPLACE_MESSAGE_7' | 'RETURN_CALL' | 'ME_DOWNLOAD' | 'ME_DEPERSONALIZE' | 'SIM_DOWNLOAD' — The TP-PID value from GSM 03.40[.750] §9.2.3.9. You can provide either an integer value, or a mnemonic string. If unspecified, this property defaults to `0`, representing the IMPLICIT value. Numeric values are listed below | Name | Value| |----- |------| | IMPLICIT | 00 | | SHORT_MESSAGE_TYPE_0 | 64 | | REPLACE_MESSAGE_1 | 65 | | REPLACE_MESSAGE_2 | 66 | | REPLACE_MESSAGE_3 | 67 | | REPLACE_MESSAGE_4 | 68 | | REPLACE_MESSAGE_5 | 69 | | REPLACE_MESSAGE_6 | 70 | | REPLACE_MESSAGE_7 | 71 | | RETURN_CALL | 95 | | ME_DOWNLOAD | 125 | | ME_DEPERSONALIZE | 126 | | SIM_DOWNLOAD | 127 | - `messageClass` 'FLASH_SMS' | 'ME_SPECIFIC' | 'SIM_SPECIFIC' | 'TE_SPECIFIC' — The class of the message, as specified by §4 of the GSM 03.38 specification. You can provide either an integer value, or a mnemonic string. The default value is SIM_SPECIFIC. Numeric values are | Name | Value| |------|------| | FLASH_SMS | 0 | | ME_SPECIFIC | 1 | | SIM_SPECIFIC | 2 | | TE_SPECIFIC | 3 | - `deliveryReports` 'ALL' | 'ERRORS' | 'NONE' — The type of delivery reports to request from the delivering network. The default value is `ALL`. Please note that not all networks support delivery reports. ALL. All possible delivery reports ERRORS. Only error delivery reports NONE. No delivery reports ## Response `201` An array of the messages that were created from the request - Message[] - `id` string, required — A unique identifier that is assigned when the message is created. - `type` 'SENT' | 'RECEIVED', required — The message direction - `from` string — The address part of the sender id - `to` string, required — The phone number of the recipient - `body` string, required — The content of the message - `encoding` 'TEXT' | 'UNICODE' | 'BINARY' — The type of the content. See the `encoding` field for more information. - `protocolId` integer — See the `protocolId` field for more information. - `messageClass` integer — See the `messageClass` field for more information. - `numberOfParts` integer — The number of parts. If this is a concatenated message, the number of parts will be more than 1. Note that this field does not have a value in the submission response. - `creditCost` number, float — The cost of the message (in credits). Note that this field does not have a value in the submission response. - `submission` object — Identifies the submission. - `id` string, required — A unique identity shared by all messages that were created from the same submission. This field should be ignored if the `type` is not SENT. - `date` string, date-time, required — The date and time the submission was processed. If the `type` is RECEIVED, this field reflects the date and time the received message was processed. - `status` object, required — The status of the message - `id` string, required — A concatenated value A.B where A is the `status.type` and B is the `status.subtype`. It there is no value for `subtype` then B takes string value `"null"` (e.g. `"SENT.null"`). - `type` 'ACCEPTED' | 'SCHEDULED' | 'SENT' | 'DELIVERED' | 'UNKNOWN' | 'FAILED', required — ACCEPTED Message accepted for delivery. Only returned for initial message submissions. SCHEDULED Message accepted for delivery at a later date. Only returned for initial message submissions. SENT Message has been relayed away from our systems. DELIVERED Successfully delivered to phone. UNKNOWN Message is in an unknown state. FAILED Delivery failed. - `subtype` 'EXPIRED' | 'HANDSET_ERROR' | 'BLOCKED' | 'NOT_SENT' — Has a value only if the `type` is FAILED. EXPIRED Delivery failed because message expired before delivery was possible. HANDSET_ERROR Delivery failed because of a problem related to the phone (e.g. message storage area full). BLOCKED Your account has been blocked from sending to this phone (e.g. recipient replied STOP to block communication). NOT_SENT Message delivery was not attempted (e.g. because we were not able to find a route for the supplied phone number). - `relatedSentMessageId` string — This field has a value only if the type is RECEIVED. With SMS messages, it is not possible to link a reply directly with a specific sent message. However, if you specified `REPLIABLE` in the `from` property, BulkSMS will link any reply to the most recent message sent to a given phone number. The `relatedSentMessageId` property keeps the information about this link. You can use this property to derive an implicit conversation from a set of messages. - If a received reply message has a `relatedSentMessageId`, you can use it to retrieve the last message that was sent before the reply was received. - If you have the `id` of the sent message and you want all the received messages that relate to it, you can use the List Related Messages Operation. - `userSuppliedId` string — This is the value you supplied in the `userSuppliedId` field. Has a value only if the `type` is SENT. ## Other responses - `400` — Bad Request. The content or structure of your submission, or a parameter, was found to be invalid. - `403` — Forbidden. Inspect the body of the response for further details - for example, you may have insufficient credits remaining --- [API](https://skmtc.net/bulksms/apis/bulksms-json-rest-api.md) · [All operations](https://skmtc.net/bulksms/apis/bulksms-json-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bulksms/bulksms-json-rest-api/versions/f923d2ecca43/schema)