Twilio Messages API

openapi: 3.2.0
info:
  title: Twilio Messaging Messages API
  description: Send and receive SMS and MMS messages globally using Twilio's Messaging API. Supports programmable messaging, messaging services, alphanumeric sender IDs, A2P 10DLC registration, toll-free verification, and link shortening.
  version: '2.0'
  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
  termsOfService: https://www.twilio.com/legal/tos
servers:
- url: https://api.twilio.com/2010-04-01
  description: Twilio REST API v1
- url: https://messaging.twilio.com/v1
  description: Twilio Messaging Service API
security:
- accountSid_authToken: []
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:
  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
    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
    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
  parameters:
    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}$
    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}$
  securitySchemes:
    accountSid_authToken:
      type: http
      scheme: basic
      description: Use your Twilio Account SID as the username and Auth Token as the password for HTTP Basic authentication.
externalDocs:
  description: Twilio Messaging API Documentation
  url: https://www.twilio.com/docs/messaging/api