# NigeriaBulkSMS Python SDK
A production-grade Python SDK for the [NigeriaBulkSMS.com](https://nigeriabulksms.com/) API. This SDK provides a simple, robust, and type-safe way to integrate bulk SMS, voice messaging, and data fetching functionalities into your Python applications.
## Features
* 🚀 **Easy to use** - Simple and intuitive API
* 🛡️ **Robust error handling** - Comprehensive error types and validation
* 📱 **SMS & Voice** - Support for text messages, voice calls, and TTS
* 📊 **Data fetching** - Access to account balance, history, and more
## Installation
Install the package using pip:
```bash
pip install nigeriabulksms-sdk
```
## Basic Usage
First, import the `NigeriaBulkSMSClient` and initialize it with your username and password.
```python
from nigeriabulksms_sdk import NigeriaBulkSMSClient
from nigeriabulksms_sdk.exceptions import NigeriaBulkSMSException
# Replace with your actual API credentials
USERNAME = "YOUR_USERNAME"
PASSWORD = "YOUR_PASSWORD"
client = NigeriaBulkSMSClient(USERNAME, PASSWORD)
print("Testing NigeriaBulkSMS SDK...\n")
try:
# Send an SMS
print("Attempting to send SMS...")
sms_response = client.sms.send(
message="Hello from Python SDK test!",
sender="TestSender",
mobiles=["2348030000000"]
)
print(f"SMS Send Response: {sms_response}\n")
except NigeriaBulkSMSException as e:
print(f"Caught NigeriaBulkSMSException for SMS: {e.message} (Code: {e.code})\n")
except Exception as e:
print(f"Caught unexpected Exception for SMS: {e}\n")
try:
# Get account balance
print("Attempting to get balance...")
balance_response = client.data.get_balance()
print(f"Balance Response: {balance_response}\n")
except NigeriaBulkSMSException as e:
print(f"Caught NigeriaBulkSMSException for Balance: {e.message} (Code: {e.code})\n")
except Exception as e:
print(f"Caught unexpected Exception for Balance: {e}\n")
try:
# Test TTS call
print("Attempting to send TTS call...")
tts_response = client.call.send_tts(
message="This is a test text to speech message.",
sender="2348030000000", # Use a mobile number as sender for TTS
mobiles=["2348030000000"]
)
print(f"TTS Call Response: {tts_response}\n")
except NigeriaBulkSMSException as e:
print(f"Caught NigeriaBulkSMSException for TTS: {e.message} (Code: {e.code})\n")
except Exception as e:
print(f"Caught unexpected Exception for TTS: {e}\n")
```
## API Reference
### `NigeriaBulkSMSClient(username, password, base_url=None)`
The main client class to interact with the NigeriaBulkSMS API.
* `username` (str): Your NigeriaBulkSMS username.
* `password` (str): Your NigeriaBulkSMS password.
* `base_url` (str, optional): The base URL for the API. Defaults to `https://portal.nigeriabulksms.com/api/`.
### SMS Service (`client.sms`)
#### `send(message, sender, mobiles)`
Sends a text message to one or more mobile numbers.
* `message` (str): The content of the SMS message.
* `sender` (str): The sender ID (max 11 alphanumeric characters).
* `mobiles` (str or list): A single mobile number string or a list of mobile number strings. Numbers should be in international format (e.g., `2348030000000`).
### Call Service (`client.call`)
#### `send_tts(message, sender, mobiles)`
Sends a Text-to-Speech (TTS) call to one or more mobile numbers.
* `message` (str): The text to be converted to speech.
* `sender` (str): The sender ID.
* `mobiles` (str or list): A single mobile number string or a list of mobile number strings.
#### `send_audio(audio_reference, sender, mobiles)`
Sends a pre-recorded audio call to one or more mobile numbers using an audio reference.
* `audio_reference` (str): The reference ID of the uploaded audio file.
* `sender` (str): The sender ID.
* `mobiles` (str or list): A single mobile number string or a list of mobile number strings.
### Audio Service (`client.audio`)
#### `upload(url)`
Uploads an audio file from a given URL to the NigeriaBulkSMS platform.
* `url` (str): The URL of the audio file (e.g., `https://example.com/audio.mp3`).
### Data Service (`client.data`)
#### `get_balance()`
Retrieves the current account balance.
#### `get_profile()`
Retrieves the customer profile information.
#### `get_contacts()`
Retrieves the list of contacts.
#### `get_numbers()`
Retrieves the list of saved numbers.
#### `get_groups()`
Retrieves the list of groups.
#### `get_audios()`
Retrieves the list of saved audio files.
#### `get_history()`
Retrieves the message history.
#### `get_scheduled()`
Retrieves the list of scheduled messages.
#### `get_reports()`
Retrieves the delivery reports.
#### `get_payments()`
Retrieves the payment history.
## Error Handling
The SDK raises `NigeriaBulkSMSException` for API-specific errors. You should wrap your API calls in `try-except` blocks to handle these exceptions gracefully.
```python
from nigeriabulksms_sdk import NigeriaBulkSMSClient
from nigeriabulksms_sdk.exceptions import NigeriaBulkSMSException
client = NigeriaBulkSMSClient("YOUR_USERNAME", "YOUR_PASSWORD")
try:
response = client.sms.send("Test message", "TestApp", ["2348000000000"])
print(response)
except NigeriaBulkSMSException as e:
print(f"API Error: {e.message} (Code: {e.code})")
except Exception as e:
print(f"General Error: {e}")
```
Common error codes are:
* `100`: Incomplete request parameters
* `101`: Request denied
* `110`: Login status failed
* `111`: Login status denied
* `150`: Insufficient funds
* `191`: Internal error
For a full list of error codes, refer to the [official NigeriaBulkSMS API documentation](https://nigeriabulksms.com/sms-gateway-api-in-nigeria/).
## Contributing
Feel free to contribute to this SDK by submitting issues or pull requests on GitHub.
## License
This SDK is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
---
**Author:** Timothy Dake
* **LinkedIn:** [https://www.linkedin.com/in/timothy-dake-14801571/](https://www.linkedin.com/in/timothy-dake-14801571/)
* **X (formerly Twitter):** [@timothydake](https://twitter.com/timothydake)
* **Email:** [timdake4@gmail.com](mailto:timdake4@gmail.com)
Raw data
{
"_id": null,
"home_page": "https://github.com/timothydake/nigeriabulksms-python-sdk",
"name": "nigeriabulksms-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "sms, bulk sms, nigeria, messaging, api, sdk, voice, tts",
"author": "Timothy Dake",
"author_email": "timdake4@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/51/83/586b8837cdc2c62488153b9527b730bc852ab441f300bec97d4c68c7d6d6/nigeriabulksms_sdk-1.0.0.tar.gz",
"platform": null,
"description": "# NigeriaBulkSMS Python SDK\n\nA production-grade Python SDK for the [NigeriaBulkSMS.com](https://nigeriabulksms.com/) API. This SDK provides a simple, robust, and type-safe way to integrate bulk SMS, voice messaging, and data fetching functionalities into your Python applications.\n\n## Features\n\n* \ud83d\ude80 **Easy to use** - Simple and intuitive API\n* \ud83d\udee1\ufe0f **Robust error handling** - Comprehensive error types and validation\n* \ud83d\udcf1 **SMS & Voice** - Support for text messages, voice calls, and TTS\n* \ud83d\udcca **Data fetching** - Access to account balance, history, and more\n\n## Installation\n\nInstall the package using pip:\n\n```bash\npip install nigeriabulksms-sdk\n```\n\n## Basic Usage\n\nFirst, import the `NigeriaBulkSMSClient` and initialize it with your username and password.\n\n```python\nfrom nigeriabulksms_sdk import NigeriaBulkSMSClient\nfrom nigeriabulksms_sdk.exceptions import NigeriaBulkSMSException\n\n# Replace with your actual API credentials\nUSERNAME = \"YOUR_USERNAME\"\nPASSWORD = \"YOUR_PASSWORD\"\n\nclient = NigeriaBulkSMSClient(USERNAME, PASSWORD)\n\nprint(\"Testing NigeriaBulkSMS SDK...\\n\")\n\ntry:\n # Send an SMS\n print(\"Attempting to send SMS...\")\n sms_response = client.sms.send(\n message=\"Hello from Python SDK test!\",\n sender=\"TestSender\",\n mobiles=[\"2348030000000\"]\n )\n print(f\"SMS Send Response: {sms_response}\\n\")\n\nexcept NigeriaBulkSMSException as e:\n print(f\"Caught NigeriaBulkSMSException for SMS: {e.message} (Code: {e.code})\\n\")\nexcept Exception as e:\n print(f\"Caught unexpected Exception for SMS: {e}\\n\")\n\ntry:\n # Get account balance\n print(\"Attempting to get balance...\")\n balance_response = client.data.get_balance()\n print(f\"Balance Response: {balance_response}\\n\")\n\nexcept NigeriaBulkSMSException as e:\n print(f\"Caught NigeriaBulkSMSException for Balance: {e.message} (Code: {e.code})\\n\")\nexcept Exception as e:\n print(f\"Caught unexpected Exception for Balance: {e}\\n\")\n\ntry:\n # Test TTS call\n print(\"Attempting to send TTS call...\")\n tts_response = client.call.send_tts(\n message=\"This is a test text to speech message.\",\n sender=\"2348030000000\", # Use a mobile number as sender for TTS\n mobiles=[\"2348030000000\"]\n )\n print(f\"TTS Call Response: {tts_response}\\n\")\n\nexcept NigeriaBulkSMSException as e:\n print(f\"Caught NigeriaBulkSMSException for TTS: {e.message} (Code: {e.code})\\n\")\nexcept Exception as e:\n print(f\"Caught unexpected Exception for TTS: {e}\\n\")\n```\n\n## API Reference\n\n### `NigeriaBulkSMSClient(username, password, base_url=None)`\n\nThe main client class to interact with the NigeriaBulkSMS API.\n\n* `username` (str): Your NigeriaBulkSMS username.\n* `password` (str): Your NigeriaBulkSMS password.\n* `base_url` (str, optional): The base URL for the API. Defaults to `https://portal.nigeriabulksms.com/api/`.\n\n### SMS Service (`client.sms`)\n\n#### `send(message, sender, mobiles)`\n\nSends a text message to one or more mobile numbers.\n\n* `message` (str): The content of the SMS message.\n* `sender` (str): The sender ID (max 11 alphanumeric characters).\n* `mobiles` (str or list): A single mobile number string or a list of mobile number strings. Numbers should be in international format (e.g., `2348030000000`).\n\n### Call Service (`client.call`)\n\n#### `send_tts(message, sender, mobiles)`\n\nSends a Text-to-Speech (TTS) call to one or more mobile numbers.\n\n* `message` (str): The text to be converted to speech.\n* `sender` (str): The sender ID.\n* `mobiles` (str or list): A single mobile number string or a list of mobile number strings.\n\n#### `send_audio(audio_reference, sender, mobiles)`\n\nSends a pre-recorded audio call to one or more mobile numbers using an audio reference.\n\n* `audio_reference` (str): The reference ID of the uploaded audio file.\n* `sender` (str): The sender ID.\n* `mobiles` (str or list): A single mobile number string or a list of mobile number strings.\n\n### Audio Service (`client.audio`)\n\n#### `upload(url)`\n\nUploads an audio file from a given URL to the NigeriaBulkSMS platform.\n\n* `url` (str): The URL of the audio file (e.g., `https://example.com/audio.mp3`).\n\n### Data Service (`client.data`)\n\n#### `get_balance()`\n\nRetrieves the current account balance.\n\n#### `get_profile()`\n\nRetrieves the customer profile information.\n\n#### `get_contacts()`\n\nRetrieves the list of contacts.\n\n#### `get_numbers()`\n\nRetrieves the list of saved numbers.\n\n#### `get_groups()`\n\nRetrieves the list of groups.\n\n#### `get_audios()`\n\nRetrieves the list of saved audio files.\n\n#### `get_history()`\n\nRetrieves the message history.\n\n#### `get_scheduled()`\n\nRetrieves the list of scheduled messages.\n\n#### `get_reports()`\n\nRetrieves the delivery reports.\n\n#### `get_payments()`\n\nRetrieves the payment history.\n\n## Error Handling\n\nThe SDK raises `NigeriaBulkSMSException` for API-specific errors. You should wrap your API calls in `try-except` blocks to handle these exceptions gracefully.\n\n```python\nfrom nigeriabulksms_sdk import NigeriaBulkSMSClient\nfrom nigeriabulksms_sdk.exceptions import NigeriaBulkSMSException\n\nclient = NigeriaBulkSMSClient(\"YOUR_USERNAME\", \"YOUR_PASSWORD\")\n\ntry:\n response = client.sms.send(\"Test message\", \"TestApp\", [\"2348000000000\"])\n print(response)\nexcept NigeriaBulkSMSException as e:\n print(f\"API Error: {e.message} (Code: {e.code})\")\nexcept Exception as e:\n print(f\"General Error: {e}\")\n```\n\nCommon error codes are:\n\n* `100`: Incomplete request parameters\n* `101`: Request denied\n* `110`: Login status failed\n* `111`: Login status denied\n* `150`: Insufficient funds\n* `191`: Internal error\n\nFor a full list of error codes, refer to the [official NigeriaBulkSMS API documentation](https://nigeriabulksms.com/sms-gateway-api-in-nigeria/).\n\n## Contributing\n\nFeel free to contribute to this SDK by submitting issues or pull requests on GitHub.\n\n## License\n\nThis SDK is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).\n\n---\n\n**Author:** Timothy Dake\n* **LinkedIn:** [https://www.linkedin.com/in/timothy-dake-14801571/](https://www.linkedin.com/in/timothy-dake-14801571/)\n* **X (formerly Twitter):** [@timothydake](https://twitter.com/timothydake)\n* **Email:** [timdake4@gmail.com](mailto:timdake4@gmail.com)\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python SDK for the NigeriaBulkSMS API.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/timothydake/nigeriabulksms-python-sdk/issues",
"Documentation": "https://github.com/timothydake/nigeriabulksms-python-sdk#readme",
"Homepage": "https://github.com/timothydake/nigeriabulksms-python-sdk",
"Source Code": "https://github.com/timothydake/nigeriabulksms-python-sdk"
},
"split_keywords": [
"sms",
" bulk sms",
" nigeria",
" messaging",
" api",
" sdk",
" voice",
" tts"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b87946ae43abc68305ab66188c049d5925fee2c143960b5886e8a08fb48694f0",
"md5": "f6c3830018353b3d7019fc1c59427846",
"sha256": "a4ad224cba77a05a1c671e5d075552506beb3ba81725aab0d04975051372afdf"
},
"downloads": -1,
"filename": "nigeriabulksms_sdk-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f6c3830018353b3d7019fc1c59427846",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10731,
"upload_time": "2025-07-12T08:00:13",
"upload_time_iso_8601": "2025-07-12T08:00:13.875394Z",
"url": "https://files.pythonhosted.org/packages/b8/79/46ae43abc68305ab66188c049d5925fee2c143960b5886e8a08fb48694f0/nigeriabulksms_sdk-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5183586b8837cdc2c62488153b9527b730bc852ab441f300bec97d4c68c7d6d6",
"md5": "7adb638a3d9756083b93d8e54c5047f6",
"sha256": "fd8a5ad94894c4b67682a2ae6ade39156e247ee4a377c1a79d973e45a66cf66a"
},
"downloads": -1,
"filename": "nigeriabulksms_sdk-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "7adb638a3d9756083b93d8e54c5047f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 10046,
"upload_time": "2025-07-12T08:00:15",
"upload_time_iso_8601": "2025-07-12T08:00:15.327103Z",
"url": "https://files.pythonhosted.org/packages/51/83/586b8837cdc2c62488153b9527b730bc852ab441f300bec97d4c68c7d6d6/nigeriabulksms_sdk-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 08:00:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "timothydake",
"github_project": "nigeriabulksms-python-sdk",
"github_not_found": true,
"lcname": "nigeriabulksms-sdk"
}
JSON
