textbelt-utils 0.3.0

A lightweight Python package for interacting with the Textbelt SMS API

textbelt-utils

A lightweight Python package for interacting with the Textbelt SMS API. Send SMS messages, check delivery status, and handle webhook responses with a clean, type-hinted interface.

Features

• 🚀 Simple, intuitive API
• 📝 Type hints and dataclasses for better IDE support
• ✅ Webhook verification
• 🧪 Test mode support
• 🔐 One-Time Password (OTP) support
• 🏢 Custom sender name support
• 📨 Bulk SMS support with rate limiting
• ⚡ Async/sync clients for flexibility
• 0️⃣ Zero external dependencies beyond requests

Installation

pip install textbelt-utils

Quick Start

from textbelt_utils import TextbeltClient, SMSRequest

# Initialize client
client = TextbeltClient(api_key="your_api_key")

# Send an SMS
request = SMSRequest(
    phone="[phone]",
    message="Hello from textbelt-utils!",
    key="your_api_key"
)

response = client.send_sms(request)
print(f"Message sent! ID: {response.text_id}")

Features

Send SMS

from textbelt_utils import TextbeltClient, SMSRequest

client = TextbeltClient(api_key="your_api_key")

# Basic SMS
request = SMSRequest(
    phone="[phone]",
    message="Hello!",
    key="your_api_key"
)

# SMS with webhook for replies
request_with_webhook = SMSRequest(
    phone="[phone]",
    message="Reply to this message!",
    key="your_api_key",
    reply_webhook_url="https://your-site.com/webhook",
    webhook_data="custom_data"
)

# SMS with custom sender name
request_with_sender = SMSRequest(
    phone="[phone]",
    message="Message from your company!",
    key="your_api_key",
    sender="MyCompany"  # Set a custom sender name for this message
)

response = client.send_sms(request)

Bulk SMS

Send multiple SMS messages efficiently with rate limiting and batching:

from textbelt_utils import TextbeltClient, BulkSMSRequest

client = TextbeltClient(api_key="your_api_key")

# Send same message to multiple recipients
request = BulkSMSRequest(
    phones=["[phone]", "[phone]"],
    message="Broadcast message to all recipients!",
    batch_size=100,  # Process in batches of 100
    delay_between_messages=0.1  # 100ms delay between messages
)

# Or send individual messages to each recipient
request = BulkSMSRequest(
    phones=["[phone]", "[phone]"],
    individual_messages={
        "[phone]": "Custom message for recipient 1",
        "[phone]": "Different message for recipient 2"
    },
    batch_size=100,
    delay_between_messages=0.1
)

response = client.send_bulk_sms(request)
print(f"Total messages: {response.total_messages}")
print(f"Successful: {response.successful_messages}")
print(f"Failed: {response.failed_messages}")

# Check individual results
for phone, result in response.results.items():
    if result.text_id:
        status = client.check_status(result.text_id)
        print(f"{phone}: {status.status}")

Async Bulk SMS

Send messages concurrently with proper rate limiting:

from textbelt_utils import AsyncTextbeltClient, BulkSMSRequest
import asyncio

async def send_bulk():
    async with AsyncTextbeltClient(api_key="your_api_key") as client:
        request = BulkSMSRequest(
            phones=["[phone]", "[phone]"],
            message="Async bulk message!",
            batch_size=100,  # Process 100 messages concurrently
            delay_between_messages=0.1
        )
        
        response = await client.send_bulk_sms(request)
        print(f"Sent: {response.successful_messages}")
        print(f"Failed: {response.failed_messages}")

asyncio.run(send_bulk())

Sender Name

You can set a sender name for your SMS messages in two ways:

1. Account-wide: Set a default sender name in your Textbelt account settings at https://textbelt.com/account
2. Per-message: Set the sender parameter in your SMSRequest

The sender name is used for compliance purposes and helps recipients identify who sent the message. If you don't specify a sender name, Textbelt will automatically append your default sender name to the message (unless it already appears in the message content).

# Example with custom sender name
request = SMSRequest(
    phone="[phone]",
    message="Important update!",
    key="your_api_key",
    sender="MyCompany"  # This overrides your account's default sender name
)

Note: The sender name is used strictly for compliance purposes and does not override the "From" number for the SMS sender.

Check Message Status

status = client.check_status("text_id")
print(f"Message status: {status.status}")  # DELIVERED, SENT, SENDING, etc.

Check Quota

quota = client.check_quota()
print(f"Remaining messages: {quota.quota_remaining}")

Test Mode

# Send a test message (doesn't use quota)
response = client.send_test(request)

Webhook Verification

from textbelt_utils.utils import verify_webhook

is_valid = verify_webhook(
    api_key="your_api_key",
    timestamp="webhook_timestamp",
    signature="webhook_signature",
    payload="webhook_payload"
)

One-Time Password (OTP)

The package provides built-in support for generating and verifying one-time passwords:

from textbelt_utils import AsyncTextbeltClient, OTPGenerateRequest, OTPVerifyRequest

async def handle_otp():
    async with AsyncTextbeltClient(api_key="your_api_key") as client:
        # Generate and send OTP
        generate_request = OTPGenerateRequest(
            phone="[phone]",
            userid="[e-mail]",  # Unique identifier for your user
            key="your_api_key",
            message="Your verification code is $OTP",  # Optional custom message
            lifetime=180,  # Optional validity duration in seconds (default: 180)
            length=6      # Optional code length (default: 6)
        )
        
        response = await client.generate_otp(generate_request)
        print(f"OTP sent! Message ID: {response.text_id}")
        
        # Later, verify the OTP entered by the user
        verify_request = OTPVerifyRequest(
            otp="123456",    # Code entered by user
            userid="[e-mail]",  # Same userid used in generate
            key="your_api_key"
        )
        
        verify_response = await client.verify_otp(verify_request)
        if verify_response.is_valid_otp:
            print("OTP verified successfully!")
        else:
            print("Invalid OTP")

OTP Features

• Custom Messages: Use the $OTP placeholder in your message to control where the code appears
• Configurable Lifetime: Set how long the code remains valid (30-3600 seconds)
• Configurable Length: Choose the number of digits in the code (4-10 digits)
• No Extra Cost: OTP functionality is included in your regular SMS quota
• Automatic Cleanup: Invalid/expired codes are automatically cleaned up
• Input Validation: Built-in validation for phone numbers, message length, and code format

Error Handling

The package provides specific exceptions for different error cases:

from textbelt_utils.exceptions import (
    QuotaExceededError,
    InvalidRequestError,
    WebhookVerificationError,
    APIError
)

try:
    response = client.send_sms(request)
except QuotaExceededError:
    print("Out of quota!")
except InvalidRequestError as e:
    print(f"Invalid request: {e}")
except WebhookVerificationError:
    print("Webhook verification failed")
except APIError as e:
    print(f"API error: {e}")

Asynchronous Usage

from textbelt_utils import AsyncTextbeltClient, SMSRequest
import asyncio

async def main():
    async with AsyncTextbeltClient(api_key="your_api_key") as client:
        # Send SMS
        request = SMSRequest(
            phone="[phone]",
            message="Async hello!",
            key="your_api_key"
        )
        response = await client.send_sms(request)
        
        # Check status
        status = await client.check_status(response.text_id)
        
        # Check quota
        quota = await client.check_quota()

if __name__ == "__main__":
    asyncio.run(main())

Mixed Sync/Async Usage

from textbelt_utils import TextbeltClient, AsyncTextbeltClient, SMSRequest

# Synchronous
sync_client = TextbeltClient(api_key="your_api_key")
sync_response = sync_client.send_sms(request)

# Asynchronous
async def send_async():
    async with AsyncTextbeltClient(api_key="your_api_key") as client:
        async_response = await client.send_sms(request)

Development

Running Tests

poetry run python -m unittest discover tests

Testing Your Integration

Testing SMS

The package includes a test_send.py script to help you verify your Textbelt integration. To use it:

1. Set up your environment variables:

export TEXTBELT_API_KEY=your_api_key_here
export TEXTBELT_TEST_PHONE=your_phone_number_here  # E.164 format, e.g., [phone]

2. Run the test script:

poetry run python test_send.py

The script will:

• Send a test message (using test mode, won't use your quota)
• Display the message ID and delivery status
• Show your remaining quota

Testing OTP

The package also includes a test_otp.py script to help you test the OTP functionality interactively:

1. Set up your environment variables (optional):

export TEXTBELT_API_KEY=your_api_key_here
export TEXTBELT_TEST_PHONE=your_phone_number_here  # E.164 format, e.g., [phone]

2. Run the test script:

# Using environment variables
poetry run python test_otp.py

# Or provide values directly
poetry run python test_otp.py --phone [phone] --key your_api_key

The script will:

1. Generate and send an OTP to your phone
2. Wait for you to enter the code you received
3. Verify the code and show the result
4. Display your remaining quota

Example output:

🔐 Testing OTP functionality...

📤 Generating and sending OTP...
✅ OTP sent successfully!
📱 Message ID: 12345
💫 Remaining quota: 100

⌛ Waiting for OTP...
Enter the verification code you received (or Ctrl+C to cancel): 123456

🔍 Verifying OTP...
✅ OTP verified successfully!

Security Note

• Never commit test scripts with actual phone numbers or API keys
• Always use environment variables for sensitive data
• Add test scripts to your .gitignore if you modify them with any sensitive data

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

TODO

High Priority

• Add comprehensive webhook support
  • Add webhook handler/router functionality
  • Add webhook signature verification middleware
  • Add example webhook handlers for common use cases
  • Document webhook payload structure and events
  • Add webhook testing utilities

Medium Priority

• Add retry mechanism for failed API calls
• Add rate limiting support
• Add logging configuration options
• Add support for bulk SMS sending
• Add support for scheduling messages

Low Priority

• Add support for message templates
• Add support for contact lists/groups
• Add message history tracking
• Add support for delivery reports