multi-sms 1.0.0

Multi-provider SMS OTP sending with automatic fallback (Fast2SMS, MSG91, Twilio, 2Factor)

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:

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":"[phone]"},
  {"method":"2FACTOR",  "api_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
]'

from multi_sms import send_sms_otp

ok = send_sms_otp("[phone]", "482910")

Option 2 — Pass methods directly

from multi_sms import send_sms_otp

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

Test mode (no real sends)

send_sms_otp("[phone]", "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. "[phone]"
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

FAST2SMS (best free option for India)

1. Sign up at fast2sms.com
2. Dashboard → Dev API → copy your API key

{"method":"FAST2SMS", "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

Phone numbers must be 10-digit Indian numbers. Pass with or without +91 — the library strips the prefix automatically.

MSG91 (reliable India SMS)

1. Sign up at 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

{"method":"MSG91", "api_key":"xxxxxxxxxx", "sender_id":"MYAPP", "template_id":"1234567890"}

TWILIO (global SMS)

1. Sign up at 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

{"method":"TWILIO", "account_sid":"ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "auth_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "from_number":"[phone]"}

2FACTOR (India SMS)

1. Sign up at 2factor.in → API Keys → copy your key

{"method":"2FACTOR", "api_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}

Phone numbers must be 10-digit Indian numbers. Pass with or without +91.

---

License

MIT