OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens Opt-Out Management API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Opt-Out Management
name: Opt-Out Management
paths:
/messaging_optouts:
get:
description: Retrieve a list of opt-out blocks.
operationId: ListOptOuts
parameters:
- description: If receiving address (+E.164 formatted phone number) should be redacted
example: +447766****
in: query
name: redaction_enabled
required: false
schema:
type: string
x-format: boolean
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[messaging_profile_id], filter[from]'
explode: true
in: query
name: filter
schema:
properties:
from:
description: The sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code) to retrieve opt-outs for
type: string
messaging_profile_id:
description: The ID of the messaging profile to retrieve opt-outs for
type: string
type: object
style: deepObject
- $ref: '#/components/parameters/PageConsolidated'
- description: 'Consolidated created_at parameter (deepObject style). Originally: created_at[gte], created_at[lte]'
explode: true
in: query
name: created_at
schema:
properties:
gte:
description: Filter opt-outs created after this date (ISO-8601 format)
format: date-time
type: string
lte:
description: Filter opt-outs created before this date (ISO-8601 format)
format: date-time
type: string
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/OptOutListResponse'
description: Successful response with opt-out list data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Error'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Error'
description: Unauthorized
summary: List opt-outs
tags:
- Opt-Out Management
x-latency-category: responsive
/messaging_profiles/{profile_id}/autoresp_configs:
get:
operationId: GetAutorespConfigs
parameters:
- in: path
name: profile_id
required: true
schema:
format: uuid
title: Profile Id
type: string
- in: query
name: country_code
required: false
schema:
title: Country Code
type: string
- description: 'Consolidated created_at parameter (deepObject style). Originally: created_at[gte], created_at[lte]'
explode: true
in: query
name: created_at
schema:
properties:
gte:
title: Created At[Gte]
type: string
lte:
title: Created At[Lte]
type: string
type: object
style: deepObject
- description: 'Consolidated updated_at parameter (deepObject style). Originally: updated_at[gte], updated_at[lte]'
explode: true
in: query
name: updated_at
schema:
properties:
gte:
title: Updated At[Gte]
type: string
lte:
title: Updated At[Lte]
type: string
type: object
style: deepObject
responses:
'200':
content:
application/json:
example:
data:
- country_code: US
created_at: '2023-03-21T23:37:45.858535+00:00'
id: 677ec1cb-949e-4aeb-a1c3-6d9ddffc1409
keywords:
- START
- BEGIN
op: start
resp_text: Thank you for subscribing US customer.
updated_at: '2023-03-21T23:37:45.858535+00:00'
- country_code: US
created_at: '2023-03-10T21:54:46.293380+00:00'
id: 54b7e19f-98a8-416f-81d1-a2782eade48b
keywords:
- END
- STOP
op: stop
resp_text: You have unsubscribed.
updated_at: '2023-03-10T21:54:46.293380+00:00'
- country_code: '*'
created_at: '2023-03-14T14:46:21.097735+00:00'
id: cfe07be1-2369-433f-be00-eb176008e834
keywords:
- START
op: start
resp_text: Thank you for subscribing.
updated_at: '2023-03-14T14:46:21.097735+00:00'
meta:
page_number: 1
page_size: 5
total_pages: 1
total_results: 3
schema:
$ref: '#/components/schemas/AutorespConfigsResponseSchema'
description: Successful Response
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: List Auto-Response Settings
tags:
- Opt-Out Management
x-latency-category: responsive
post:
operationId: CreateAutorespConfig
parameters:
- in: path
name: profile_id
required: true
schema:
title: Profile Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutoRespConfigCreateSchema'
required: true
responses:
'200':
content:
application/json:
example:
data:
country_code: US
created_at: '2023-03-22T00:06:49.068817+00:00'
id: c2298f86-a4dc-4cac-b6b6-4a3d01c290fa
keywords:
- START
op: start
resp_text: Hello there!
updated_at: '2023-03-22T00:06:49.068817+00:00'
schema:
$ref: '#/components/schemas/AutorespConfigResponseSchema'
description: Successful Response
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Create auto-response setting
tags:
- Opt-Out Management
x-latency-category: responsive
/messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}:
delete:
operationId: DeleteAutorespConfig
parameters:
- in: path
name: profile_id
required: true
schema:
format: uuid
title: Profile Id
type: string
- in: path
name: autoresp_cfg_id
required: true
schema:
format: uuid
title: Autoresp Cfg Id
type: string
responses:
'200':
content:
application/json:
schema:
example: OK
type: string
description: Successful Response
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Delete Auto-Response Setting
tags:
- Opt-Out Management
x-latency-category: responsive
get:
operationId: GetAutorespConfig
parameters:
- in: path
name: profile_id
required: true
schema:
format: uuid
title: Profile Id
type: string
- in: path
name: autoresp_cfg_id
required: true
schema:
format: uuid
title: Autoresp Cfg Id
type: string
responses:
'200':
content:
application/json:
example:
data:
country_code: US
created_at: '2023-03-13T17:51:03.826453+00:00'
id: adc37adf-d110-4355-9e9a-262847e68e89
keywords:
- UNSTOP
op: start
resp_text: Hello there!
updated_at: '2023-03-13T17:51:03.826453+00:00'
schema:
$ref: '#/components/schemas/AutorespConfigResponseSchema'
description: Successful Response
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Get Auto-Response Setting
tags:
- Opt-Out Management
x-latency-category: responsive
put:
operationId: UpdateAutoRespConfig
parameters:
- in: path
name: profile_id
required: true
schema:
format: uuid
title: Profile Id
type: string
- in: path
name: autoresp_cfg_id
required: true
schema:
format: uuid
title: Autoresp Cfg Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutoRespConfigCreateSchema'
required: true
responses:
'200':
content:
application/json:
example:
data:
country_code: '*'
created_at: '2023-03-10T21:54:46.293380+00:00'
id: 54b7e19f-98a8-416f-81d1-a2782eade48b
keywords:
- START
- BEGIN
op: start
resp_text: Hello there!
updated_at: '2023-03-10T21:54:46.293380+00:00'
schema:
$ref: '#/components/schemas/AutorespConfigResponseSchema'
description: Successful Response
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Update Auto-Response Setting
tags:
- Opt-Out Management
x-latency-category: responsive
components:
schemas:
AutorespConfigSchema:
properties:
country_code:
example: '*'
title: Country Code
type: string
created_at:
format: date-time
title: Created At
type: string
id:
example: b8f9c1c0-5b5a-4b1e-8c1c-0b5a4b1e8c1c
title: Id
type: string
keywords:
example:
- START
- BEGIN
items:
type: string
title: Keywords
type: array
op:
enum:
- start
- stop
- info
example: start
title: Op
type: string
resp_text:
example: Thank you for subscribing to our service.
title: Resp Text
type: string
updated_at:
format: date-time
title: Updated At
type: string
required:
- op
- keywords
- country_code
- id
- created_at
- updated_at
title: AutorespConfigSchema
type: object
OptOutListResponse:
properties:
data:
items:
$ref: '#/components/schemas/OptOutItem'
type: array
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
type: object
messaging_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/messaging_Error'
type: array
AutorespConfigResponseSchema:
properties:
data:
$ref: '#/components/schemas/AutorespConfigSchema'
required:
- data
title: AutorespConfigResponseSchema
type: object
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
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
AutoRespConfigCreateSchema:
properties:
country_code:
example: US
title: Country Code
type: string
keywords:
example:
- keyword1
- keyword2
items:
type: string
title: Keywords
type: array
op:
enum:
- start
- stop
- info
title: Op
type: string
resp_text:
example: Thank you for your message
title: Resp Text
type: string
required:
- op
- keywords
- country_code
title: AutoRespConfigCreateSchema
type: object
ToNumber:
description: Receiving address (+E.164 formatted phone number or short code).
example: +E.164
type: string
x-format: address
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
OptOutItem:
properties:
created_at:
description: The timestamp when the opt-out was created
example: '2025-04-28 12:00:38.631252+00:00'
format: date-time
type: string
from:
description: Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
type: string
x-format: address
keyword:
description: The keyword that triggered the opt-out.
example: STOP
type:
- string
- 'null'
messaging_profile_id:
description: Unique identifier for a messaging profile.
type:
- string
- 'null'
to:
$ref: '#/components/schemas/ToNumber'
type: object
responses:
messaging_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors'
description: Unexpected error
parameters:
PageConsolidated:
description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: The page number to load
minimum: 1
type: integer
size:
default: 20
description: The size of the page
maximum: 250
minimum: 1
type: integer
type: object
style: deepObject
securitySchemes:
bearerAuth:
scheme: bearer
type: http
branded-calling_bearerAuth:
description: API key passed as a Bearer token in the Authorization header
scheme: bearer
type: http
oauthClientAuth:
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
flows:
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
clientCredentials:
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
type: oauth2
outbound-voice-profiles_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
pronunciation-dicts_bearerAuth:
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
scheme: bearer
type: http
stored-payment-transactions_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http