Metadata-Version: 2.4
Name: smsnova-sdk
Version: 1.0.1
Summary: Official Python SDK for SMSNova temporary phone number and automated SMS OTP verification API.
Author-email: SMSNova Team <support@smsnova.net>
License-Expression: MIT
Project-URL: Homepage, https://smsnova.net
Project-URL: Documentation, https://github.com/smsnovaglobal/smsnova-sdk/tree/main/python
Project-URL: Repository, https://github.com/smsnovaglobal/smsnova-sdk
Project-URL: Issues, https://smsnova.net/contact
Keywords: temporary-phone-number,virtual-phone,otp-verification,sms-activation,smsnova,receive-sms-online
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Telephony
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# SMSNova Python SDK

[![PyPI version](https://img.shields.io/pypi/v/smsnova-sdk.svg)](https://pypi.org/project/smsnova-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/smsnova-sdk.svg)](https://pypi.org/project/smsnova-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)

The official Python client for requesting a [temporary phone number](https://smsnova.net), checking SMS activation inventory, and retrieving OTP verification messages through the SMSNova API.

Use temporary numbers only where permitted by applicable law, SMSNova's policies, and the target platform. Do not use this SDK for spam, fraud, account farming, or bypassing platform controls.

## Installation

```bash
python -m pip install smsnova-sdk
```

## Quick Start

```python
import os

from smsnova import SMSNova, SMSNovaError

client = SMSNova(os.environ["SMSNOVA_API_KEY"])

try:
    print(client.get_balance())
    order = client.get_number("telegram", "in")
    result = client.wait_for_otp(order["id"])
    print(result)
except SMSNovaError as error:
    print(error.status, error.code, error)
finally:
    client.close()
```

The client defaults to `https://smsnova.net/api/v1` with Bearer authentication. If your account uses a different documented API prefix, pass `base_url`:

```python
client = SMSNova(
    os.environ["SMSNOVA_API_KEY"],
    base_url=os.environ.get("SMSNOVA_API_URL", "https://smsnova.net/api/v1"),
    timeout=30,
)
```

## Methods

| Method | Description |
| --- | --- |
| `get_balance()` | Query the current account balance. |
| `get_services()` | Fetch available services and rates. |
| `get_countries()` | Fetch supported country codes. |
| `get_number(service_code, country_code="vn")` | Allocate a temporary number. |
| `get_otp(order_id)` | Retrieve the order, SMS content, and OTP. |
| `cancel_order(order_id)` | Cancel an active order. |
| `wait_for_otp(order_id, timeout=60, interval=3)` | Poll until an `otp` or `code` is returned. |

## Supported Countries & Regions

Availability and pricing can change. Call `get_countries()` for live inventory.

| Country or region | SMSNova information |
| --- | --- |
| India | [Temporary Phone Number India](https://smsnova.net/countries/india/) |
| United States | [Temporary Phone Number USA](https://smsnova.net/countries/usa/) |
| Nigeria | [Temporary Phone Number Nigeria](https://smsnova.net/countries/nigeria/) |
| Bangladesh | [Temporary Phone Number Bangladesh](https://smsnova.net/countries/bangladesh/) |
| Egypt | [Temporary Phone Number Egypt](https://smsnova.net/countries/egypt/) |
| All locations | [View all supported countries](https://smsnova.net/countries/) |

## Supported Services & Platforms

Service availability depends on country and current inventory. Call `get_services()` for live rates.

| Platform | SMS verification information |
| --- | --- |
| Telegram | [SMS Verification for Telegram](https://smsnova.net/services/telegram/) |
| Facebook | [SMS Verification for Facebook](https://smsnova.net/services/facebook/) |
| TikTok / Douyin | [SMS Verification for Tiktok](https://smsnova.net/services/tiktok-douyin/) |
| Google / Gmail / YouTube | [SMS Verification for Google](https://smsnova.net/services/google-gmail-youtube/) |
| X / Twitter | [SMS Verification for X](https://smsnova.net/services/x-twitter/) |
| Apple | [SMS Verification for Apple](https://smsnova.net/services/apple/) |
| All platforms | [View all supported services](https://smsnova.net/services/) |

## Security & Compliance

- Store API keys in a secrets manager or environment variable.
- Do not log credentials, authorization headers, full phone numbers, or SMS contents.
- Set reasonable polling intervals and handle rate limits returned by the API.
- Cancel unused orders and retain verification data only as long as necessary.
- Review the SMSNova [Privacy Policy](https://smsnova.net/privacy-policy) and comply with applicable laws and third-party platform terms.

To report a suspected vulnerability privately, email [support@smsnova.net](mailto:support@smsnova.net).

## Official Community & Socials

- YouTube: [https://www.youtube.com/@SMSNovaGlobal](https://www.youtube.com/@SMSNovaGlobal)
- X (Twitter): [https://x.com/SMSNovaGlobal](https://x.com/SMSNovaGlobal)
- Facebook: [https://facebook.com/SMSNovaGlobal](https://facebook.com/SMSNovaGlobal)
- Telegram: [https://t.me/SMSNovaGlobal](https://t.me/SMSNovaGlobal)
- Threads: [https://www.threads.net/@smsnovaglobal](https://www.threads.net/@smsnovaglobal)
- Pinterest: [https://pinterest.com/SMSNovaGlobal](https://pinterest.com/SMSNovaGlobal)
- Linktree: [https://linktr.ee/SMSNovaGlobal](https://linktr.ee/SMSNovaGlobal)
- Contact Support: [https://smsnova.net/contact](https://smsnova.net/contact)

## License

Released under the [MIT License](LICENSE). Source code is available in the [SMSNova SDK repository](https://github.com/smsnovaglobal/smsnova-sdk).
