# Beem SMS Python SDK
A professional Python SDK for sending SMS via the Beem SMS API. This package provides a simple, robust, and feature-rich interface for integrating SMS functionality into your Python applications.
## Features
- **Easy to use** - Simple, intuitive API
- **Robust error handling** - Comprehensive exception handling and validation
- **Phone number validation** - Built-in phone number validation and formatting
- **Retry logic** - Automatic retry on failures with exponential backoff
- **Logging support** - Detailed logging for debugging and monitoring
- **Type hints** - Full type hint support for better IDE experience
- **Security** - Secure credential handling
- **Bulk SMS** - Efficient bulk SMS sending with batching
- **Well tested** - Comprehensive test suite
- **CLI tool** - Command-line interface for quick operations
## Installation
```bash
pip install beem-sms-python
```
### Development Installation
```bash
git clone https://github.com/islandkid-20/beem-sms-python.git
cd beem-sms-python
pip install -e .[dev]
```
## Quick Start
### Basic Usage
```python
from beem_sms import BeemSMSClient
# Initialize client
client = BeemSMSClient(
api_key="your_api_key",
secret_key="your_secret_key"
)
# Send SMS
response = client.send_sms(
source_addr="YourApp",
dest_addr="+255742892731",
message="Hello from Beem SMS!"
)
if response.success:
print(f"SMS sent! Request ID: {response.request_id}")
else:
print(f"Failed: {response.message}")
```
### Using Context Manager
```python
from beem_sms import BeemSMSClient
with BeemSMSClient("api_key", "secret_key") as client:
response = client.send_sms(
source_addr="YourApp",
dest_addr="+255742892731",
message="Hello World!"
)
```
### Bulk SMS
```python
recipients = ["+255742892731", "+255783346386", "+255713521250"]
results = client.send_bulk_sms(
source_addr="YourApp",
recipients=recipients,
message="Bulk SMS message",
batch_size=10
)
successful = sum(1 for r in results if r.success)
print(f"Sent {successful}/{len(results)} batches successfully")
```
### Convenience Function
```python
from beem_sms import send_sms
response = send_sms(
api_key="your_api_key",
secret_key="your_secret_key",
source_addr="YourApp",
dest_addr="+255742892731",
message="Quick SMS!"
)
```
## CLI Usage
The package includes a command-line tool for quick SMS operations:
### Send SMS
```bash
beem-sms send --api-key YOUR_KEY --secret-key YOUR_SECRET \
--sender "YourApp" --message "Hello CLI!" \
--recipients "+255742892731" "+255783346386"
```
### Send Bulk SMS from File
```bash
# Create recipients.txt with one phone number per line
echo "+255742892731" > recipients.txt
echo "+255783346386" >> recipients.txt
beem-sms send --sender "YourApp" --message "Bulk message" \
--file recipients.txt --bulk --batch-size 50
```
### Validate Phone Numbers
```bash
beem-sms validate --numbers "+255742892731" "0783346386" "invalid"
```
### Configuration File
Create `~/.beem_sms.json`:
```json
{
"api_key": "your_api_key",
"secret_key": "your_secret_key"
}
```
Then use CLI without credentials:
```bash
beem-sms send --sender "YourApp" --message "Hello!" \
--recipients "+255742892731"
```
## Error Handling
The SDK provides specific exceptions for different error scenarios:
```python
from beem_sms import (
BeemSMSClient,
AuthenticationError,
ValidationError,
APIError,
NetworkError
)
client = BeemSMSClient("api_key", "secret_key")
try:
response = client.send_sms(
source_addr="YourApp",
dest_addr="+255742892731",
message="Test message"
)
except AuthenticationError:
print("Invalid API credentials")
except ValidationError as e:
print(f"Invalid input: {e}")
except NetworkError:
print("Network connection failed")
except APIError as e:
print(f"API error: {e}")
```
## Phone Number Validation
```python
from beem_sms import PhoneNumberValidator
# Validate single number
is_valid = PhoneNumberValidator.validate("+255742892731")
# Clean and format number
clean_number = PhoneNumberValidator.clean("0742892731")
# Returns: "+255742892731"
# Validate batch
numbers = ["+255742892731", "invalid", "0783346386"]
results = PhoneNumberValidator.validate_batch(numbers)
# Returns: [True, False, True]
```
## Advanced Configuration
```python
import logging
# Custom logger
logger = logging.getLogger("my_app")
client = BeemSMSClient(
api_key="your_api_key",
secret_key="your_secret_key",
base_url="https://custom-endpoint.com/v1/send", # Custom endpoint
timeout=60, # 60 second timeout
max_retries=5, # 5 retry attempts
logger=logger # Custom logger
)
```
## API Reference
### BeemSMSClient
#### Methods
- `send_sms(source_addr, dest_addr, message, encoding=SMSEncoding.PLAIN_TEXT)` - Send SMS to single or multiple recipients
- `send_bulk_sms(source_addr, recipients, message, encoding, batch_size=100)` - Send bulk SMS with batching
#### Parameters
- `source_addr` (str): Sender ID or phone number
- `dest_addr` (str | List[str]): Recipient phone number(s)
- `message` (str): SMS message content
- `encoding` (SMSEncoding): Message encoding (PLAIN_TEXT or UNICODE)
### SMSResponse
Response object with the following attributes:
- `success` (bool): Whether the operation succeeded
- `status_code` (int): HTTP status code
- `message` (str): Response message
- `response_data` (dict): Raw API response data
- `request_id` (str): Request ID for tracking
### Exceptions
- `SMSError` - Base exception
- `AuthenticationError` - Invalid credentials
- `ValidationError` - Invalid input parameters
- `APIError` - API request failed
- `NetworkError` - Network/connection issues
## Testing
Run the test suite:
```bash
# Run all tests
make test
# Run with coverage
make test-cov
# Run specific test file
pytest tests/test_client.py -v
```
## Development
Set up development environment:
```bash
make dev-setup
```
Run code quality checks:
```bash
make check # Runs format-check, lint, type-check, and test
```
Format code:
```bash
make format
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and code quality checks (`make check`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- Email: j1997ames@gmail.com
- Issues: [GitHub Issues](https://github.com/islandkid-20/beem-sms-python/issues)
- Documentation: [Read the Docs](https://beem-sms-python.readthedocs.io/)
## Changelog
### v1.0.2
* Adjusted message length limits to support multi-part SMS:
* Increased `MAX_MESSAGE_LENGTH` from `160` to `153 * 3`
* Increased `MAX_UNICODE_LENGTH` from `70` to `67 * 3`
### v1.0.1
- Initial release
- Basic SMS sending functionality
- Bulk SMS support
- Phone number validation
- CLI tool
- Comprehensive test suite
Raw data
{
"_id": null,
"home_page": "https://github.com/islandkid-20/beem-sms-python",
"name": "beem-sms-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sms, beem, tanzania, messaging, api, sdk",
"author": "James Mashaka",
"author_email": "James Mashaka <j1997ames@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/70/54/0795e0babbf6a45d5ea396b5e4070e21e1451186087a2a1db4e4aecb3022/beem_sms_python-1.0.2.tar.gz",
"platform": null,
"description": "# Beem SMS Python SDK\n\nA professional Python SDK for sending SMS via the Beem SMS API. This package provides a simple, robust, and feature-rich interface for integrating SMS functionality into your Python applications.\n\n## Features\n\n- **Easy to use** - Simple, intuitive API\n- **Robust error handling** - Comprehensive exception handling and validation\n- **Phone number validation** - Built-in phone number validation and formatting\n- **Retry logic** - Automatic retry on failures with exponential backoff\n- **Logging support** - Detailed logging for debugging and monitoring\n- **Type hints** - Full type hint support for better IDE experience\n- **Security** - Secure credential handling\n- **Bulk SMS** - Efficient bulk SMS sending with batching\n- **Well tested** - Comprehensive test suite\n- **CLI tool** - Command-line interface for quick operations\n\n## Installation\n\n```bash\npip install beem-sms-python\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/islandkid-20/beem-sms-python.git\ncd beem-sms-python\npip install -e .[dev]\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom beem_sms import BeemSMSClient\n\n# Initialize client\nclient = BeemSMSClient(\n api_key=\"your_api_key\",\n secret_key=\"your_secret_key\"\n)\n\n# Send SMS\nresponse = client.send_sms(\n source_addr=\"YourApp\",\n dest_addr=\"+255742892731\",\n message=\"Hello from Beem SMS!\"\n)\n\nif response.success:\n print(f\"SMS sent! Request ID: {response.request_id}\")\nelse:\n print(f\"Failed: {response.message}\")\n```\n\n### Using Context Manager\n\n```python\nfrom beem_sms import BeemSMSClient\n\nwith BeemSMSClient(\"api_key\", \"secret_key\") as client:\n response = client.send_sms(\n source_addr=\"YourApp\",\n dest_addr=\"+255742892731\", \n message=\"Hello World!\"\n )\n```\n\n### Bulk SMS\n\n```python\nrecipients = [\"+255742892731\", \"+255783346386\", \"+255713521250\"]\n\nresults = client.send_bulk_sms(\n source_addr=\"YourApp\",\n recipients=recipients,\n message=\"Bulk SMS message\",\n batch_size=10\n)\n\nsuccessful = sum(1 for r in results if r.success)\nprint(f\"Sent {successful}/{len(results)} batches successfully\")\n```\n\n### Convenience Function\n\n```python\nfrom beem_sms import send_sms\n\nresponse = send_sms(\n api_key=\"your_api_key\",\n secret_key=\"your_secret_key\",\n source_addr=\"YourApp\",\n dest_addr=\"+255742892731\",\n message=\"Quick SMS!\"\n)\n```\n\n## CLI Usage\n\nThe package includes a command-line tool for quick SMS operations:\n\n### Send SMS\n\n```bash\nbeem-sms send --api-key YOUR_KEY --secret-key YOUR_SECRET \\\n --sender \"YourApp\" --message \"Hello CLI!\" \\\n --recipients \"+255742892731\" \"+255783346386\"\n```\n\n### Send Bulk SMS from File\n\n```bash\n# Create recipients.txt with one phone number per line\necho \"+255742892731\" > recipients.txt\necho \"+255783346386\" >> recipients.txt\n\nbeem-sms send --sender \"YourApp\" --message \"Bulk message\" \\\n --file recipients.txt --bulk --batch-size 50\n```\n\n### Validate Phone Numbers\n\n```bash\nbeem-sms validate --numbers \"+255742892731\" \"0783346386\" \"invalid\"\n```\n\n### Configuration File\n\nCreate `~/.beem_sms.json`:\n\n```json\n{\n \"api_key\": \"your_api_key\",\n \"secret_key\": \"your_secret_key\"\n}\n```\n\nThen use CLI without credentials:\n\n```bash\nbeem-sms send --sender \"YourApp\" --message \"Hello!\" \\\n --recipients \"+255742892731\"\n```\n\n## Error Handling\n\nThe SDK provides specific exceptions for different error scenarios:\n\n```python\nfrom beem_sms import (\n BeemSMSClient,\n AuthenticationError,\n ValidationError,\n APIError,\n NetworkError\n)\n\nclient = BeemSMSClient(\"api_key\", \"secret_key\")\n\ntry:\n response = client.send_sms(\n source_addr=\"YourApp\",\n dest_addr=\"+255742892731\",\n message=\"Test message\"\n )\nexcept AuthenticationError:\n print(\"Invalid API credentials\")\nexcept ValidationError as e:\n print(f\"Invalid input: {e}\")\nexcept NetworkError:\n print(\"Network connection failed\")\nexcept APIError as e:\n print(f\"API error: {e}\")\n```\n\n## Phone Number Validation\n\n```python\nfrom beem_sms import PhoneNumberValidator\n\n# Validate single number\nis_valid = PhoneNumberValidator.validate(\"+255742892731\")\n\n# Clean and format number\nclean_number = PhoneNumberValidator.clean(\"0742892731\")\n# Returns: \"+255742892731\"\n\n# Validate batch\nnumbers = [\"+255742892731\", \"invalid\", \"0783346386\"]\nresults = PhoneNumberValidator.validate_batch(numbers)\n# Returns: [True, False, True]\n```\n\n## Advanced Configuration\n\n```python\nimport logging\n\n# Custom logger\nlogger = logging.getLogger(\"my_app\")\n\nclient = BeemSMSClient(\n api_key=\"your_api_key\",\n secret_key=\"your_secret_key\",\n base_url=\"https://custom-endpoint.com/v1/send\", # Custom endpoint\n timeout=60, # 60 second timeout\n max_retries=5, # 5 retry attempts\n logger=logger # Custom logger\n)\n```\n\n## API Reference\n\n### BeemSMSClient\n\n#### Methods\n\n- `send_sms(source_addr, dest_addr, message, encoding=SMSEncoding.PLAIN_TEXT)` - Send SMS to single or multiple recipients\n- `send_bulk_sms(source_addr, recipients, message, encoding, batch_size=100)` - Send bulk SMS with batching\n\n#### Parameters\n\n- `source_addr` (str): Sender ID or phone number\n- `dest_addr` (str | List[str]): Recipient phone number(s)\n- `message` (str): SMS message content\n- `encoding` (SMSEncoding): Message encoding (PLAIN_TEXT or UNICODE)\n\n### SMSResponse\n\nResponse object with the following attributes:\n\n- `success` (bool): Whether the operation succeeded\n- `status_code` (int): HTTP status code\n- `message` (str): Response message\n- `response_data` (dict): Raw API response data\n- `request_id` (str): Request ID for tracking\n\n### Exceptions\n\n- `SMSError` - Base exception\n- `AuthenticationError` - Invalid credentials\n- `ValidationError` - Invalid input parameters\n- `APIError` - API request failed\n- `NetworkError` - Network/connection issues\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\nmake test\n\n# Run with coverage\nmake test-cov\n\n# Run specific test file\npytest tests/test_client.py -v\n```\n\n## Development\n\nSet up development environment:\n\n```bash\nmake dev-setup\n```\n\nRun code quality checks:\n\n```bash\nmake check # Runs format-check, lint, type-check, and test\n```\n\nFormat code:\n\n```bash\nmake format\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests and code quality checks (`make check`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- Email: j1997ames@gmail.com\n- Issues: [GitHub Issues](https://github.com/islandkid-20/beem-sms-python/issues)\n- Documentation: [Read the Docs](https://beem-sms-python.readthedocs.io/)\n\n## Changelog\n\n\n### v1.0.2\n\n* Adjusted message length limits to support multi-part SMS:\n\n * Increased `MAX_MESSAGE_LENGTH` from `160` to `153 * 3`\n * Increased `MAX_UNICODE_LENGTH` from `70` to `67 * 3`\n\n### v1.0.1\n\n- Initial release\n- Basic SMS sending functionality\n- Bulk SMS support\n- Phone number validation\n- CLI tool\n- Comprehensive test suite\n",
"bugtrack_url": null,
"license": "MIT License - Copyright (c) 2025 James Mashaka",
"summary": "Professional Python SDK for Beem SMS API",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/islandkid-20/beem-sms-python",
"Repository": "https://github.com/islandkid-20/beem-sms-python"
},
"split_keywords": [
"sms",
" beem",
" tanzania",
" messaging",
" api",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b88cc586f5b01630e05736a06728d8625b140bc39fd6c994958485fe2502d179",
"md5": "5f8a4f48fef52daa3b956f66f9d9b8a3",
"sha256": "928b76674ab9550a1348588f2d698e99148ba99bbd0cbee2582bf7bcbc4ef7c4"
},
"downloads": -1,
"filename": "beem_sms_python-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f8a4f48fef52daa3b956f66f9d9b8a3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14270,
"upload_time": "2025-07-29T10:43:22",
"upload_time_iso_8601": "2025-07-29T10:43:22.795925Z",
"url": "https://files.pythonhosted.org/packages/b8/8c/c586f5b01630e05736a06728d8625b140bc39fd6c994958485fe2502d179/beem_sms_python-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "70540795e0babbf6a45d5ea396b5e4070e21e1451186087a2a1db4e4aecb3022",
"md5": "1ff16d77b5f19bc0ab74894055067cc8",
"sha256": "1172847dcf38eff669471ab7b5eeac489448986fd29de0e6a7202c179c33d792"
},
"downloads": -1,
"filename": "beem_sms_python-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1ff16d77b5f19bc0ab74894055067cc8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15132,
"upload_time": "2025-07-29T10:43:24",
"upload_time_iso_8601": "2025-07-29T10:43:24.958475Z",
"url": "https://files.pythonhosted.org/packages/70/54/0795e0babbf6a45d5ea396b5e4070e21e1451186087a2a1db4e4aecb3022/beem_sms_python-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 10:43:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "islandkid-20",
"github_project": "beem-sms-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
">=",
"1.26.0"
]
]
}
],
"lcname": "beem-sms-python"
}
JSON
