Install & Compatibility
Where this runs
tested against v4.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.366s · 21.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.344s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MessagingClient
✓ from telesign.messaging import MessagingClient
Verify
✓ from telesign.api import Verify
✗ from telesignenterprise.verify import VerifyClient
The `telesignenterprise` package is for 'Full-service' accounts and has different import paths for Verify services. For the 'telesign' (self-service) package, the older `telesign.api.Verify` is the correct import for basic verification methods, while `telesign.messaging.MessagingClient` is used for newer messaging features.
This quickstart demonstrates how to send an SMS message using the `MessagingClient`. It retrieves TeleSign credentials and the recipient's phone number from environment variables, or uses placeholders if not set. After initializing the client, it attempts to send a message and prints the API response.
import os
from telesign.messaging import MessagingClient
CUSTOMER_ID = os.environ.get('TELESIGN_CUSTOMER_ID', 'YOUR_CUSTOMER_ID')
API_KEY = os.environ.get('TELESIGN_API_KEY', 'YOUR_API_KEY')
PHONE_NUMBER = os.environ.get('TELESIGN_PHONE_NUMBER', '11234567890') # E.164 format
MESSAGE = "Your package has shipped!"
MESSAGE_TYPE = "ARN"
if CUSTOMER_ID == 'YOUR_CUSTOMER_ID' or API_KEY == 'YOUR_API_KEY':
print("Please set TELESIGN_CUSTOMER_ID and TELESIGN_API_KEY environment variables or replace placeholders.")
else:
try:
messaging_client = MessagingClient(CUSTOMER_ID, API_KEY)
response = messaging_client.message(PHONE_NUMBER, MESSAGE, MESSAGE_TYPE)
if response.ok:
print(f"Message sent successfully: {response.json}")
else:
print(f"Error sending message: {response.json}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingVersion 4.0.0 and 3.0.0 removed all functionality and methods for the Legacy Intelligence Use Case API and the App Verify SDK. Users relying on these legacy APIs must migrate to newer services.fixReview the TeleSign developer documentation for the latest Intelligence Cloud API and Verify API to re-implement functionality. The App Verify API SDK has been discontinued entirely.
affects: >=3.0.0
breakingWith TeleSign Python SDK v4.0.0 and the launch of Intelligence Cloud, legacy GET-based Intelligence methods (e.g., from `PhoneIdClient`) are no longer supported. Integrations using these methods must switch to POST-based methods (e.g., from `ScoreClient`).fixUpgrade to the latest SDK, ensure a `ScoreClient` instance is used, and replace calls to `PhoneIdClient` score methods with `ScoreClient` score methods. The Intelligence endpoint should be updated to `https://detect.telesign.com/intelligence/phone`, with the phone number submitted in the API request body.
affects: >=4.0.0
gotchaHTTP Keep-Alive connections can cause 'connection reset by peer' errors if idle for more than 499 seconds. While v2.3.1 added automatic HTTP session recycling, older integrations or specific network configurations might still encounter this.fixIf experiencing connection errors, instantiate the client with `pool_recycle` set to a value less than 499 (e.g., 300-480) to automatically refresh the HTTP session. Example: `MessagingClient(customer_id, api_key, pool_recycle=480)`.
affects: <4.0.1
gotchaVersions of the SDK prior to v4.0.1 and v3.0.1 may encounter issues with newer `setuptools` versions due to the removal of `pkg_resources`.fixUpgrade to version 4.0.1 or higher to resolve compatibility issues with `pkg_resources` and `setuptools`.
affects: <3.0.1, >=3.0.1,<4.0.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'telesign'
The 'telesign' library has not been installed in your Python environment.
fixRun `pip install telesign` to install the library.
TypeError: Client.__init__() missing 2 required positional arguments: 'customer_id' and 'api_key'
The TeleSign `Client` class was initialized without providing the necessary `customer_id` and `api_key` arguments.
fixProvide your TeleSign Customer ID and API Key when creating the client object: `client = Client(customer_id='YOUR_CUSTOMER_ID', api_key='YOUR_API_KEY')`.
TeleSignError: Authentication failed
The provided `customer_id` or `api_key` are incorrect, expired, or do not have the necessary permissions to access the TeleSign API.
fixVerify that your TeleSign Customer ID and API Key are correct and active in your TeleSign account dashboard.
TeleSignError: Invalid parameter 'phone_number'
The phone number provided to a TeleSign API endpoint (e.g., Verify, Messaging) is either missing, incorrectly formatted, or deemed invalid by the TeleSign service.
fixEnsure the phone number is provided in E.164 format (e.g., `+12135550123`) and is a valid, reachable number.
Upgrade
Version history
4.1.0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
No dependency data recorded yet.