Here you'll find documentation related to the Sinch Python SDK, including how to install it, initialize it, and start developing Python code using Sinch services.

To use Sinch services, you'll need a Sinch account and access keys. You can sign up for an account and create access keys at dashboard.sinch.com.

For more information on the Sinch APIs on which this SDK is based, refer to the official developer documentation portal.

• Prerequisites
• Installation
• Getting started
• Logging

• Python in one of the supported versions - 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
• pip
• Sinch account

You can install this package by typing: pip install sinch

The Sinch client provides access to the following Sinch products:

• Numbers API
• SMS API
• Conversation API (beta release)

To establish a connection with the Sinch backend, you must provide the appropriate credentials based on the API you intend to use. For security best practices, avoid hardcoding credentials. Instead, retrieve them from environment variables.

For the SMS API in Australia (AU), Brazil (BR), Canada (CA), the United States (US), and the European Union (EU), provide the following parameters:

from sinch import SinchClient

sinch_client = SinchClient(
    service_plan_id="service_plan_id",
    sms_api_token="api_token"
)

For all other Sinch APIs, including SMS in US and EU regions, use the following parameters:

from sinch import SinchClient

sinch_client = SinchClient(
    project_id="project_id",
    key_id="key_id",
    key_secret="key_secret"
)

You must set sms_region before using the SMS API and conversation_region before using the Conversation API—either in the SinchClient(...) constructor or on sinch_client.configuration before the first call to that product. See MIGRATION_GUIDE.md for examples.

Logging configuration for this SDK utilizes following hierarchy:

1. If no configuration was provided via logger_name or logger configurable, SDK will inherit configuration from the root logger with the Sinch prefix.
2. If logger_name configurable was provided, SDK will use logger related to that name. For example: myapp.sinch will inherit configuration from the myapp logger.
3. If logger (logger instance) configurable was provided, SDK will use that particular logger for all its logging operations.

If all logging returned by this SDK needs to be disabled, usage of NullHandler provided by the standard logging module is advised.

Usage example of the Numbers API via VirtualNumbers on the client (sinch_client.numbers)—list() returns your project’s active virtual numbers:

paginator = sinch_client.numbers.list(
    region_code="US",
    number_type="LOCAL",
)
for active_number in paginator.iterator():
    print(active_number)

Returned values are Pydantic model instances (for example ActiveNumber), including fields such as phone_number, region_code, type, and capabilities.

More examples live under examples/snippets on the main branch.

Each API throws a custom, API related exception for an unsuccessful backed call.

Example for Numbers API:

from sinch.domains.numbers.api.v1.exceptions import NumbersException

try:
    paginator = sinch_client.numbers.list(
        region_code="US",
        number_type="LOCAL",
    )
except NumbersException as err:
    pass

For handling all possible exceptions thrown by this SDK use SinchException (superclass of all Sinch exceptions) from sinch.core.exceptions.

By default, the HTTP implementation uses the requests library.

To use a custom HTTP client, inject your own transport during initialization:

sinch_client = SinchClient(
    key_id="key_id",
    key_secret="key_secret",
    project_id="some_project",
    transport=MyHTTPImplementation
)

Custom client has to obey types and methods described by HTTPTransport abstract base class:

class HTTPTransport(ABC):
    @abstractmethod
    def request(self, endpoint: HTTPEndpoint) -> HTTPResponse:
        pass

Note: Asynchronous HTTP clients are not supported. The transport must be a synchronous implementation.

This project is licensed under the Apache License. See the LICENSE file for the license text.