openapi: 3.0.0
info:
  title: Message Search API
  version: 1.0.3
  description: >-
    The Messages API lets you retrieve messages you have sent via the SMS API by
    ID, as well as retrieve details of messages that were rejected.
  contact:
    name: Nexmo.com
    email: devrel@nexmo.com
    url: 'https://developer.nexmo.com/'
    x-twitter: Nexmo
  termsOfService: 'https://www.nexmo.com/terms-of-use'
  license:
    name: The MIT License (MIT)
    url: 'https://opensource.org/licenses/MIT'
  x-logo:
    url: 'https://twitter.com/Nexmo/profile_image?size=original'
  x-apiClientRegistration: 'https://dashboard.nexmo.com/sign-up'
servers:
  - url: 'https://rest.nexmo.com/search'
externalDocs:
  url: 'https://developer.nexmo.com/api/developer/messages'
  x-sha1: d8836c374e2a7504bd2cd59e05fcee440f67cb44
security:
  - apiKey: []
    apiSecret: []
paths:
  /message:
    get:
      summary: Get a single message
      description: >-
        Retrieve information about a single message that you sent using SMS API
        or that was received on your number.
      operationId: searchMessage
      parameters:
        - name: id
          in: query
          required: true
          description: The ID of the message you want to retrieve.
          example: 00A0B0C0
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/messageBase'
                  - $ref: '#/components/schemas/messageMT'
            application/xml:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/messageBase'
                  - $ref: '#/components/schemas/messageMT'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorJson'
            application/xml:
              schema:
                $ref: '#/components/schemas/errorXml'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
            application/xml:
              schema:
                $ref: '#/components/schemas/error'
  /messages:
    get:
      summary: Search messages
      description: >-
        Retrieve multiple messages that you sent using the SMS API or that were received
        on your number. You may provide one or more `ids` are specified, or both `date` and `number` 
        to identify the messages.
      operationId: searchMessages
      parameters:
        - name: ids
          in: query
          description: A message ID to search for. You can specify up to 10 message IDs to search for as query parameters.
          example: 'ids=123456789&ids=987654321'
          schema:
            type: string
        - name: date
          in: query
          description: >-
            The date the request to SMS API was submitted in the following
            format: `YYYY-MM-DD`
          example: '2020-01-01'
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: The phone number the message was sent to.
          example: '447700900000'
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messages'
            application/xml:
              schema:
                $ref: '#/components/schemas/messages'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorJson'
            application/xml:
              schema:
                $ref: '#/components/schemas/errorXml'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
            application/xml:
              schema:
                $ref: '#/components/schemas/error'
  /rejections:
    get:
      summary: Search for rejections
      description: >-
        Search for messages that have been rejected by Nexmo. Messages rejected
        by the carrier do not appear.
      operationId: searchRejections
      parameters:
        - name: date
          in: query
          description: >-
            The date the request to SMS API was submitted in the following
            format: `YYYY-MM-DD`
          required: true
          example: '2020-01-01'
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: The phone number the message was sent to.
          required: true
          example: '447700900000'
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rejections'
            application/xml:
              schema:
                $ref: '#/components/schemas/rejections'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorJson'
            application/xml:
              schema:
                $ref: '#/components/schemas/errorXml'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
            application/xml:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    messageBase:
      type: object
      description: Inbound (MO)
      required:
        - type
        - message-id
        - account-id
        - network
        - from
        - to
        - body
        - date-received
      xml:
        name: message
      properties:
        type:
          type: string
          description: >-
            The message type. `MT` (mobile terminated or outbound) or `MO`
            (mobile originated or inbound)
          example: MO
          enum:
            - MO
        message-id:
          type: string
          description: The id of the message you sent.
          example: 0A00000000ABCD00
        account-id:
          type: string
          description: Your API Key.
          example: API_KEY
        date-received:
          type: string
          description: >-
            The date and time at UTC+0 when Platform received your request in
            the following format: `YYYY-MM-DD HH:MM:SS`.
          example: '2020-01-01 12:00:00'
        network:
          type: string
          description: >-
            The [MCCMNC](https://en.wikipedia.org/wiki/Mobile_Network_Code) for
            the carrier who delivered the message.
          example: '012345'
        from:
          type: string
          description: >-
            The sender ID the message was sent from. Could be a phone number or
            name.
          example: Nexmo
        to:
          type: string
          description: The phone number the message was sent to.
          example: 447700900000
        body:
          type: string
          description: The body of the message.
          example: A text message sent using the Nexmo SMS API
    messageMT:
      description: Outbound (MT)
      type: object
      required:
        - type
        - message-id
        - account-id
        - network
        - from
        - to
        - body
        - date-received
        - price
        - final-status
        - date-closed
        - latency
      xml:
        name: message
      properties:
        type:
          type: string
          description: >-
            The message type. `MT` (mobile terminated or outbound) or `MO`
            (mobile originated or inbound)
          example: MT
          enum:
            - MT
        message-id:
          $ref: '#/components/schemas/messageBase/properties/message-id'
        account-id:
          $ref: '#/components/schemas/messageBase/properties/account-id'
        network:
          $ref: '#/components/schemas/messageBase/properties/network'
        from:
          $ref: '#/components/schemas/messageBase/properties/from'
        to:
          $ref: '#/components/schemas/messageBase/properties/to'
        body:
          $ref: '#/components/schemas/messageBase/properties/body'
        date-received:
          $ref: '#/components/schemas/messageBase/properties/date-received'
        price:
          type: number
          description: Price in Euros for a MT message.
          example: 0.0333
        date-closed:
          type: string
          description: >-
            The date and time at UTC+0 when Platform received the delivery
            receipt from the carrier who delivered the MT message. This
            parameter is in the following format `YYYY-MM-DD HH:MM:SS`.
          format: date-time
          example: '2020-01-01 12:00:00'
        latency:
          type: number
          description: >-
            The overall latency between `date-received` and `date-closed` in
            milliseconds.
          example: 3000
        client-ref:
          type: string
          maxLength: 40
          description: >-
            The [internal
            reference](https://developer.nexmo.com/api/sms#send-an-sms) you set
            in the request.
          example: my-personal-reference
        status:
          type: string
          description: >-
            A code that explains where the message is in the delivery process.
            If status is not `delivered` check `error-code` for more
            information. If status is `accepted` ignore the value of
            `error-code`.
          enum:
            - delivered
            - expired
            - failed
            - rejected
            - accepted
            - buffered
            - unknown
          x-ms-enum:
            name: status
            values:
              - value: delivered
                description: This message has been delivered to the phone number.
              - value: expired
                description: >-
                  The target carrier did not send a status in the 48 hours after
                  this message was delivered to them.
              - value: failed
                description: The target carrier failed to deliver this message.
              - value: rejected
                description: The target carrier rejected this message.
              - value: accepted
                description: The target carrier has accepted to send this message.
              - value: buffered
                description: This message is in the process of being delivered.
              - value: unknown
                description: The target carrier has returned an undocumented status code.
        final-status:
          type: string
          description: The status of `message-id` at `date-closed`.
          enum:
            - DELIVRD
            - EXPIRED
            - UNDELIV
            - REJECTD
            - UNKNOWN
          x-ms-enum:
            name: final-status
            values:
              - value: DELIVRD
                description: This message has been delivered to the phone number.
              - value: EXPIRED
                description: >-
                  The target carrier did not send a status in the 48 hours after
                  this message was delivered to them.
              - value: UNDELIV
                description: The target carrier failed to deliver this message.
              - value: REJECTD
                description: The target carrier rejected this message.
              - value: UNKNOWN
                description: The target carrier has returned an undocumented status code.
          example: DELIVRD
        error-code:
          $ref: '#/components/schemas/error-code'
        error-code-label:
          $ref: '#/components/schemas/error-code-label'
    messages:
      type: object
      properties:
        count:
          type: integer
          description: The number of messages included in the response.
        items:
          type: array
          description: The messages in the response.
          xml:
            wrapped: true
          items:
            type: object
            xml:
              name: message
            oneOf:
              - $ref: '#/components/schemas/messageBase'
              - $ref: '#/components/schemas/messageMT'
    rejections:
      type: object
      properties:
        count:
          type: integer
          description: The number of messages included in the response.
        items:
          type: array
          xml:
            wrapped: true
          items:
            type: object
            properties:
              account-id:
                $ref: '#/components/schemas/messageBase/properties/account-id'
              from:
                $ref: '#/components/schemas/messageBase/properties/from'
              to:
                $ref: '#/components/schemas/messageBase/properties/to'
              date-received:
                $ref: '#/components/schemas/messageBase/properties/date-received'
              error-code:
                $ref: '#/components/schemas/error-code'
              error-code-label:
                $ref: '#/components/schemas/error-code-label'
            xml:
              name: rejection
            required:
              - account-id
              - from
              - to
              - date-received
              - error-code
              - error-code-label
    error-code:
      type: string
      description: Will be set if the `status` is not `accepted`.
      example: '0'
      enum:
        - '0'
        - '1'
        - '2'
        - '3'
        - '4'
        - '5'
        - '6'
        - '7'
        - '8'
        - '9'
        - '10'
        - '11'
        - '12'
        - '13'
        - '14'
        - '15'
        - '99'
        - '400'
        - '401'
      x-ms-enum:
        name: error-code
        values:
          - value: '0'
            description: Delivered.
          - value: '1'
            description: >-
              Unknown - either; An unknown error was received from the carrier
              who tried to send this this message. _or_ Depending on the
              carrier, that `to` is unknown. When you see this error, and
              `status` is rejected, always check if `to` in your request was
              valid.
          - value: '2'
            description: >-
              Absent Subscriber Temporary - this message was not delivered
              because `to` was temporarily unavailable. For example, the handset
              used for `to` was out of coverage or switched off. This is a
              temporary failure, retry later for a positive result.
          - value: '3'
            description: >-
              Absent Subscriber Permanent - `to` is no longer active, you should
              remove this phone number from your database.
          - value: '4'
            description: >-
              Call barred by user - you should remove this phone number from
              your database. If the user wants to receive messages from you,
              they need to contact their carrier directly.
          - value: '5'
            description: >-
              Portability Error - there is an issue after the user has changed
              carrier for `to` If the user wants to receive messages from you,
              they need to contact their carrier directly.
          - value: '6'
            description: >-
              Anti-Spam Rejection - carriers often apply restrictions that block
              messages following different criteria. For example, on SenderID or
              message content.
          - value: '7'
            description: >-
              Handset Busy - the handset associated with `to` was not available
              when this message was sent. If `status` is `Failed` this is a
              temporary failure; retry later for a positive result. If `status`
              is `Accepted` this message has is in the retry scheme and will be
              resent until it expires in 24-48 hours.
          - value: '8'
            description: >-
              Network Error - a network failure while sending your message. This
              is a temporary failure, retry later for a positive result.
          - value: '9'
            description: >-
              Illegal Number - you tried to send a message to a blacklisted
              phone number. That is, the user has already sent a STOP opt-out
              message and no longer wishes to receive messages from you.
          - value: '10'
            description: >-
              Invalid Message - the message could not be sent because one of the
              parameters in the message was incorrect. For example, incorrect
              `type` or `udh`
          - value: '11'
            description: >-
              Unroutable - the chosen route to send your message is not
              available. This is because the phone number is either; Currently
              on an unsupported _or_ network. On a pre-paid or reseller account
              that could not receive a message sent by `from` To resolve this
              issue either email us at
              [support@nexmo.com](mailto:support@nexmo.com) or create a helpdesk
              ticket at [https://help.nexmo.com](https://help.nexmo.com).
          - value: '12'
            description: >-
              Destination unreachable - the message could not be delivered to
              the phone number.
          - value: '13'
            description: >-
              Subscriber Age Restriction - the carrier blocked this message
              because the content is not suitable for `to` based on age
              restrictions.
          - value: '14'
            description: >-
              Number Blocked by Carrier - the carrier blocked this message. This
              could be due to several reasons. For example, `to` s plan does not
              include SMS or the account is suspended.
          - value: '15'
            description: >-
              Pre-Paid - Insufficent funds - `to`’s pre-paid account does not
              have enough credit to receive the message.
          - value: '99'
            description: >-
              General Error - there is a problem with the chosen route to send
              your message. To resolve this issue either email us at
              [support@nexmo.com](mailto:support@nexmo.com) or create a helpdesk
              ticket at [https://help.nexmo.com](https://help.nexmo.com).
          - value: '400'
            description: wrong parameters
          - value: '401'
            description: authentication failed
    error-code-label:
      type: string
      description: A text label to explain `error-code`.
      example: Delivered
    error:
      type: object
      properties:
        error-code:
          $ref: '#/components/schemas/error-code'
        error-code-label:
          $ref: '#/components/schemas/error-code-label'
    errorJson:
      type: object
      properties:
        type:
          type: string
          example: BAD_REQUEST
        error_title:
          type: string
          example: Bad Request
        invalid_parameters:
          type: object
          additionalProperties:
            type: string
            example: Is required.
    errorXml:
      type: object
      xml:
        name: error
      properties:
        type:
          type: string
          example: BAD_REQUEST
        error_title:
          type: string
          example: Bad Request
        invalid_parameters:
          type: array
          items:
            type: object
            xml:
              name: entry
            properties:
              key:
                type: string
                example: date
              value:
                type: string
                example: Is required.
  securitySchemes:
    apiKey:
      type: apiKey
      name: api_key
      in: query
      description: >-
        You can find your API key in your [account
        overview](https://dashboard.nexmo.com/account-overview)
    apiSecret:
      type: apiKey
      name: api_secret
      in: query
      description: >-
        You can find your API secret in your [account
        overview](https://dashboard.nexmo.com/account-overview)
