Retrieve Messages

v1.0.0

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 .

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

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

If the field name or the field value of a clause is not valid, a bad_request error [blocked] 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`

Input

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string"
    },
    "limit": {
      "type": "number",
      "format": "int"
    },
    "sortOrder": {
      "type": "string",
      "enum": [
        "ASCENDING"
      ]
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "id",
      "type",
      "to",
      "body",
      "status"
    ],
    "properties": {
      "body": {
        "description": "The content of the message",
        "type": "object"
      },
      "creditCost": {
        "type": "number",
        "format": "float",
        "description": "The cost of the message (in credits).   Note that this field does not have a value in the submission response."
      },
      "encoding": {
        "type": "string",
        "description": "The type of the content.  See the `encoding` field for more information.",
        "enum": [
          "TEXT",
          "UNICODE",
          "BINARY"
        ]
      },
      "from": {
        "type": "string",
        "description": "The address part of the sender id"
      },
      "id": {
        "type": "string",
        "description": "A unique identifier that is assigned when the message is created."
      },
      "messageClass": {
        "type": "integer",
        "format": "int32",
        "description": "See the `messageClass` field for more information."
      },
      "numberOfParts": {
        "type": "integer",
        "format": "int32",
        "description": "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."
      },
      "protocolId": {
        "type": "integer",
        "format": "int32",
        "description": "See the `protocolId` field for more information."
      },
      "relatedSentMessageId": {
        "type": "string",
        "description": "This field has a value only if the type is RECEIVED.\nWith 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.\n\nThe `relatedSentMessageId` property keeps the information about this link.\n\nYou can use this property to derive an implicit conversation from a set of messages.\n  - 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.\n  - 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.\n"
      },
      "status": {
        "type": "object",
        "description": "The status of the message",
        "required": [
          "id",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "A concatenated value A.B where A is the `status.type` and B is the `status.subtype`.  \nIt there is no value for `subtype` then B takes string value `\"null\"` (e.g. `\"SENT.null\"`).   \n"
          },
          "subtype": {
            "type": "string",
            "description": "Has a value only if the `type` is FAILED.\n\nEXPIRED  Delivery failed because message expired before delivery was possible.\n\nHANDSET_ERROR  Delivery failed because of a problem related to the phone (e.g. message storage area full).\n\nBLOCKED  Your account has been blocked from sending to this phone (e.g. recipient replied STOP to block communication).\n\nNOT_SENT  Message delivery was not attempted (e.g. because we were not able to find a route for the supplied phone number).\n",
            "enum": [
              "EXPIRED",
              "HANDSET_ERROR",
              "BLOCKED",
              "NOT_SENT"
            ]
          },
          "type": {
            "type": "string",
            "description": "\nACCEPTED  Message accepted for delivery. Only returned for initial message submissions.\n\nSCHEDULED  Message accepted for delivery at a later date. Only returned for initial message  submissions.\n\nSENT  Message has been relayed away from our systems.\n\nDELIVERED  Successfully delivered to phone.\n\nUNKNOWN  Message is in an unknown state.\n\nFAILED  Delivery failed.\n",
            "enum": [
              "ACCEPTED",
              "SCHEDULED",
              "SENT",
              "DELIVERED",
              "UNKNOWN",
              "FAILED"
            ]
          }
        }
      },
      "submission": {
        "type": "object",
        "description": "Identifies the submission.\n",
        "required": [
          "id",
          "date"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "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."
          },
          "id": {
            "type": "string",
            "description": "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."
          }
        }
      },
      "to": {
        "type": "string",
        "description": "The phone number of the recipient"
      },
      "type": {
        "type": "string",
        "description": "The message direction",
        "enum": [
          "SENT",
          "RECEIVED"
        ]
      },
      "userSuppliedId": {
        "type": "string",
        "description": "This is the value you supplied in the `userSuppliedId` field.\nHas a value only if the `type` is SENT.\n"
      }
    }
  }
}