Azure Communication Services SMS API

openapi: 3.2.0
info:
  title: Azure Communication Service Sms API
  description: Azure Communication SMS Service
  version: '2026-01-23'
tags:
- name: SMS
paths:
  /sms:
    post:
      tags:
      - SMS
      summary: Sends a SMS message from a phone number that belongs to the authenticated…
      operationId: Sms_Send
      parameters:
      - name: api-version
        in: query
        description: Version of API to invoke.
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsSendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
        description: Represents the body of the send message request.
        required: true
components:
  schemas:
    ErrorDetail:
      description: Error detail information.
      required:
      - code
      - message
      type: object
      properties:
        code:
          description: The error code.
          type: string
        message:
          description: The error message.
          type: string
        innerError:
          description: Additional error details.
          type: object
    SendMessageRequest:
      description: Represents the properties of a send message request.
      required:
      - message
      - smsRecipients
      - from
      type: object
      properties:
        from:
          description: The sender's phone number in E.164 format that is owned by the authenticated account.
          type: string
        smsRecipients:
          description: The recipient's phone number in E.164 format. In this version, a minimum of 1 and upto 100 recipients in the list are supported.
          maxLength: 100
          minLength: 1
          type: array
          items:
            $ref: '#/components/schemas/SmsRecipient'
        message:
          description: The contents of the message that will be sent to the recipient. The allowable content is defined by RFC 5724.
          maxLength: 2048
          minLength: 0
          type: string
        smsSendOptions:
          $ref: '#/components/schemas/SmsSendOptions'
    MessagingConnectOptions:
      description: Defines optional parameters for connecting with the Messaging Connect Partner to deliver SMS.
      required:
      - partner
      - partnerParams
      type: object
      properties:
        partner:
          description: Specifies the partner name for message delivery.
          type: string
        partnerParams:
          description: Partner-specific parameters as key-value pairs. Must contain at least one parameter required by the messaging connect partner (e.g., apiKey, servicePlanId, authToken, etc.).
          type: object
          minProperties: 1
    SmsSendResponseItem:
      description: Response for a single recipient.
      required:
      - httpStatusCode
      - to
      - successful
      type: object
      properties:
        to:
          description: The recipient's phone number in E.164 format.
          type: string
        messageId:
          description: The identifier of the outgoing Sms message. Only present if message processed.
          type: string
        httpStatusCode:
          format: int32
          description: HTTP Status code.
          type: integer
        repeatabilityResult:
          description: The result of a repeatable request with one of the case-insensitive values accepted or rejected.
          type: string
          enum:
          - accepted
          - rejected
        successful:
          description: Indicates if the message is processed successfully or not.
          type: boolean
        errorMessage:
          description: Optional error message in case of 4xx/5xx/repeatable errors.
          type: string
    StandardErrorResponse:
      description: Standard error response format.
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
    SmsSendResponse:
      description: Response for a successful or multi status send Sms request.
      required:
      - value
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/SmsSendResponseItem'
    SmsSendOptions:
      description: Optional configuration for sending SMS messages.
      required:
      - enableDeliveryReport
      type: object
      properties:
        enableDeliveryReport:
          description: Enable this flag to receive a delivery report for this message on the Azure Resource EventGrid.
          type: boolean
        tag:
          description: Use this field to provide metadata that will then be sent back in the corresponding Delivery Report.
          type: string
        deliveryReportTimeoutInSeconds:
          format: int32
          description: Time to wait for a delivery report. After this time a delivery report with timeout error code is generated.
          maximum: 43200
          minimum: 60
          type: integer
        messagingConnect:
          $ref: '#/components/schemas/MessagingConnectOptions'
    SmsRecipient:
      description: Recipient details for sending SMS messages.
      required:
      - to
      type: object
      properties:
        to:
          description: The recipient's phone number in E.164 format.
          type: string
        repeatabilityRequestId:
          description: If specified, the client directs that the request is repeatable; that is, the client can make the request multiple times with the same Repeatability-Request-ID and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-ID is an opaque string representing a client-generated, 36-character hexadecimal case-insensitive encoding of a UUID (GUID), identifier for the request.
          type: string
        repeatabilityFirstSent:
          description: MUST be sent by clients to specify that a request is repeatable. Repeatability-First-Sent is used to specify the date and time at which the request was first created.eg- Tue, 26 Mar 2019 16:06:51 GMT
          type: string
    BadRequestErrorResponse:
      description: Bad Request error response that can represent both validation errors and standard API errors.
      type: object
      properties:
        type:
          description: A URI reference that identifies the problem type (for validation errors).
          type: string
        title:
          description: A short, human-readable summary of the problem type (for validation errors).
          type: string
        status:
          description: The HTTP status code (for validation errors).
          type: integer
          format: int32
        errors:
          description: Dictionary of field-specific validation errors (for validation errors).
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        traceId:
          description: The trace identifier for the request (for validation errors).
          type: string
        error:
          description: Error detail information (for standard API errors).
          $ref: '#/components/schemas/ErrorDetail'
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    description: The communication resource, for example https://my-resource.communication.azure.com
    required: true
    type: string
    in: path
    x-ms-skip-url-encoding: true
    x-ms-parameter-location: client
    format: url