> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List messages

> Returns a paginated list of SMS and MMS messages for the authenticated account, filtered by direction, date, and other criteria.



## OpenAPI

````yaml https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v3/messages
openapi: 3.1.0
info:
  title: Wavix APIs
  description: >-
    Wavix provides robust APIs that let you integrate voice and text messaging
    features directly into your app. Send text, place calls, and access detailed
    reports  programmatically.
  termsOfService: https://wavix.com/terms-and-conditions
  license:
    name: MIT
    identifier: MIT
  contact:
    name: Wavix
    url: https://wavix.com
    email: support@wavix.com
  version: '1.0'
servers:
  - url: https://api.wavix.com
    description: https://api.wavix.com
    variables: {}
security:
  - bearerAuth: []
tags:
  - name: SIP trunks
    description: SIP trunks
  - name: Buy
    description: Numbers
  - name: Cart
    description: Numbers
  - name: My numbers
    description: Numbers
  - name: Billing
    description: Billing, transactions, and invoices
  - name: Profile
    description: Account profile and customer information
  - name: CDRs
    description: Call detail records and call history
  - name: Speech Analytics
    description: Call transcription and speech analytics
  - name: SMS and MMS
    description: Messaging
  - name: Number Validator
    description: Phone number validation
  - name: Link shortener
    description: Short link and click metrics
  - name: 2FA
    description: Two-factor authentication
  - name: 10DLC
    description: 10DLC Campaigns and Brands
  - name: API Keys
    description: API key management
  - name: Call webhooks
    description: Webhook configuration for call events
  - name: Call control
    description: Programmable Voice
  - name: Call streaming
    description: Real-time call audio streaming over WebSocket
  - name: Call recording
    description: Call recording
  - name: Sub-accounts
    description: Sub-account management
  - name: Voice campaigns
    description: Outbound voice campaigns
  - name: Wavix Embeddable
    description: WebRTC embeddable widget
paths:
  /v3/messages:
    get:
      tags:
        - SMS and MMS
      summary: List messages
      description: >-
        Returns a paginated list of SMS and MMS messages for the authenticated
        account, filtered by direction, date, and other criteria.
      operationId: sms_and_mms_messages_list
      parameters:
        - name: sent_after
          in: query
          description: Returns messages sent on or after this date, in `YYYY-MM-DD` format.
          style: form
          explode: true
          schema:
            type: string
            example: '2023-04-10'
        - name: sent_before
          in: query
          description: >-
            Returns messages sent on or before this date, in `YYYY-MM-DD`
            format.
          style: form
          explode: true
          schema:
            type: string
            example: '2023-04-13'
        - name: type
          in: query
          description: >-
            Filters messages by direction. One of `inbound` (messages received
            by the account) or `outbound` (messages sent by the account).
          required: true
          style: form
          explode: true
          schema:
            type: string
            example: outbound
        - name: from
          in: query
          description: >-
            Filters by message sender. For `outbound` messages, the Sender ID
            used to send the message; for `inbound` messages, the originating
            phone number.
          style: form
          explode: true
          schema:
            type: string
            example: '15072429497'
        - name: to
          in: query
          description: >-
            Filters by message recipient. For `outbound` messages, the
            destination phone number; for `inbound` messages, an SMS-enabled
            number on the Wavix platform.
          style: form
          explode: true
          schema:
            type: string
            example: '16419252149'
        - name: status
          in: query
          description: >-
            Filters messages by delivery status. Accepts a
            `MessageDeliveryStatus` value.
          style: form
          explode: true
          schema:
            allOf:
              - $ref: '#/components/schemas/MessageDeliveryStatus'
        - name: tag
          in: query
          description: Filters messages by `tag`. Supported for outbound messages only.
          style: form
          explode: true
          schema:
            type: string
            example: campaignX
        - name: message_type
          in: query
          description: >-
            Filters messages by type. One of `sms` (text message) or `mms`
            (multimedia message).
          style: form
          explode: true
          schema:
            type: string
            enum:
              - sms
              - mms
            example: sms
        - name: page
          in: query
          description: Page number to retrieve. Default `1`.
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            example: 2
        - name: per_page
          in: query
          description: Number of records to return per page. Default `25`.
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            example: 50
      responses:
        '200':
          description: Returns a paginated list of messages.
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/MessageListResponse'
                  - example:
                      items:
                        - charge: '0.0475'
                          delivered_at: '2023-08-29T12:32:45.000Z'
                          direction: outbound
                          error_message: null
                          from: Sender ID.
                          mcc: '234'
                          message_body:
                            text: Please call me back
                            media: null
                          message_id: 3a525ca2-6909-4c72-9399-905adf7f3a74
                          message_type: sms
                          mnc: '024'
                          segments: 1
                          sent_at: '2023-08-29T12:32:44.000Z'
                          status: delivered
                          submitted_at: '2023-08-29T12:32:44.000Z'
                          carrier_fees: '0.0'
                          tag: null
                          to: '447537151866'
                      pagination:
                        current_page: 1
                        per_page: 10
                        total: 1
                        total_pages: 1
              examples:
                success:
                  summary: Successful response
                  value:
                    items:
                      - charge: '0.0475'
                        delivered_at: '2023-08-29T12:32:45.000Z'
                        direction: outbound
                        error_message: null
                        from: Sender ID.
                        mcc: '234'
                        message_body:
                          text: Please call me back
                          media: null
                        message_id: 3a525ca2-6909-4c72-9399-905adf7f3a74
                        message_type: sms
                        mnc: '024'
                        segments: 1
                        sent_at: '2023-08-29T12:32:44.000Z'
                        status: delivered
                        submitted_at: '2023-08-29T12:32:44.000Z'
                        carrier_fees: '0.0'
                        tag: null
                        to: '447537151866'
                    pagination:
                      current_page: 1
                      per_page: 10
                      total: 1
                      total_pages: 1
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
      deprecated: false
      security:
        - bearerAuth:
            - messages:read
components:
  schemas:
    MessageDeliveryStatus:
      title: MessageDeliveryStatus
      enum:
        - accepted
        - pending
        - sent
        - delivered
        - undelivered
        - expired
        - rejected
        - dlr_expired
      type: string
      description: >-
        Current delivery status of the message. One of:


        - `accepted` — the message was accepted by the platform for sending.

        - `pending` — the message is queued and awaiting a carrier response.

        - `sent` — the message was handed to the carrier.

        - `delivered` — the carrier confirmed delivery to the handset.

        - `undelivered` — the carrier reported that delivery failed.

        - `expired` — the validity period elapsed before the message was sent.

        - `rejected` — the message was rejected before sending.

        - `dlr_expired` — no delivery receipt arrived from the carrier within
        the expected window.
    MessageListResponse:
      title: MessageListResponse
      required:
        - items
        - pagination
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          description: Messages that match the request.
          items:
            $ref: '#/components/schemas/Message'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Message:
      title: Message
      required:
        - message_id
        - message_type
        - from
        - to
        - direction
        - mcc
        - mnc
        - message_body
        - tag
        - status
        - segments
        - charge
        - submitted_at
        - sent_at
        - delivered_at
        - error_message
      type: object
      additionalProperties: false
      properties:
        message_id:
          type: string
          description: Message ID.
          example: 871b4eeb-f798-4105-be23-32df9e991456
        message_type:
          type: string
          description: Message type. Possible values are `sms` or `mms`
          example: sms
        from:
          type: string
          description: Sender ID. Can be numeric or alphanumeric.
          example: Wavix
        to:
          type: string
          description: Recipient phone number.
          example: '447537151866'
        carrier_fees:
          type: string
          description: Carrier fees for the message in USD.
          format: float
          example: '0.0'
        direction:
          type: string
          description: Message direction. Possible values are `outbound` or `inbound`.
          example: outbound
        mcc:
          type:
            - string
            - 'null'
          description: Mobile country code.
          example: '301'
        mnc:
          type:
            - string
            - 'null'
          description: Mobile network code.
          example: '204'
        message_body:
          $ref: '#/components/schemas/MessageBody'
        tag:
          type:
            - string
            - 'null'
          description: Tag to group messages, such as for a specific campaign.
          example: Fall sale
        status:
          $ref: '#/components/schemas/MessageDeliveryStatus'
        segments:
          type: integer
          description: Number of SMS segments. Always 1 for MMS.
          format: int32
          example: 1
        charge:
          type: string
          description: Total charge for the message in USD.
          example: '0.01'
        submitted_at:
          type: string
          description: Date and time the message was accepted in ISO 8601 format.
          example: '2022-04-14T13:51:16.096Z'
        sent_at:
          type:
            - string
            - 'null'
          description: >-
            Date and time the message was sent in ISO 8601 format. For mobile
            terminated messages only.
          example: '2022-04-14T13:51:16.096Z'
        delivered_at:
          type:
            - string
            - 'null'
          description: >-
            Date and time the message was delivered in ISO 8601 format. Refers
            to DLR reception for mobile-terminated messages
             or webhook relay for mobile-originated messages.
          example: '2022-04-14T13:51:16.096Z'
        error_message:
          type:
            - string
            - 'null'
          description: A human-readable error description.
      description: SMS or MMS message.
      example:
        message_id: 871b4eeb-f798-4105-be23-32df9e991456
        message_type: sms
        from: Wavix
        to: '447537151866'
        direction: outbound
        mcc: '301'
        mnc: '204'
        message_body:
          text: Hi there, this a message from Wavix
          media: null
        tag: Fall sale
        status: delivered
        segments: 1
        charge: '0.01'
        submitted_at: '2022-04-14T13:51:16.096Z'
        sent_at: '2022-04-14T13:51:16.096Z'
        delivered_at: '2022-04-14T13:51:16.096Z'
        error_message: ''
    Pagination:
      title: Pagination
      required:
        - current_page
        - per_page
        - total
        - total_pages
      type: object
      additionalProperties: false
      properties:
        current_page:
          type: integer
          description: Current page number.
          format: int32
          example: 2
        per_page:
          type: integer
          description: Number of records per page.
          format: int32
          example: 25
        total:
          type: integer
          description: Total number of records.
          format: int32
          example: 101
        total_pages:
          type: integer
          description: Total number of pages.
          format: int32
          example: 5
    ValidationErrorResponse:
      title: ValidationErrorResponse
      type: object
      properties:
        success:
          type: boolean
          description: >-
            Indicates whether the request was successful. Always `false` for
            this error.
          example: false
        message:
          type: string
          description: >-
            Human-readable description naming the missing or invalid request
            parameter.
          example: Missing or invalid parameter <param_name>
    ForbiddenErrorResponse:
      title: ForbiddenErrorResponse
      type: object
      properties:
        success:
          type: boolean
          description: >-
            Indicates whether the request was successful. Always `false` for
            this error.
          example: false
        message:
          type: string
          description: Human-readable description of why access is forbidden.
          example: The service is not provisioned for your account.
    MessageBody:
      title: MessageBody
      required:
        - text
        - media
      type: object
      additionalProperties: false
      properties:
        text:
          type: string
          description: Message text.
          example: Hi there, this is a sample message
        media:
          maxItems: 5
          minItems: 0
          type:
            - array
            - 'null'
          items:
            type: string
          description: |-
            List of media URLs.
             If provided, the message is sent as an MMS;
              otherwise, it is sent as an SMS.
          example:
            - https://you-site.com/media
  responses:
    BadRequestErrorResponse:
      description: Request failed. Missing or invalid parameter <param_name>
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
    ForbiddenErrorResponse:
      description: Request failed. The feature is disabled for your account.
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Wavix API key. Pass as `Authorization: Bearer <api_key>`. Keys support
        per-resource scopes (none / read / write). See [Restricted keys and
        scopes](https://docs.wavix.com/api-reference/authentication#restricted-keys-and-scopes).

````