openapi: 3.0.1
info:
  title: SimpleTexting Campaigns Messages API
  description: The SimpleTexting v2 REST API lets developers send SMS and MMS messages, manage contacts and contact lists, run bulk campaigns, upload media, read custom fields and segments, and subscribe to webhook events. The API is organized around REST, uses standard HTTP verbs and response codes, accepts and returns JSON, and is authenticated with a bearer token in the Authorization header.
  termsOfService: https://simpletexting.com/terms-of-service/
  contact:
    name: SimpleTexting Support
    url: https://simpletexting.com/api/
    email: support@simpletexting.com
  version: '2.0'
servers:
- url: https://api-app2.simpletexting.com/v2
  description: SimpleTexting v2 production API
security:
- bearerAuth: []
tags:
- name: Messages
  description: Send and retrieve one-to-one SMS / MMS messages.
paths:
  /api/messages:
    get:
      operationId: getAllMessages
      tags:
      - Messages
      summary: Get all Messages
      description: Returns a paginated list of messages sent to and from the account.
      parameters:
      - name: page
        in: query
        schema:
          type: integer
      - name: size
        in: query
        schema:
          type: integer
      - name: accountPhone
        in: query
        schema:
          type: string
      - name: since
        in: query
        schema:
          type: string
      - name: contactPhone
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A page of messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageViewMessage'
    post:
      operationId: sendMessage
      tags:
      - Messages
      summary: Send a Message
      description: Sends a single SMS or MMS message to one contact.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '200':
          description: The accepted message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /api/messages/evaluate:
    post:
      operationId: evaluateMessage
      tags:
      - Messages
      summary: Evaluate a Message
      description: Evaluates a message body without sending it, returning credit cost, segment count, and encoding details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluateMessageRequest'
      responses:
        '200':
          description: Message evaluation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageInfo'
  /api/messages/{messageId}:
    get:
      operationId: getMessage
      tags:
      - Messages
      summary: Get a Message
      description: Retrieves a single message by its identifier.
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
components:
  schemas:
    EvaluateMessageRequest:
      type: object
      required:
      - mode
      - text
      properties:
        mode:
          type: string
          enum:
          - AUTO
          - SINGLE_SMS_STRICTLY
          - MMS_PREFERRED
        subject:
          type: string
        text:
          type: string
        fallbackText:
          type: string
        mediaItems:
          type: array
          items:
            type: string
    MessageInfo:
      type: object
      properties:
        segmentsCount:
          type: integer
        creditsCost:
          type: integer
        encoding:
          type: string
        charactersCount:
          type: integer
    PageViewMessage:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        page:
          type: integer
        size:
          type: integer
        totalElements:
          type: integer
    SendMessageRequest:
      type: object
      required:
      - contactPhone
      - mode
      - text
      properties:
        contactPhone:
          type: string
          description: Destination phone number in E.164 format.
        accountPhone:
          type: string
          description: Sending phone number to use; defaults to the account's primary number.
        mode:
          type: string
          enum:
          - AUTO
          - SINGLE_SMS_STRICTLY
          - MMS_PREFERRED
        subject:
          type: string
        text:
          type: string
        fallbackText:
          type: string
        mediaItems:
          type: array
          items:
            type: string
    Message:
      type: object
      properties:
        id:
          type: string
        contactPhone:
          type: string
        accountPhone:
          type: string
        text:
          type: string
        direction:
          type: string
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send the API token as a bearer token in the Authorization header: `Authorization: Bearer <token>`. Generate a token in the SimpleTexting web app under Settings.'