Telnyx Fax - Python

Installation

pip install telnyx

Setup

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)

All examples below assume

client

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

import telnyx

try:
    result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
    print("Network error — check connectivity and retry")
except telnyx.RateLimitError:
    # 429: rate limited — wait and retry with exponential backoff
    import time
    time.sleep(1)  # Check Retry-After header for actual delay
except telnyx.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.status_code == 422:
        print("Validation error — check required fields and formats")

Common error codes:

401

403

404

422

429

Important Notes

• Phone numbers must be in E.164 format (e.g.,

  +13125550001

  ). Include the

  +

  prefix and country code. No spaces, dashes, or parentheses.
• Pagination: List methods return an auto-paginating iterator. Use

  for item in page_result:

  to iterate through all pages automatically.

List all Fax Applications

This endpoint returns a list of your Fax Applications inside the 'data' attribute of the response. You can adjust which applications are listed by using filters. Fax Applications are used to configure how you send and receive faxes using the Programmable Fax API with Telnyx.

GET /fax_applications

page = client.fax_applications.list()
page = page.data[0]
print(page.id)

Returns:

active

anchorsite_override

application_name

created_at

id

inbound

outbound

record_type

tags

updated_at

webhook_event_failover_url

webhook_event_url

webhook_timeout_secs

Creates a Fax Application

Creates a new Fax Application based on the parameters sent in the request. The application name and webhook URL are required. Once created, you can assign phone numbers to your application using the

/phone_numbers

POST /fax_applications

application_name

webhook_event_url

Optional:

active

anchorsite_override

inbound

outbound

tags

webhook_event_failover_url

webhook_timeout_secs

fax_application = client.fax_applications.create(
    application_name="fax-router",
    webhook_event_url="https://example.com",
)
print(fax_application.data)

Returns:

active

anchorsite_override

application_name

created_at

id

inbound

outbound

record_type

tags

updated_at

webhook_event_failover_url

webhook_event_url

webhook_timeout_secs

Retrieve a Fax Application

Return the details of an existing Fax Application inside the 'data' attribute of the response.

GET /fax_applications/{id}

fax_application = client.fax_applications.retrieve(
    "1293384261075731499",
)
print(fax_application.data)

Returns:

active

anchorsite_override

application_name

created_at

id

inbound

outbound

record_type

tags

updated_at

webhook_event_failover_url

webhook_event_url

webhook_timeout_secs

Update a Fax Application

Updates settings of an existing Fax Application based on the parameters of the request.

PATCH /fax_applications/{id}

application_name

webhook_event_url

Optional:

active

anchorsite_override

fax_email_recipient

inbound

outbound

tags

webhook_event_failover_url

webhook_timeout_secs

fax_application = client.fax_applications.update(
    id="1293384261075731499",
    application_name="fax-router",
    webhook_event_url="https://example.com",
)
print(fax_application.data)

Returns:

active

anchorsite_override

application_name

created_at

id

inbound

outbound

record_type

tags

updated_at

webhook_event_failover_url

webhook_event_url

webhook_timeout_secs

Deletes a Fax Application

Permanently deletes a Fax Application. Deletion may be prevented if the application is in use by phone numbers.

DELETE /fax_applications/{id}

fax_application = client.fax_applications.delete(
    "1293384261075731499",
)
print(fax_application.data)

Returns:

active

anchorsite_override

application_name

created_at

id

inbound

outbound

record_type

tags

updated_at

webhook_event_failover_url

webhook_event_url

webhook_timeout_secs

View a list of faxes

GET /faxes

page = client.faxes.list()
page = page.data[0]
print(page.id)

Returns:

client_state

connection_id

created_at

direction

from

from_display_name

id

media_name

media_url

preview_url

quality

record_type

status

store_media

stored_media_url

to

updated_at

webhook_failover_url

webhook_url

Send a fax

Send a fax. Files have size limits and page count limit validations. If a file is bigger than 50MB or has more than 350 pages it will fail with

file_size_limit_exceeded

page_count_limit_exceeded

POST /faxes

connection_id

from

to

Optional:

black_threshold

client_state

from_display_name

media_name

media_url

monochrome

preview_format

quality

store_media

store_preview

t38_enabled

webhook_url

fax = client.faxes.create(
    connection_id="234423",
    from_="+13125790015",
    to="+13127367276",
    media_url="https://example.com/document.pdf",
)
print(fax.data)

Returns:

client_state

connection_id

created_at

direction

from

from_display_name

id

media_name

media_url

preview_url

quality

record_type

status

store_media

stored_media_url

to

updated_at

webhook_failover_url

webhook_url

View a fax

GET /faxes/{id}

fax = client.faxes.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(fax.data)

Returns:

client_state

connection_id

created_at

direction

from

from_display_name

id

media_name

media_url

preview_url

quality

record_type

status

store_media

stored_media_url

to

updated_at

webhook_failover_url

webhook_url

Delete a fax

DELETE /faxes/{id}

client.faxes.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)

Cancel a fax

Cancel the outbound fax that is in one of the following states:

queued

media.processed

originated

sending

POST /faxes/{id}/actions/cancel

response = client.faxes.actions.cancel(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)

Returns:

result

Refresh a fax

Refreshes the inbound fax's media_url when it has expired

POST /faxes/{id}/actions/refresh

response = client.faxes.actions.refresh(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)

Returns:

result

Webhooks

Webhook Verification

Telnyx signs webhooks with Ed25519. Each request includes

telnyx-signature-ed25519

telnyx-timestamp

# In your webhook handler (e.g., Flask — use raw body, not parsed JSON):
@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    payload = request.get_data(as_text=True)  # raw body as string
    headers = dict(request.headers)
    try:
        event = client.webhooks.unwrap(payload, headers=headers)
    except Exception as e:
        print(f"Webhook verification failed: {e}")
        return "Invalid signature", 400
    # Signature valid — event is the parsed webhook payload
    print(f"Received event: {event.data.event_type}")
    return "OK", 200

The following webhook events are sent to your configured webhook URL. All webhooks include

telnyx-timestamp

telnyx-signature-ed25519

client.webhooks.unwrap()

fax.delivered

fax.failed

fax.media.processed

fax.queued

fax.sending.started

Webhook payload fields

fax.delivered

data.record_type

data.id

data.occurred_at

data.event_type

data.payload.call_duration_secs

data.payload.connection_id

data.payload.direction

data.payload.fax_id

data.payload.original_media_url

data.payload.media_name

data.payload.to

data.payload.from

data.payload.user_id

data.payload.page_count

data.payload.status

data.payload.client_state

meta.attempt

meta.delivered_to

fax.failed

data.record_type

data.id

data.occurred_at

data.event_type

data.payload.connection_id

data.payload.direction

data.payload.fax_id

data.payload.original_media_url

data.payload.media_name

data.payload.to

data.payload.from

data.payload.user_id

data.payload.failure_reason

data.payload.status

data.payload.client_state

meta.attempt

meta.delivered_to

fax.media.processed

data.record_type

data.id

data.occurred_at

data.event_type

data.payload.connection_id

data.payload.direction

data.payload.fax_id

data.payload.original_media_url

data.payload.media_name

data.payload.to

data.payload.from

data.payload.user_id

data.payload.status

data.payload.client_state

meta.attempt

meta.delivered_to

fax.queued

data.record_type

data.id

data.occurred_at

data.event_type

data.payload.connection_id

data.payload.direction

data.payload.fax_id

data.payload.original_media_url

data.payload.media_name

data.payload.to

data.payload.from

data.payload.user_id

data.payload.status

data.payload.client_state

meta.attempt

meta.delivered_to

fax.sending.started

data.record_type

data.id

data.occurred_at

data.event_type

data.payload.connection_id

data.payload.direction

data.payload.fax_id

data.payload.original_media_url

data.payload.media_name

data.payload.to

data.payload.from

data.payload.user_id

data.payload.status

data.payload.client_state

meta.attempt

meta.delivered_to