openapi: 3.0.1
info:
  title: Message status API
  description: API for querying SMS statistics and message details
  version: 3.1.0.10
servers:
  - url: https://sms-apistatus.namirialtsp.com/api
    description: Production environment
  - url: https://sms-apistatus.preprod.namirialtsp.com/api
    description: Pre-release staging environment
  - url: https://sms-apistatus.test.namirialtsp.com/api
    description: Development and testing environment
paths:
  /messagestatus/phonenumber/{phonenumber}:
    get:
      summary: Get latest SMS from phone number
      operationId: getLatestSmsFromNumber
      parameters:
        - name: phonenumber
          in: path
          description: Phone number in E.164 format (e.g., +1234567890).
          required: true
          schema:
            type: string
            example: '+1234567890'
        - name: sendDate
          in: query
          description: >-
            Filter messages sent before this timestamp (ISO 8601 format, e.g.
            `2026-12-31T23:59:59Z`). Defaults to current time if not specified.
          schema:
            type: string
            format: date-time
        - name: count
          in: query
          description: Maximum number of records to return (max 100)
          schema:
            type: integer
            format: int64
            default: 50
            maximum: 100
            minimum: 1
      responses:
        '200':
          description: SMS list for phone number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsStatisticsResponse'
              examples:
                withReference:
                  summary: Message with reference
                  value:
                    messages:
                      - message:
                          id: 54145623-7f65-4d02-b29d-106a42ca7a88
                          reference:
                            service: DIGITALSIGN
                            action: AUTH
                            key: ref-12345
                          channel: SMS
                          status: DELIVERED
                          providerAcceptanceAt: '2026-02-25T16:12:10Z'
                          statusChangedAt: '2026-02-25T16:12:15Z'
                          provider:
                            name: PROVIDER1
                            id: DSFGDF5gw45g3453
                            status: DELIVERED
                            code: '0'
                          sms:
                            segments: 1
                withoutReference:
                  summary: >-
                    Message without reference (reference not specified in send
                    request)
                  value:
                    messages:
                      - message:
                          id: e989c2ec-c476-4224-a2b3-f21c76b552bb
                          reference: {}
                          channel: SMS
                          status: DELIVERED
                          providerAcceptanceAt: '2026-02-26T21:47:22Z'
                          statusChangedAt: '2026-02-26T21:47:30Z'
                          provider:
                            name: PROVIDER2
                            id: 381b43c9-fff1-cf1e-b15c-e8f387f2d49f
                            status: DELIVERED
                            code: '0'
                          sms:
                            segments: 1
                emptyResult:
                  summary: No messages found
                  value:
                    messages: []
        '400':
          description: Bad request
        '403':
          description: Forbidden. The API key is missing or invalid.
        '500':
          description: Internal server error
      tags:
        - MessageStatus
      description: >-
        Retrieves the delivery status of the latest messages sent to a given
        phone number.
  /messagestatus/reference/{referencekey}:
    get:
      summary: Get latest SMS from reference key
      operationId: getLatestSmsFromReferenceKey
      parameters:
        - name: referencekey
          in: path
          description: >-
            External key specified in the `reference.key` parameter of the send
            request.
          required: true
          schema:
            type: string
            example: ref-12345
        - name: sendDate
          in: query
          description: >-
            Filter messages sent before this timestamp (ISO 8601 format, e.g.
            `2026-12-31T23:59:59Z`). Defaults to current time if not specified.
          schema:
            type: string
            format: date-time
        - name: count
          in: query
          description: Maximum number of records to return (max 100)
          schema:
            type: integer
            format: int64
            default: 50
            maximum: 100
            minimum: 1
      responses:
        '200':
          description: SMS list for reference key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsStatisticsResponse'
              examples:
                withReference:
                  summary: Message with reference
                  value:
                    messages:
                      - message:
                          id: 54149766-7f65-4d02-b29d-406a42ca7a81
                          reference:
                            service: DIGITALSIGN
                            action: AUTH
                            key: ref-12345
                          channel: SMS
                          status: DELIVERED
                          providerAcceptanceAt: '2026-02-25T16:12:10Z'
                          statusChangedAt: '2026-02-25T16:12:15Z'
                          provider:
                            name: PROVIDER1
                            id: eb1cd034767b91e5d7a1fd23d9f
                            status: DELIVERED
                            code: '0'
                          sms:
                            segments: 1
                withoutReference:
                  summary: >-
                    Message without reference (reference not specified in send
                    request)
                  value:
                    messages:
                      - message:
                          id: 320bc578-d2f9-44e0-b83e-72cbb9dbd5da
                          reference: {}
                          channel: SMS
                          status: DELIVERED
                          providerAcceptanceAt: '2026-02-26T11:41:41Z'
                          statusChangedAt: '2026-02-26T11:41:47Z'
                          provider:
                            name: PROVIDER2
                            id: 0467bc0e-425e-2d1d-b159-91b17d93e401
                            status: DELIVERED
                            code: '0'
                          sms:
                            segments: 1
                emptyResult:
                  summary: No messages found
                  value:
                    messages: []
        '400':
          description: Bad request
        '403':
          description: Forbidden. The API key is missing or invalid.
        '500':
          description: Internal server error
      tags:
        - MessageStatus
      description: >-
        Retrieves the delivery status of the latest messages associated with the
        external key specified in the `reference.key` parameter of the
        [send](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/api-references/services-send)
        API.
  /messagestatus/{messageid}:
    get:
      summary: Get SMS details from message ID
      operationId: getSmsDetailFromMessageId
      parameters:
        - name: messageid
          in: path
          description: Message ID to query
          required: true
          schema:
            type: string
            example: 54149766-7f65-4d02-b29d-406a42ca7a88
            format: uuid
      responses:
        '200':
          description: Message status details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageStatusWrapper'
              examples:
                found:
                  summary: Message found
                  value:
                    message:
                      id: 30307af0-6d8b-4fbf-b4f3-b0e1fc32381c
                      reference:
                        service: DIGITALSIGN
                        action: TEST
                        key: apistatus-live-test-001
                      channel: SMS
                      status: DELIVERED
                      providerAcceptanceAt: '2026-02-27T09:06:58Z'
                      statusChangedAt: '2026-02-27T09:07:08Z'
                      provider:
                        name: PROVIDER1
                        id: 1565fbb5-3d73-4da4-96d2-e91d987f23b4
                        status: DELIVERED
                        code: '0'
                      sms:
                        segments: 1
                foundWithoutReference:
                  summary: Message found, no reference specified in send request
                  value:
                    message:
                      id: e989c2ec-c476-4224-a2b4-f21c76b551bb
                      reference: {}
                      channel: SMS
                      status: DELIVERED
                      providerAcceptanceAt: '2026-02-26T21:47:22Z'
                      statusChangedAt: '2026-02-26T21:47:30Z'
                      provider:
                        name: PROVIDER2
                        id: 381b43c9-fff3-4f5e-b35c-1cf387f2d49f
                        status: DELIVERED
                        code: '0'
                      sms:
                        segments: 1
        '400':
          description: Bad request
        '403':
          description: Forbidden. The API key is missing or invalid.
        '404':
          description: Message not found. No message exists with the specified ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 1
                  message: Message not found
        '500':
          description: Internal server error
      tags:
        - MessageStatus
      description: Retrieves the delivery status for a specific message.
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      description: Error response wrapper
    ErrorDetail:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
      description: Error detail
    MessageStatus:
      type: object
      properties:
        id:
          type: string
          description: Message identifier
          format: uuid
          example: 54149766-7f65-4d02-b29d-406a42ca7a88
        reference:
          $ref: '#/components/schemas/ReferenceService'
          description: Reference object specified in the send request.
        channel:
          type: string
          enum:
            - SMS
            - RCS
          description: Delivery channel.
        status:
          type: string
          enum:
            - SENT
            - DELIVERED
            - REJECTED
            - UNDELIVERED
            - READ
            - PROVIDER_ACCEPTANCE
          description: Current delivery status.
        providerAcceptanceAt:
          type: string
          format: date-time
          description: >-
            Timestamp when the message was accepted by the provider (ISO 8601
            format, e.g., 2026-02-12T14:51:00Z). Corresponds to the initial
            PROVIDER_ACCEPTANCE status.
        statusChangedAt:
          type: string
          format: date-time
          description: >-
            Timestamp of the most recent status change (ISO 8601 format, e.g.,
            2026-02-12T14:51:05Z).
        provider:
          $ref: '#/components/schemas/MessageStatusProvider'
          description: Provider information.
        sms:
          $ref: '#/components/schemas/SmsInfo'
          description: SMS-specific information.
      description: SMS message status
      required:
        - id
        - providerAcceptanceAt
        - statusChangedAt
    MessageStatusProvider:
      type: object
      properties:
        name:
          type: string
          description: Provider name.
        id:
          type: string
          description: Provider's message identifier.
        status:
          type: string
          description: Provider-specific status.
        code:
          type: string
          description: Provider status/error code.
        message:
          type: string
          description: Optional provider error details (e.g. `Number Blocked by Carrier`).
      description: SMS provider details
    MessageStatusWrapper:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/MessageStatus'
          description: SMS message status details.
      description: Single message wrapper
    ReferenceService:
      type: object
      properties:
        service:
          type: string
          description: Service identifier (e.g., AUTHENTICATION, ECOMMERCE, DIGITALSIGN).
          maxLength: 50
        action:
          type: string
          description: Action within the service (e.g., 2FA, PASSWORD_RESET).
          maxLength: 50
        key:
          type: string
          description: Custom tracking key (e.g., user ID, order ID).
          maxLength: 255
      description: >-
        Tracking reference to correlate SMS with your business logic. May be an
        empty object (`{}`) if no reference was specified in the send request.
    SmsInfo:
      type: object
      properties:
        segments:
          type: integer
          format: int32
          description: >-
            Number of SMS segments used. Messages exceeding 160 characters
            (GSM-7) or 70 characters (UCS-2) are split into multiple segments.
      description: SMS info
    SmsStatisticsResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageStatusWrapper'
          description: List of SMS message statuses.
      description: List of message statuses
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-Api-Key
      in: header
      description: >-
        HTTP API Key authentication using account credentials.


        **Format**: `X-Api-Key: YOUR_API_KEY`


        **How to obtain credentials**:

        1. Contact Namirial support to create a Message Status API account

        2. Receive API key via secure channel

        3. Test credentials in TEST environment first


        See [Authentication
        documentation](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/authentication-api-status)
        for details.
security:
  - ApiKeyAuth: []
tags:
  - name: MessageStatus
    description: |-
      Retrieve delivery status and statistics for SMS messages.

      **Authentication**: API Key required (`X-Api-Key` header)
    externalDocs:
      description: Message Status API Documentation
      url: >-
        https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/apistatus-references
externalDocs:
  description: Message Status API Documentation
  url: >-
    https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/apistatus-references
