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

pip install beem-sms-python

Development Installation

git clone https://github.com/islandkid-20/beem-sms-python.git
cd beem-sms-python
pip install -e .[dev]

Quick Start

Basic Usage

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

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

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

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

beem-sms send --api-key YOUR_KEY --secret-key YOUR_SECRET \
    --sender "YourApp" --message "Hello CLI!" \
    --recipients "+255742892731" "+255783346386"

Send Bulk SMS from File

# 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

beem-sms validate --numbers "+255742892731" "0783346386" "invalid"

Configuration File

Create ~/.beem_sms.json:

{
    "api_key": "your_api_key",
    "secret_key": "your_secret_key"
}

Then use CLI without credentials:

beem-sms send --sender "YourApp" --message "Hello!" \
    --recipients "+255742892731"

Error Handling

The SDK provides specific exceptions for different error scenarios:

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

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

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:

# 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:

make dev-setup

Run code quality checks:

make check  # Runs format-check, lint, type-check, and test

Format code:

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 file for details.

Support

Changelog

v1.0.3

  • Added Read the Docs documentation support:

    • Created .readthedocs.yml configuration file

    • Set up Sphinx documentation with MyST parser

    • Added documentation dependencies (sphinx, sphinx-rtd-theme, myst-parser)

    • Documentation now auto-syncs with README.md content

    • Added support for PDF and EPUB formats

    • Documentation available at: https://beem-sms-python.readthedocs.io/

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