openapi: 3.2.0
info:
  version: 2.0.0
  x-latency-category: responsive
  x-endpoint-cost: light
  title: Telnyx Email Domains API
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Email Domains
  description: Email domain CRUD operations
paths:
  /email_domains:
    get:
      tags:
      - Email Domains
      summary: List email domains
      operationId: listEmailDomains
      parameters:
      - $ref: '#/components/parameters/email_PageNumber'
      - $ref: '#/components/parameters/DomainsPageSize'
      - $ref: '#/components/parameters/PageAfter'
      - $ref: '#/components/parameters/PageBefore'
      - name: sort
        in: query
        description: Field to sort by. Prefix with `-` for descending order.
        required: false
        schema:
          type: string
          enum:
          - created_at
          - -created_at
          - domain
          - -domain
      - name: filter[status]
        description: 'Filter domains by verification status: pending, verifying, verified, failed, degraded, or suspended.'
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/EmailDomainStatus'
      - name: filter[domain]
        in: query
        required: false
        description: Partial match on domain name (case-insensitive)
        schema:
          type: string
        example: example.com
      - name: filter[profile_id]
        in: query
        required: false
        description: Filter by profile UUID
        schema:
          type: string
          format: uuid
      - name: filter[type]
        description: 'Filter domains by type: custom, shared, or shared_inbound.'
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/EmailDomainType'
      - name: filter[usable_for_sending]
        description: Filter domains by whether they can currently be used to send email.
        in: query
        required: false
        schema:
          type: boolean
      - name: filter[usable_for_inbound]
        description: Filter domains by whether they can currently receive inbound email.
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: A paginated list of email domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDomainListResponse'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: 'Shared (`type: shared`) Telnyx-managed domains are included/readable for every account, in addition to the account''s own custom domains.'
    post:
      tags:
      - Email Domains
      summary: Create an email domain
      operationId: createEmailDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailDomainRequest'
            example:
              domain: example.com
              inbound_enabled: true
              tracking:
                open_tracking: true
                click_tracking: true
                unsubscribe_tracking: false
      responses:
        '201':
          description: Email domain created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDomainResponse'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: Registers a domain for email sending and optional inbound delivery. The response includes the domain configuration and current verification state.
  /email_domains/{domain_id}/rotate_dkim:
    post:
      tags:
      - Email Domains
      summary: Rotate the DKIM key for an email domain
      description: Generates a new DKIM key for the domain, activates it, and retires the previous key. The response includes the updated DKIM DNS records the customer must publish. Selectors are fixed, so rotation replaces the TXT value at the existing `._domainkey.` host rather than adding a second record — `old_selector_retained` is false and the new TXT value must be published promptly, since signing switches to the new key immediately and the old TXT value will no longer match. The previous key is retired to a `retiring` state (retained, not revoked) so it can be revoked after the DNS propagation grace period.
      operationId: rotateEmailDomainDKIMKey
      parameters:
      - $ref: '#/components/parameters/EmailDomainDomainId'
      responses:
        '201':
          description: DKIM key rotated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDomainDKIMRotationResponse'
              example:
                data:
                  record_type: email_domain_dkim_rotation
                  domain_id: 123e4567-e89b-12d3-a456-426614174002
                  domain: example.com
                  dkim:
                    id: 123e4567-e89b-12d3-a456-42661417400a
                    selector: telnyx1
                    algorithm: rsa-sha256
                    key_length: 2048
                    version: 2
                    status: active
                    activated_at: '2026-09-11T12:00:00Z'
                  previous_dkim_key:
                    id: 123e4567-e89b-12d3-a456-426614174009
                    selector: telnyx1
                    version: 1
                    status: retiring
                  old_selector_retained: false
                  dns_records:
                  - id: 123e4567-e89b-12d3-a456-42661417400b
                    purpose: dkim
                    record_type: TXT
                    host: telnyx1._domainkey.example.com
                    value: v=DKIM1; k=rsa; p=MIIBIjANBgkqh...
                    actual_value: null
                    priority: null
                    required: true
                    status: pending
        '403':
          description: 'Forbidden — shared email domains are managed by Telnyx and cannot have their DKIM keys rotated by this account.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainsErrorResponse'
              example:
                errors:
                - code: '10008'
                  title: Forbidden
                  detail: Shared email domains are managed by Telnyx and cannot have their DKIM keys rotated by this account
        '404':
          $ref: '#/components/responses/email_NotFound'
        '409':
          description: DKIM rotation conflicted with a concurrent operation on this domain. Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainsErrorResponse'
              example:
                errors:
                - code: '40901'
                  title: Conflict
                  detail: DKIM rotation conflicted with a concurrent operation on this domain. Safe to retry.
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /email_domains/{id}:
    delete:
      tags:
      - Email Domains
      summary: Delete an email domain
      operationId: deleteEmailDomain
      parameters:
      - $ref: '#/components/parameters/EmailDomainId'
      - name: force
        in: query
        required: false
        description: Required as true when deleting verified domains
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Email domain deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDomainResponse'
        '403':
          description: Forbidden — shared domains are read-only for non-owner accounts (error code 10008).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainsErrorResponse'
        '404':
          $ref: '#/components/responses/email_NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: Deletes an email domain configuration. Verified domains require `force=true`, and shared domains are read-only for non-owner accounts.
    get:
      tags:
      - Email Domains
      summary: Retrieve an email domain
      operationId: getEmailDomain
      parameters:
      - $ref: '#/components/parameters/EmailDomainId'
      responses:
        '200':
          description: Email domain details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDomainResponse'
        '404':
          $ref: '#/components/responses/email_NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: 'Shared (`type: shared`) Telnyx-managed domains are included/readable for every account, in addition to the account''s own custom domains.'
    patch:
      tags:
      - Email Domains
      summary: Update an email domain
      operationId: updateEmailDomain
      parameters:
      - $ref: '#/components/parameters/EmailDomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailDomainRequest'
            example:
              inbound_enabled: true
              tracking:
                open_tracking: false
      responses:
        '200':
          description: Email domain updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDomainResponse'
        '403':
          description: Forbidden — shared domains are read-only for non-owner accounts (error code 10008).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainsErrorResponse'
        '404':
          $ref: '#/components/responses/email_NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: Updates mutable settings for an existing email domain, including inbound delivery and tracking configuration. Shared domains are read-only for non-owner accounts.
  /email_domains/{id}/health:
    get:
      tags:
      - Email Domains
      summary: Get domain health summary
      description: Returns a summary of domain health including verification status and usability.
      operationId: getEmailDomainHealth
      parameters:
      - $ref: '#/components/parameters/EmailDomainId'
      responses:
        '200':
          description: Domain health summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDomainHealthResponse'
              example:
                data:
                  id: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
                  record_type: email_domain_health
                  status: verified
                  usable_for_sending: true
                  usable_for_inbound: false
                  verification:
                    ownership: verified
                    spf: verified
                    dkim: verified
                    dmarc: missing_optional
                    mx: not_required
                  checked_at: '2026-05-31T12:00:00Z'
        '404':
          $ref: '#/components/responses/email_NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    OffsetPaginationMeta:
      type: object
      required:
      - page_number
      - page_size
      - total_pages
      - total_results
      properties:
        page_number:
          type: integer
          minimum: 1
        page_size:
          type: integer
          minimum: 1
        total_pages:
          type: integer
          minimum: 0
        total_results:
          type: integer
          minimum: 0
    EmailDomainListResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmailDomain'
        meta:
          oneOf:
          - $ref: '#/components/schemas/OffsetPaginationMeta'
          - $ref: '#/components/schemas/email_CursorPaginationMeta'
    DomainsTrackingSettings:
      type: object
      properties:
        open_tracking:
          type: boolean
          default: false
          description: Inject a tracking pixel into HTML messages to record open events.
        click_tracking:
          type: boolean
          default: false
          description: Rewrite HTML links through a tracking redirect to record click events.
        unsubscribe_tracking:
          type: boolean
          default: true
          description: Add RFC 8058 List-Unsubscribe headers with a signed one-click unsubscribe URL. Enabled by default; Gmail/Yahoo bulk-sender rules require one-click unsubscribe support.
    DomainsErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/email_Error'
    EmailDomainVerification:
      type: object
      required:
      - ownership
      - spf
      - dkim
      - dmarc
      - mx
      properties:
        ownership:
          type: string
          enum:
          - pending
          - verified
          - not_required
        spf:
          type: string
          enum:
          - missing_optional
          - verified
          - failed
          - not_required
        dkim:
          type: string
          enum:
          - pending
          - verified
          - failed
        dmarc:
          type: string
          enum:
          - missing_optional
          - verified
          - failed
        mx:
          type: string
          enum:
          - not_required
          - pending
          - verified
          - failed
    EmailDomainStatus:
      type: string
      enum:
      - pending
      - verifying
      - verified
      - failed
      - degraded
      - suspended
    UpdateEmailDomainRequest:
      type: object
      properties:
        inbound_enabled:
          type: boolean
          description: Enable or disable inbound routing for this domain
        dmarc_policy:
          type: object
          allOf:
          - $ref: '#/components/schemas/EmailDMARCPolicy'
          nullable: true
          description: 'Update the DMARC policy. The recommended _dmarc TXT record is rebuilt and its verification reset to pending.

            '
        tracking:
          $ref: '#/components/schemas/DomainsTrackingSettings'
    DNSRecord:
      type: object
      required:
      - id
      - purpose
      - record_type
      - host
      - value
      - required
      - status
      properties:
        id:
          type: string
          format: uuid
        purpose:
          type: string
          enum:
          - ownership
          - spf
          - dkim
          - dmarc
          - mx
        record_type:
          type: string
          enum:
          - TXT
          - MX
        host:
          type: string
        value:
          type: string
        actual_value:
          type: string
          nullable: true
        priority:
          type: integer
          nullable: true
        required:
          type: boolean
        status:
          type: string
          enum:
          - pending
          - verified
          - failed
          - not_required
      example:
        id: 123e4567-e89b-12d3-a456-426614174001
        purpose: ownership
        record_type: TXT
        host: _telnyx-email.example.com
        value: telnyx-domain-verification=abc123
        actual_value: null
        priority: null
        required: true
        status: pending
    EmailDomainHealth:
      type: object
      required:
      - id
      - record_type
      - status
      - usable_for_sending
      - usable_for_inbound
      - verification
      - checked_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the email domain
        record_type:
          type: string
          enum:
          - email_domain_health
          description: Record type discriminator
        status:
          type: string
          enum:
          - pending
          - verifying
          - verified
          - failed
          - degraded
          - suspended
          description: Current domain status
        usable_for_sending:
          type: boolean
          description: Whether the domain is usable for sending email
        usable_for_inbound:
          type: boolean
          description: Whether the domain is usable for receiving inbound email
        verification:
          $ref: '#/components/schemas/EmailDomainVerification'
        checked_at:
          type: string
          format: date-time
          description: Timestamp of the last health check
    EmailDomainResponse:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/EmailDomain'
    CreateEmailDomainRequest:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
          example: example.com
        inbound_enabled:
          type: boolean
          default: false
          description: Enable inbound routing for this domain
        dmarc_policy:
          type: object
          allOf:
          - $ref: '#/components/schemas/EmailDMARCPolicy'
          nullable: true
          description: 'DMARC policy. Omit/null for the advisory default (v=DMARC1; p=none; rua=mailto:dmarc@telnyx.com).

            '
        tracking:
          $ref: '#/components/schemas/DomainsTrackingSettings'
    EmailDomainHealthResponse:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/EmailDomainHealth'
    EmailDomain:
      type: object
      required:
      - id
      - record_type
      - domain
      - type
      - status
      - usable_for_sending
      - usable_for_inbound
      - verification
      - dns_records
      - dkim
      - inbound
      - dmarc_policy
      - tracking
      - created_at
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        record_type:
          type: string
          enum:
          - email_domain
        domain:
          type: string
          example: example.com
        type:
          $ref: '#/components/schemas/EmailDomainType'
          description: 'Domain type. `custom` domains are account-owned (BYOD). `shared` domains are Telnyx-managed, visible to and usable by ALL accounts for sending, but read-only: only the owning (system) account may modify, verify, or delete them; other accounts receive 403 (code 10008).'
        status:
          $ref: '#/components/schemas/EmailDomainStatus'
        usable_for_sending:
          type: boolean
        usable_for_inbound:
          type: boolean
        verification:
          $ref: '#/components/schemas/EmailDomainVerification'
        dns_records:
          type: array
          items:
            $ref: '#/components/schemas/DNSRecord'
        dkim:
          $ref: '#/components/schemas/DKIMStatus'
        inbound:
          $ref: '#/components/schemas/InboundConfig'
        dmarc_policy:
          type: object
          allOf:
          - $ref: '#/components/schemas/EmailDMARCPolicy'
          nullable: true
          description: 'Customer DMARC policy. null means use the advisory default (v=DMARC1; p=none; rua=mailto:dmarc@telnyx.com).

            '
        tracking:
          $ref: '#/components/schemas/DomainsTrackingSettings'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        verified_at:
          type: string
          format: date-time
          nullable: true
        reputation:
          type: object
          description: Sender reputation for this domain (present on all domain responses).
          properties:
            band:
              type: string
              description: Reputation band, e.g. good/warn/poor.
            breakdown:
              type: object
              additionalProperties: true
            computed_at:
              type: string
              format: date-time
              nullable: true
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
        record_type: email_domain
        domain: example.com
        type: custom
        status: pending
        usable_for_sending: false
        usable_for_inbound: false
        verification:
          ownership: pending
          spf: missing_optional
          dkim: pending
          dmarc: missing_optional
          mx: not_required
        dns_records: []
        dkim:
          selector: null
          algorithm: null
          key_length: null
          active: false
          rotated_at: null
        inbound:
          enabled: false
          catch_all: false
          mx_required: false
        dmarc_policy:
          p: none
          pct: 100
          rua: mailto:dmarc@telnyx.com
        tracking:
          open_tracking: false
          click_tracking: false
          unsubscribe_tracking: false
        created_at: '2026-01-01T00:00:00Z'
        updated_at: '2026-01-01T00:00:00Z'
        verified_at: null
    email_CursorPaginationMeta:
      type: object
      required:
      - page_size
      - has_next
      - has_previous
      properties:
        page_size:
          type: integer
          minimum: 1
        next_cursor:
          type: string
          nullable: true
          description: Opaque cursor to fetch the next page
        previous_cursor:
          type: string
          nullable: true
          description: Opaque cursor to fetch the previous page
        has_next:
          type: boolean
        has_previous:
          type: boolean
    EmailDomainDKIMRotation:
      type: object
      description: 'Result of rotating a domain''s DKIM key. The new key is active and signing switches to it immediately; the previous key is retired to a `retiring` state (retained, not revoked) so it can be revoked after the DNS propagation grace period. Selectors are fixed, so the DKIM DNS record''s TXT value is replaced in place at the shared `<selector>._domainkey.<domain>` host — `old_selector_retained` is false and the returned dns_records carry the new value the customer must publish promptly.

        '
      required:
      - record_type
      - domain_id
      - domain
      - dkim
      - previous_dkim_key
      - old_selector_retained
      - dns_records
      properties:
        record_type:
          type: string
          enum:
          - email_domain_dkim_rotation
        domain_id:
          type: string
          format: uuid
        domain:
          type: string
        dkim:
          type: object
          description: The new active DKIM key.
          required:
          - id
          - selector
          - algorithm
          - key_length
          - version
          - status
          properties:
            id:
              type: string
              format: uuid
            selector:
              type: string
            algorithm:
              type: string
              enum:
              - rsa-sha256
            key_length:
              type: integer
              enum:
              - 2048
            version:
              type: integer
              description: Monotonically increasing per-domain key version.
              minimum: 1
            status:
              type: string
              enum:
              - active
            activated_at:
              type: string
              format: date-time
              nullable: true
        previous_dkim_key:
          type: object
          nullable: true
          description: 'The retired previous key, or null when the domain had no active key before rotation. Retained in a `retiring` state so it can be revoked after the DNS propagation grace period.

            '
          required:
          - id
          - selector
          - version
          - status
          properties:
            id:
              type: string
              format: uuid
            selector:
              type: string
            version:
              type: integer
            status:
              type: string
              enum:
              - retiring
              - revoked
        old_selector_retained:
          type: boolean
          description: 'False for this service: one selector is fixed per domain, so rotation replaces the TXT value at the existing _domainkey host. There is no dual-selector overlap; publish the replacement TXT promptly because signing switches immediately.'
        dns_records:
          type: array
          description: 'The DKIM DNS records the customer must publish, carrying the new key''s TXT value with verification reset to pending.

            '
          items:
            $ref: '#/components/schemas/DNSRecord'
      example:
        record_type: email_domain_dkim_rotation
        domain_id: 123e4567-e89b-12d3-a456-426614174002
        domain: example.com
        dkim:
          id: 123e4567-e89b-12d3-a456-42661417400a
          selector: telnyx1
          algorithm: rsa-sha256
          key_length: 2048
          version: 2
          status: active
          activated_at: '2026-09-11T12:00:00Z'
        previous_dkim_key:
          id: 123e4567-e89b-12d3-a456-426614174009
          selector: telnyx1
          version: 1
          status: retiring
        old_selector_retained: false
        dns_records:
        - id: 123e4567-e89b-12d3-a456-42661417400b
          purpose: dkim
          record_type: TXT
          host: telnyx1._domainkey.example.com
          value: v=DKIM1; k=rsa; p=MIIBIjANBgkqh...
          actual_value: null
          priority: null
          required: true
          status: pending
    EmailDomainDKIMRotationResponse:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/EmailDomainDKIMRotation'
    DKIMStatus:
      type: object
      required:
      - selector
      - algorithm
      - key_length
      - active
      - rotated_at
      properties:
        selector:
          type: string
          nullable: true
        algorithm:
          type: string
          enum:
          - rsa-sha256
          - null
          nullable: true
        key_length:
          type: integer
          enum:
          - 2048
          - null
          nullable: true
        active:
          type: boolean
        rotated_at:
          type: string
          format: date-time
          nullable: true
    InboundConfig:
      type: object
      required:
      - enabled
      - catch_all
      - mx_required
      properties:
        enabled:
          type: boolean
        catch_all:
          type: boolean
        mx_required:
          type: boolean
    EmailDMARCPolicy:
      type: object
      description: DMARC policy for a sending domain. Drives the recommended _dmarc.<domain> TXT record. DMARC is advisory and never blocks sending. When omitted or null, the domain uses the advisory default (v=DMARC1; p=none; rua=mailto:dmarc@telnyx.com).
      properties:
        p:
          type: string
          enum:
          - none
          - quarantine
          - reject
          default: none
          description: Policy applied to messages that fail alignment.
        pct:
          type: integer
          minimum: 0
          maximum: 100
          default: 100
          description: Percentage of messages the policy applies to. Omitted from the record when 100.
        rua:
          type: string
          nullable: true
          description: URI for aggregate reports. Defaults to the Telnyx address when absent; null omits it.
        sp:
          type: string
          enum:
          - none
          - quarantine
          - reject
          nullable: true
          description: Policy for subdomains. Omitted from the record when null.
    email_Error:
      type: object
      required:
      - code
      - title
      - detail
      properties:
        code:
          type: string
          enum:
          - '10001'
          - '10015'
          - '500'
          - '10007'
          - '10008'
          - '10020'
          - '40901'
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              type: string
    EmailDomainType:
      type: string
      enum:
      - custom
      - shared
      - shared_inbound
  parameters:
    PageBefore:
      name: page[before]
      in: query
      required: false
      description: Cursor for records before the provided value (cursor pagination)
      schema:
        type: string
    DomainsPageSize:
      name: page[size]
      in: query
      required: false
      description: Number of records per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    PageAfter:
      name: page[after]
      in: query
      required: false
      description: Cursor for records after the provided value (cursor pagination)
      schema:
        type: string
    EmailDomainDomainId:
      name: domain_id
      in: path
      required: true
      description: Email domain UUID
      schema:
        type: string
        format: uuid
    email_PageNumber:
      name: page[number]
      in: query
      required: false
      description: Page number to return (offset pagination)
      schema:
        type: integer
        minimum: 1
        default: 1
    EmailDomainId:
      name: id
      in: path
      required: true
      description: Email domain UUID
      schema:
        type: string
        format: uuid
  responses:
    ValidationFailed:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DomainsErrorResponse'
          example:
            errors:
            - code: '10015'
              title: Validation Failed
              detail: domain is invalid
              source:
                pointer: /data/attributes/domain
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DomainsErrorResponse'
          example:
            errors:
            - code: '500'
              title: Internal Server Error
              detail: An unexpected error occurred
    email_NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DomainsErrorResponse'
          example:
            errors:
            - code: '10001'
              title: Not Found
              detail: The requested email domain was not found
  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
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt