Telnyx Opt-Out Management API

openapi: 3.2.0
info:
  title: Telnyx Opt-Out Management API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged Opt-Out Management across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Opt-Out Management
  description: Opt-Out Management
paths:
  /messaging_optouts:
    get:
      summary: List opt-outs
      description: Returns a paginated list of opt-out blocks created when message recipients opt out. Supports filtering and optional redaction of recipient numbers.
      operationId: ListOptOuts
      tags:
      - Opt-Out Management
      parameters:
      - name: redaction_enabled
        in: query
        description: If receiving address (+E.164 formatted phone number) should be redacted
        required: false
        example: +447766****
        schema:
          type: string
          x-format: boolean
      - name: filter
        in: query
        style: deepObject
        explode: true
        description: 'Consolidated filter parameter (deepObject style). Originally: filter[messaging_profile_id], filter[from]'
        schema:
          type: object
          properties:
            messaging_profile_id:
              type: string
              description: The ID of the messaging profile to retrieve opt-outs for
            from:
              type: string
              description: The sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code) to retrieve opt-outs for
      - $ref: '#/components/parameters/PageConsolidated'
      - name: created_at
        in: query
        style: deepObject
        explode: true
        description: 'Consolidated created_at parameter (deepObject style). Originally: created_at[gte], created_at[lte]'
        schema:
          type: object
          properties:
            gte:
              type: string
              format: date-time
              description: Filter opt-outs created after this date (ISO-8601 format)
            lte:
              type: string
              format: date-time
              description: Filter opt-outs created before this date (ISO-8601 format)
      responses:
        '200':
          description: Successful response with opt-out list data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messaging_Error_0b38e7044b'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messaging_Error_0b38e7044b'
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /messaging_profiles/{profile_id}/autoresp_configs:
    get:
      tags:
      - Opt-Out Management
      summary: List Auto-Response Settings
      operationId: GetAutorespConfigs
      parameters:
      - required: true
        schema:
          title: Profile Id
          type: string
          format: uuid
        name: profile_id
        in: path
        description: Unique identifier of the profile.
      - required: false
        schema:
          title: Country Code
          type: string
        name: country_code
        in: query
        description: Filter results by country code.
      - name: created_at
        in: query
        style: deepObject
        explode: true
        description: 'Consolidated created_at parameter (deepObject style). Originally: created_at[gte], created_at[lte]'
        schema:
          type: object
          properties:
            gte:
              title: Created At[Gte]
              type: string
            lte:
              title: Created At[Lte]
              type: string
      - name: updated_at
        in: query
        style: deepObject
        explode: true
        description: 'Consolidated updated_at parameter (deepObject style). Originally: updated_at[gte], updated_at[lte]'
        schema:
          type: object
          properties:
            gte:
              title: Updated At[Gte]
              type: string
            lte:
              title: Updated At[Lte]
              type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messaging_AutorespConfigsResponseSchema'
              example:
                data:
                - op: start
                  keywords:
                  - START
                  - BEGIN
                  resp_text: Thank you for subscribing US customer.
                  country_code: US
                  id: 677ec1cb-949e-4aeb-a1c3-6d9ddffc1409
                  created_at: '2023-03-21T23:37:45.858535+00:00'
                  updated_at: '2023-03-21T23:37:45.858535+00:00'
                - op: stop
                  keywords:
                  - END
                  - STOP
                  resp_text: You have unsubscribed.
                  country_code: US
                  id: 54b7e19f-98a8-416f-81d1-a2782eade48b
                  created_at: '2023-03-10T21:54:46.293380+00:00'
                  updated_at: '2023-03-10T21:54:46.293380+00:00'
                - op: start
                  keywords:
                  - START
                  resp_text: Thank you for subscribing.
                  country_code: '*'
                  id: cfe07be1-2369-433f-be00-eb176008e834
                  created_at: '2023-03-14T14:46:21.097735+00:00'
                  updated_at: '2023-03-14T14:46:21.097735+00:00'
                meta:
                  page_number: 1
                  page_size: 5
                  total_pages: 1
                  total_results: 3
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Returns the auto-response rules configured for the specified messaging profile.
    post:
      tags:
      - Opt-Out Management
      summary: Create auto-response setting
      operationId: CreateAutorespConfig
      parameters:
      - required: true
        schema:
          title: Profile Id
          type: string
        name: profile_id
        in: path
        description: Unique identifier of the profile.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoRespConfigCreateSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutorespConfigResponseSchema'
              example:
                data:
                  op: start
                  keywords:
                  - START
                  resp_text: Hello there!
                  country_code: US
                  id: c2298f86-a4dc-4cac-b6b6-4a3d01c290fa
                  created_at: '2023-03-22T00:06:49.068817+00:00'
                  updated_at: '2023-03-22T00:06:49.068817+00:00'
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Creates an auto-response rule on the specified messaging profile. Matching inbound messages trigger the configured response.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}:
    delete:
      tags:
      - Opt-Out Management
      summary: Delete Auto-Response Setting
      operationId: DeleteAutorespConfig
      parameters:
      - required: true
        schema:
          title: Profile Id
          type: string
          format: uuid
        name: profile_id
        in: path
        description: Unique identifier of the profile.
      - required: true
        schema:
          title: Autoresp Cfg Id
          type: string
          format: uuid
        name: autoresp_cfg_id
        in: path
        description: Unique identifier of the autoresp cfg.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string
                example: OK
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Deletes the specified auto-response rule from the messaging profile.
    get:
      tags:
      - Opt-Out Management
      summary: Get Auto-Response Setting
      operationId: GetAutorespConfig
      parameters:
      - required: true
        schema:
          title: Profile Id
          type: string
          format: uuid
        name: profile_id
        in: path
        description: Unique identifier of the profile.
      - required: true
        schema:
          title: Autoresp Cfg Id
          type: string
          format: uuid
        name: autoresp_cfg_id
        in: path
        description: Unique identifier of the autoresp cfg.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutorespConfigResponseSchema'
              example:
                data:
                  op: start
                  keywords:
                  - UNSTOP
                  resp_text: Hello there!
                  country_code: US
                  id: adc37adf-d110-4355-9e9a-262847e68e89
                  created_at: '2023-03-13T17:51:03.826453+00:00'
                  updated_at: '2023-03-13T17:51:03.826453+00:00'
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Returns the matching criteria and response content for the specified auto-response rule.
    put:
      tags:
      - Opt-Out Management
      summary: Update Auto-Response Setting
      operationId: UpdateAutoRespConfig
      parameters:
      - required: true
        schema:
          title: Profile Id
          type: string
          format: uuid
        name: profile_id
        in: path
        description: Unique identifier of the profile.
      - required: true
        schema:
          title: Autoresp Cfg Id
          type: string
          format: uuid
        name: autoresp_cfg_id
        in: path
        description: Unique identifier of the autoresp cfg.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoRespConfigCreateSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutorespConfigResponseSchema'
              example:
                data:
                  op: start
                  keywords:
                  - START
                  - BEGIN
                  resp_text: Hello there!
                  country_code: '*'
                  id: 54b7e19f-98a8-416f-81d1-a2782eade48b
                  created_at: '2023-03-10T21:54:46.293380+00:00'
                  updated_at: '2023-03-10T21:54:46.293380+00:00'
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Replaces the configuration of the specified auto-response rule.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  schemas:
    messaging_Errors_0b38e7044b:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/messaging_Error_0b38e7044b'
    messaging_Error_0b38e7044b:
      required:
      - code
      - title
      properties:
        code:
          type: string
          x-format: integer
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
              format: json-pointer
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
    OptOutItem:
      type: object
      properties:
        from:
          type: string
          description: Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
          x-format: address
        to:
          $ref: '#/components/schemas/ToNumber'
        messaging_profile_id:
          type:
          - string
          - 'null'
          description: Unique identifier for a messaging profile.
        keyword:
          type:
          - string
          - 'null'
          description: The keyword that triggered the opt-out.
          example: STOP
        created_at:
          type: string
          format: date-time
          description: The timestamp when the opt-out was created
          example: '2025-04-28 12:00:38.631252+00:00'
    AutoRespConfigCreateSchema:
      title: AutoRespConfigCreateSchema
      required:
      - op
      - keywords
      - country_code
      type: object
      properties:
        op:
          title: Op
          enum:
          - start
          - stop
          - info
          type: string
        keywords:
          title: Keywords
          type: array
          items:
            type: string
          example:
          - keyword1
          - keyword2
        resp_text:
          title: Resp Text
          type: string
          example: Thank you for your message
        country_code:
          title: Country Code
          type: string
          example: US
    OptOutListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OptOutItem'
        meta:
          $ref: '#/components/schemas/messaging_PaginationMeta_0b38e7044b'
    ToNumber:
      type: string
      description: Receiving address (+E.164 formatted phone number or short code).
      example: +E.164
      x-format: address
    AutorespConfigResponseSchema:
      title: AutorespConfigResponseSchema
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AutorespConfigSchema'
    messaging_PaginationMeta_0b38e7044b:
      type: object
      required:
      - total_pages
      - total_results
      - page_size
      - page_number
      properties:
        total_pages:
          type: integer
          example: 3
        total_results:
          type: integer
          example: 55
        page_number:
          type: integer
          example: 2
        page_size:
          type: integer
          example: 25
    messaging_AutorespConfigsResponseSchema:
      title: AutorespConfigsResponseSchema
      description: List of Auto-Response Settings
      required:
      - data
      - meta
      type: object
      properties:
        data:
          title: Data
          type: array
          items:
            $ref: '#/components/schemas/AutorespConfigSchema'
        meta:
          $ref: '#/components/schemas/messaging_PaginationMeta_0b38e7044b'
    AutorespConfigSchema:
      title: AutorespConfigSchema
      required:
      - op
      - keywords
      - country_code
      - id
      - created_at
      - updated_at
      type: object
      properties:
        op:
          title: Op
          enum:
          - start
          - stop
          - info
          type: string
          example: start
        keywords:
          title: Keywords
          type: array
          items:
            type: string
          example:
          - START
          - BEGIN
        resp_text:
          title: Resp Text
          type: string
          example: Thank you for subscribing to our service.
        country_code:
          title: Country Code
          type: string
          example: '*'
        id:
          title: Id
          type: string
          example: b8f9c1c0-5b5a-4b1e-8c1c-0b5a4b1e8c1c
        created_at:
          title: Created At
          type: string
          format: date-time
        updated_at:
          title: Updated At
          type: string
          format: date-time
    AutorespConfigsResponseSchema:
      description: List of Auto-Response Settings
      properties:
        data:
          items:
            $ref: '#/components/schemas/AutorespConfigSchema'
          title: Data
          type: array
        meta:
          $ref: '#/components/schemas/messaging_PaginationMeta'
      required:
      - data
      - meta
      title: AutorespConfigsResponseSchema
      type: object
    messaging_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/messaging_Error'
          type: array
    OptOutListResponse_2:
      properties:
        data:
          items:
            $ref: '#/components/schemas/OptOutItem'
          type: array
        meta:
          $ref: '#/components/schemas/messaging_PaginationMeta'
      type: object
    messaging_Error:
      properties:
        code:
          type: string
          x-format: integer
        detail:
          type: string
        meta:
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              format: json-pointer
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
    messaging_PaginationMeta:
      properties:
        page_number:
          example: 2
          type: integer
        page_size:
          example: 25
          type: integer
        total_pages:
          example: 3
          type: integer
        total_results:
          example: 55
          type: integer
      required:
      - total_pages
      - total_results
      - page_size
      - page_number
      type: object
  responses:
    messaging_GenericErrorResponse_0b38e7044b:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors_0b38e7044b'
          example:
            errors:
            - code: string
              title: string
              detail: string
              source:
                pointer: /data/attributes/phone_number
                parameter: string
    messaging_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Unexpected error
  parameters:
    PageConsolidated:
      name: page
      in: query
      style: deepObject
      explode: true
      description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      schema:
        type: object
        properties:
          number:
            type: integer
            minimum: 1
            default: 1
            description: The page number to load
          size:
            type: integer
            minimum: 1
            maximum: 250
            default: 20
            description: The size of the page
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt