Twilio Messages API

openapi: 3.0.1
info:
  title: Twilio - Accounts A2p Messages API
  description: This is the public Twilio REST API.
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.52.0
servers:
- url: https://accounts.twilio.com
tags:
- name: Messages
  description: Send and manage SMS and MMS messages
paths:
  /Accounts/{AccountSid}/Messages.json:
    get:
      operationId: listMessages
      summary: Twilio List Messages
      description: Retrieve a list of messages associated with your account. The list includes paging information and is sorted by DateSent descending.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/AccountSid'
      - name: To
        in: query
        description: Filter by recipient phone number
        schema:
          type: string
      - name: From
        in: query
        description: Filter by sender phone number
        schema:
          type: string
      - name: DateSent
        in: query
        description: Filter by date sent (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: PageSize
        in: query
        description: Number of records to return per page (max 1000)
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 50
      - name: Page
        in: query
        description: Page number to retrieve
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: List of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '401':
          description: Unauthorized - invalid credentials
        '404':
          description: Account not found
    post:
      operationId: createMessage
      summary: Twilio Send a Message
      description: Send an SMS or MMS message. Specify the recipient, sender, and body or media URL. Messages can be sent from a Twilio phone number, short code, alphanumeric sender ID, or messaging service.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/AccountSid'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
      responses:
        '201':
          description: Message created and queued for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized - invalid credentials
        '422':
          description: Unable to create message
  /Accounts/{AccountSid}/Messages/{MessageSid}.json:
    get:
      operationId: fetchMessage
      summary: Twilio Fetch a Message
      description: Retrieve details of a specific message by its SID.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/AccountSid'
      - $ref: '#/components/parameters/MessageSid'
      responses:
        '200':
          description: Message details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          description: Unauthorized
        '404':
          description: Message not found
    post:
      operationId: updateMessage
      summary: Twilio Update a Message
      description: Update the body of a message resource. Can be used to redact message content by posting an empty body.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/AccountSid'
      - $ref: '#/components/parameters/MessageSid'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                Body:
                  type: string
                  description: The updated message body (empty string to redact)
                Status:
                  type: string
                  enum:
                  - canceled
                  description: Set to canceled to cancel a queued message
      responses:
        '200':
          description: Message updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          description: Unauthorized
        '404':
          description: Message not found
    delete:
      operationId: deleteMessage
      summary: Twilio Delete a Message
      description: Delete a message record from your account. The message will no longer appear in your account logs.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/AccountSid'
      - $ref: '#/components/parameters/MessageSid'
      responses:
        '204':
          description: Message deleted
        '401':
          description: Unauthorized
        '404':
          description: Message not found
components:
  parameters:
    MessageSid:
      name: MessageSid
      in: path
      required: true
      description: The unique identifier of the message
      schema:
        type: string
        pattern: ^(SM|MM)[0-9a-fA-F]{32}$
    AccountSid:
      name: AccountSid
      in: path
      required: true
      description: The unique identifier of the Twilio account
      schema:
        type: string
        pattern: ^AC[0-9a-fA-F]{32}$
  schemas:
    Message:
      type: object
      properties:
        sid:
          type: string
          pattern: ^(SM|MM)[0-9a-fA-F]{32}$
          description: Unique identifier for the message
        account_sid:
          type: string
          pattern: ^AC[0-9a-fA-F]{32}$
          description: Account SID that created the message
        messaging_service_sid:
          type: string
          pattern: ^MG[0-9a-fA-F]{32}$
          description: SID of the messaging service used
        to:
          type: string
          description: Recipient phone number in E.164 format
        from:
          type: string
          description: Sender phone number, alphanumeric sender ID, or short code
        body:
          type: string
          description: The text body of the message (up to 1600 characters)
          maxLength: 1600
        status:
          type: string
          enum:
          - queued
          - sending
          - sent
          - delivered
          - undelivered
          - failed
          - receiving
          - received
          - accepted
          - scheduled
          - read
          - partially_delivered
          - canceled
          description: Current status of the message
        direction:
          type: string
          enum:
          - inbound
          - outbound-api
          - outbound-call
          - outbound-reply
          description: Direction of the message
        price:
          type: string
          description: Price of the message in the currency specified
        price_unit:
          type: string
          description: Currency unit for the price (e.g., USD)
        num_segments:
          type: string
          description: Number of segments the message was split into
        num_media:
          type: string
          description: Number of media files associated with the message
        error_code:
          type: integer
          description: Error code if the message failed
        error_message:
          type: string
          description: Human-readable error message
        date_created:
          type: string
          format: date-time
          description: When the message was created
        date_updated:
          type: string
          format: date-time
          description: When the message was last updated
        date_sent:
          type: string
          format: date-time
          description: When the message was sent
        uri:
          type: string
          description: Relative URI for this message resource
        api_version:
          type: string
          description: API version used to process the message
        subresource_uris:
          type: object
          description: URIs of related subresources
          properties:
            media:
              type: string
    CreateMessageRequest:
      type: object
      required:
      - To
      properties:
        To:
          type: string
          description: Recipient phone number in E.164 format
        From:
          type: string
          description: Twilio phone number, short code, or alphanumeric sender ID
        Body:
          type: string
          description: The text content of the message (max 1600 characters)
          maxLength: 1600
        MessagingServiceSid:
          type: string
          description: SID of the messaging service to use
          pattern: ^MG[0-9a-fA-F]{32}$
        MediaUrl:
          type: array
          items:
            type: string
            format: uri
          description: URLs of media to include in MMS messages (max 10)
          maxItems: 10
        StatusCallback:
          type: string
          format: uri
          description: URL for status callback notifications
        MaxPrice:
          type: number
          description: Maximum price in USD to pay for the message
        ValidityPeriod:
          type: integer
          description: Validity period in seconds (max 14400)
          maximum: 14400
        SendAt:
          type: string
          format: date-time
          description: Time to send a scheduled message (requires messaging service)
        ScheduleType:
          type: string
          enum:
          - fixed
          description: Schedule type for scheduled messages
        ContentSid:
          type: string
          description: SID of a content template to use
          pattern: ^HX[0-9a-fA-F]{32}$
        ContentVariables:
          type: string
          description: JSON string of variables for content templates
    MessageList:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        first_page_uri:
          type: string
        next_page_uri:
          type: string
        previous_page_uri:
          type: string
        page:
          type: integer
        page_size:
          type: integer
        uri:
          type: string
  securitySchemes:
    accountSid_authToken:
      type: http
      scheme: basic
x-maturity:
- name: GA
  description: This product is Generally Available.
- name: Beta
  description: PLEASE NOTE that this is a Beta product that is subject to change. Use it with caution.