Telnyx Python Library

Warnings

• breaking Malicious versions 4.87.1 and 4.87.2 were briefly published to PyPI, containing malicious code. If installed between 03:51 UTC and 10:13 UTC on March 27, 2026, your system may have been compromised.
  Fix: Immediately uninstall the affected versions (`pip uninstall telnyx`), then install a known clean version (e.g., `pip install telnyx==4.87.0` or the latest stable version not affected). Rotate all exposed credentials and audit systems for compromise.
• gotcha Telnyx recommends storing API keys as environment variables (`TELNYX_API_KEY`) and explicitly passing them to the client constructor, rather than setting `telnyx.api_key` globally, especially for applications requiring multiple keys or robust security practices.
  Fix: Use `api_key=os.environ.get("TELNYX_API_KEY")` when instantiating `telnyx.Telnyx()` or `telnyx.AsyncTelnyx()`. Never hardcode API keys or commit them to version control.
• gotcha Webhook signature verification now defaults to Ed25519. If you are handling webhooks, it's strongly recommended to verify signatures to ensure authenticity.
  Fix: Implement Ed25519 webhook signature verification in your webhook handler. Refer to the Telnyx documentation for specific implementation details for Python.
• gotcha The library is updated very frequently (sometimes daily), and while it generally follows SemVer, some backwards-incompatible changes may be released as minor versions if they affect static types, internal components, or are not expected to impact the majority of users.
  Fix: Regularly review release notes before upgrading and thoroughly test your application after updates to catch subtle breaking changes.
• gotcha The keyword `from` is a reserved word in Python but often an API parameter (e.g., in messaging). The library handles this by allowing `from_` as a keyword argument for such parameters.
  Fix: When an API parameter clashes with a Python reserved word, append an underscore (`_`) to the parameter name (e.g., `from_="..."`).
• gotcha When sending file data, ensure it is passed as a single parameter. An earlier bug caused issues if file data was incorrectly structured.
  Fix: Ensure your file upload logic conforms to the latest SDK examples for `telnyx.files.create()` or similar methods to avoid issues fixed in v4.104.1.

Install

• pip install telnyx Standard Install
• pip install telnyx[aiohttp] Install with aiohttp for async client

Imports

• Telnyx

  from telnyx import Telnyx

  For synchronous API calls.
• AsyncTelnyx

  from telnyx import AsyncTelnyx

  For asynchronous API calls.

Quickstart

Initializes the Telnyx client using an API key from an environment variable and attempts to list messaging profiles to verify connectivity and authentication. Replace `YOUR_TELNYX_API_KEY_HERE` with an actual key or ensure the `TELNYX_API_KEY` environment variable is set.

import os
import telnyx

# It is recommended to set TELNYX_API_KEY as an environment variable
# export TELNYX_API_KEY="YOUR_TELNYX_API_KEY"
api_key = os.environ.get("TELNYX_API_KEY", "YOUR_TELNYX_API_KEY_HERE")

if not api_key or api_key == "YOUR_TELNYX_API_KEY_HERE":
    print("Warning: TELNYX_API_KEY environment variable not set or is placeholder.")
    print("Please set TELNYX_API_KEY or replace 'YOUR_TELNYX_API_KEY_HERE' with your actual API key.")
    # In a production environment, you would likely exit or raise an error.

client = telnyx.Telnyx(api_key=api_key)

try:
    # Example: List messaging profiles to verify connectivity and API key
    print("Attempting to list messaging profiles...")
    messaging_profiles = client.messaging_profiles.list()
    print(f"Successfully retrieved {len(messaging_profiles.data)} messaging profiles.")
    if messaging_profiles.data:
        print(f"First profile ID: {messaging_profiles.data[0].id}")

except telnyx.APIStatusError as e:
    print(f"Telnyx API Error: {e.status_code} - {e.response.json()}")
    print("Please ensure your API key is valid and has the necessary permissions.")
except telnyx.APIConnectionError as e:
    print(f"Telnyx Connection Error: {e}")
    print("Please check your network connection.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")