action bulksms_get_messages {
  label: "Retrieve Messages"
  description: "Retrieve the messages you have sent or received.  \n\nScheduled messages are available for retrieval only after the delivery date.\n\nAll the parameters are optional.  If a value is not supplied for `filter`, the messages are not filtered.\n\nMessages 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.\nFor a numeric filter field, you can also use the less than operator (`<`).\n\nIf 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).\n\nFor 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\n```\ntype%3DSENT&submission.id%3D1-00000000000522347562\n```\nBecause `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.\n\nUsing the previous example to illustrate; after encoding and encasing it, the clauses are transformed into a request that looks like this\n```\nGET /v1/messages?filter=type%3DSENT%26submission.id%3D1-00000000000522347562\n```\nIf 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.\n\nThe table below lists the fields available for filtering\n\n| Field | Type   | Values | Note and example |\n|-------|------|--------------------|------|\n| 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. <br/>`filter=id<123456` |\n| type          | String  | SENT, RECEIVED  | SENT are Mobile Terminating (MT) SMSs; RECEIVED are Mobile Originating (MO) SMSs.<br/>`filter=type%3DSENT` |\n| submission.id | String  |  | `filter=submission.id%3D1-00000000000522347562` |\n| status.type   | String  | ACCEPTED, SENT, DELIVERED, FAILED  | See the message `status.type` field for more information. <br/>`filter=status.type%3DDELIVERED` |\n| status.id| String  |  | See the message `status.id` field for more information. `filter=status.id%3DFAILED.EXPIRED`|\n| 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. <br/>`filter=submission.date%3E%3D2017-01-01T10%3A00%3A00%2B01%3A00` |\n| userSuppliedId  | String | | Use a string value you specified in the `userSuppliedId` property when you sent the message. Only `SENT` messages will be retrieved. <br/>`filter=userSuppliedId%3Dacc009876` |\n"
  provider: bulksms
  method: GET
  path: "/messages"
  encoding: json
  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"
        }
      }
    }
  }
}