openapi: 3.2.0
info:
  title: Sinch SMS Delivery Reports API
  description: The Sinch SMS API enables developers to send and receive SMS messages globally at scale. It supports batch messaging with scheduled delivery, message templates, delivery reports, and inbound message handling via webhooks. The API provides group management for organizing recipients, automatic message encoding optimization, and supports both transactional and marketing use cases across carriers worldwide.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
servers:
- url: https://us.sms.api.sinch.com
  description: US Production Server
- url: https://eu.sms.api.sinch.com
  description: EU Production Server
- url: https://au.sms.api.sinch.com
  description: Australia Production Server
- url: https://br.sms.api.sinch.com
  description: Brazil Production Server
- url: https://ca.sms.api.sinch.com
  description: Canada Production Server
security:
- bearerAuth: []
tags:
- name: Delivery Reports
  description: Delivery reports provide the status of sent messages. Reports can be retrieved via the API or delivered via webhook callbacks.
paths:
  /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report:
    get:
      operationId: getBatchDeliveryReport
      summary: Retrieve a Batch Delivery Report
      description: Returns the aggregate delivery report for a specific batch. The report contains status counts and details about message delivery.
      tags:
      - Delivery Reports
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      - $ref: '#/components/parameters/BatchId'
      - name: type
        in: query
        description: The type of delivery report to retrieve
        schema:
          type: string
          enum:
          - summary
          - full
      responses:
        '200':
          description: Delivery report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryReport'
        '401':
          description: Unauthorized
        '404':
          description: Batch not found
  /xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/{recipient_msisdn}:
    get:
      operationId: getRecipientDeliveryReport
      summary: Retrieve a Recipient Delivery Report
      description: Returns the delivery report for a specific recipient in a batch.
      tags:
      - Delivery Reports
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      - $ref: '#/components/parameters/BatchId'
      - name: recipient_msisdn
        in: path
        required: true
        description: The phone number of the recipient
        schema:
          type: string
      responses:
        '200':
          description: Recipient delivery report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientDeliveryReport'
        '401':
          description: Unauthorized
        '404':
          description: Report not found
  /xms/v1/{service_plan_id}/delivery_reports:
    get:
      operationId: listDeliveryReports
      summary: List Delivery Reports
      description: Returns a list of delivery reports with pagination support.
      tags:
      - Delivery Reports
      parameters:
      - $ref: '#/components/parameters/ServicePlanId'
      - name: page
        in: query
        description: The page number to retrieve
        schema:
          type: integer
          default: 0
      - name: page_size
        in: query
        description: The number of reports per page
        schema:
          type: integer
          default: 30
          maximum: 100
      responses:
        '200':
          description: List of delivery reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryReportList'
        '401':
          description: Unauthorized
components:
  schemas:
    DeliveryReportList:
      type: object
      properties:
        count:
          type: integer
          description: Total number of delivery reports
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of reports per page
        delivery_reports:
          type: array
          description: List of delivery report objects
          items:
            $ref: '#/components/schemas/DeliveryReport'
    RecipientDeliveryReport:
      type: object
      properties:
        batch_id:
          type: string
          description: The batch identifier
        recipient:
          type: string
          description: The recipient phone number
        code:
          type: integer
          description: The delivery status code
        status:
          type: string
          description: The delivery status
        at:
          type: string
          format: date-time
          description: When the status was updated
        operator_status_at:
          type: string
          format: date-time
          description: When the operator reported the status
    DeliveryReport:
      type: object
      properties:
        batch_id:
          type: string
          description: The batch identifier
        type:
          type: string
          description: The delivery report type
        statuses:
          type: array
          description: List of status objects with counts
          items:
            type: object
            properties:
              code:
                type: integer
                description: The status code
              status:
                type: string
                description: The delivery status
              count:
                type: integer
                description: The number of recipients with this status
              recipients:
                type: array
                description: List of recipient phone numbers
                items:
                  type: string
        total_message_count:
          type: integer
          description: Total number of messages in the batch
  parameters:
    BatchId:
      name: batch_id
      in: path
      required: true
      description: The unique identifier for the batch
      schema:
        type: string
    ServicePlanId:
      name: service_plan_id
      in: path
      required: true
      description: The unique identifier for the service plan
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token sent in the Authorization header preceded by Bearer.
externalDocs:
  description: Sinch SMS API Documentation
  url: https://developers.sinch.com/docs/sms
x-ae-provenance: origin unrecorded (catalog pass before 2026-09); NOT a provider-published document. Kept on 2026-10-08 because its /xms/v1/{service_plan_id}/... paths match the SMS REST API reference nav at https://developers.sinch.com/docs/sms/api-reference (Batches, Delivery reports, Groups, Inbounds), which publishes no downloadable OpenAPI bundle (searched 2026-10-08). Moved out of _original/ because _original asserts provider publication.