Metadata-Version: 2.4
Name: multi-sms
Version: 1.0.0
Summary: Multi-provider SMS OTP sending with automatic fallback (Fast2SMS, MSG91, Twilio, 2Factor)
License: MIT
Project-URL: Homepage, https://github.com/yourusername/multi-sms
Project-URL: Issues, https://github.com/yourusername/multi-sms/issues
Keywords: sms,otp,fast2sms,msg91,twilio,2factor,india,fallback
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# multi-sms

**Multi-provider SMS OTP sending with automatic fallback.**

Configure a priority-ordered list of SMS providers. The library tries each one in order — on any failure it automatically moves to the next. First success wins.

```
pip install multi-sms
```

---

## Supported providers

| Method    | Free / Cost           | DLT India  | Notes                        |
|-----------|-----------------------|------------|------------------------------|
| FAST2SMS  | Rs50 free credits     | ✅ Built-in | Best for India               |
| MSG91     | No free tier          | ✅ Built-in | Reliable India SMS           |
| TWILIO    | $15 trial credit      | ⚠️ Manual  | Global, works everywhere     |
| 2FACTOR   | No free tier          | ✅ Built-in | India only                   |

DLT = TRAI registration required for Indian SMS delivery.

---

## Quick start

### Option 1 — Environment variable

Set `SMS_SEND_METHODS` to a JSON array:

```bash
export SMS_SEND_METHODS='[
  {"method":"FAST2SMS", "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
  {"method":"MSG91",    "api_key":"xxxxxxxxxx", "sender_id":"MYAPP", "template_id":"1234567890"},
  {"method":"TWILIO",   "account_sid":"ACxxxxxxxx", "auth_token":"xxxxxxxx", "from_number":"+12345678901"},
  {"method":"2FACTOR",  "api_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
]'
```

```python
from multi_sms import send_sms_otp

ok = send_sms_otp("+919876543210", "482910")
```

### Option 2 — Pass methods directly

```python
from multi_sms import send_sms_otp

methods = [
    {"method": "FAST2SMS", "api_key": "xxx"},
    {"method": "TWILIO",   "account_sid": "ACxxx", "auth_token": "xxx", "from_number": "+12345678901"},
]
ok = send_sms_otp("+919876543210", "482910", methods=methods)
```

### Test mode (no real sends)

```python
send_sms_otp("+919876543210", "482910", test_mode=True)
```

---

## API

### `send_sms_otp(to, otp, *, methods=None, test_mode=False) -> bool`

| Parameter   | Type           | Description                                                |
|-------------|----------------|------------------------------------------------------------|
| `to`        | `str`          | Recipient phone in E.164 format, e.g. `"+919876543210"`    |
| `otp`       | `str`          | The OTP string to deliver, e.g. `"482910"`                 |
| `methods`   | `list \| None` | Override the env-var provider list for this call           |
| `test_mode` | `bool`         | If `True`, log the OTP and return `True` without sending   |

Returns `True` on first successful send, `False` only if every provider fails.

### `load_methods(env_var="SMS_SEND_METHODS") -> list`

Re-read and parse the method list from an environment variable.

---

## Provider setup

<details>
<summary><strong>FAST2SMS</strong> (best free option for India)</summary>

1. Sign up at [fast2sms.com](https://fast2sms.com)
2. Dashboard → Dev API → copy your API key

```json
{"method":"FAST2SMS", "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
```
Phone numbers must be 10-digit Indian numbers. Pass with or without `+91` — the library strips the prefix automatically.
</details>

<details>
<summary><strong>MSG91</strong> (reliable India SMS)</summary>

1. Sign up at [msg91.com](https://msg91.com) → get API key
2. Create a DLT-approved template containing `{otp}` as the variable
3. Note your 6-character sender ID and the template ID

```json
{"method":"MSG91", "api_key":"xxxxxxxxxx", "sender_id":"MYAPP", "template_id":"1234567890"}
```
</details>

<details>
<summary><strong>TWILIO</strong> (global SMS)</summary>

1. Sign up at [twilio.com](https://twilio.com) → get Account SID and Auth Token
2. Buy a phone number to use as `from_number`
3. For India: complete DLT registration separately via Twilio's India SMS guide

```json
{"method":"TWILIO", "account_sid":"ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "auth_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "from_number":"+12345678901"}
```
</details>

<details>
<summary><strong>2FACTOR</strong> (India SMS)</summary>

1. Sign up at [2factor.in](https://2factor.in) → API Keys → copy your key

```json
{"method":"2FACTOR", "api_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
```
Phone numbers must be 10-digit Indian numbers. Pass with or without `+91`.
</details>

---

## License

MIT
