--- title: "Retrieve Messages" method: GET path: "/messages" tags: ["Message"] --- # Retrieve Messages `GET /messages` Retrieve the messages you have sent or received. Scheduled messages are available for retrieval only after the delivery date. All the parameters are optional. If a value is not supplied for `filter`, the messages are not filtered. Messages can be filtered by supplying query clauses in the `filter` parameter. Each clause has the form `name=value` where `name` is the name of a filter field and `value` is a valid value for that field. A value for a field is optional. Include a clause for a field in the filter only when there is a need to fetch messages that match some value for that field. For a numeric filter field, you can also use the less than operator (`<`). If present, the filter value must have at least one clause, but it can contain a combination of clauses. Multiple clauses are separated with the `&` symbol. Semantically, multiple clauses form a [logical conjunction](https://en.wikipedia.org/wiki/Logical_conjunction). For example, if you want to list all messages that were sent as part of a particular submission, your filter contains two clauses and will look something like this ``` type%3DSENT&submission.id%3D1-00000000000522347562 ``` Because `filter` is a request parameter, it is important to note that the value for this parameter must be *URL encoded*. In particular, the `=` encodes to `%3D` and the `&` encodes to `%26`. Note that you do not have to encode the `<` character. Using the previous example to illustrate; after encoding and encasing it, the clauses are transformed into a request that looks like this ``` GET /v1/messages?filter=type%3DSENT%26submission.id%3D1-00000000000522347562 ``` If the field name or the field value of a clause is not valid, a [bad_request error](errors#bad-request) is returned instead of the usual result. The `detail` field of this error provides more information about the problem. The table below lists the fields available for filtering | Field | Type | Values | Note and example | |-------|------|--------------------|------| | id | Integer | Positive integer | Use the `id` field with `<` (or with `>`) to fetch messages that are older (or newer) than those that are already fetched.
`filter=id<123456` | | type | String | SENT, RECEIVED | SENT are Mobile Terminating (MT) SMSs; RECEIVED are Mobile Originating (MO) SMSs.
`filter=type%3DSENT` | | submission.id | String | | `filter=submission.id%3D1-00000000000522347562` | | status.type | String | ACCEPTED, SENT, DELIVERED, FAILED | See the message `status.type` field for more information.
`filter=status.type%3DDELIVERED` | | status.id| String | | See the message `status.id` field for more information. `filter=status.id%3DFAILED.EXPIRED`| | submission.date | String | Formatted Date | A fully specified date (e.g. 2017-01-01T10:00:00+01:00). Use this field with `<=`, `<`, `>` or `>=` to limit the values.
`filter=submission.date%3E%3D2017-01-01T10%3A00%3A00%2B01%3A00` | | userSuppliedId | String | | Use a string value you specified in the `userSuppliedId` property when you sent the message. Only `SENT` messages will be retrieved.
`filter=userSuppliedId%3Dacc009876` | ## Query parameters - `limit` number - `filter` string - `sortOrder` 'ASCENDING' ## Response `200` Contains the requested array of messages - 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. --- [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)