Python Library Documentation
The Shoutbox Python library provides a robust, type-safe interface for sending emails through both REST API and SMTP protocols.
Installation
Install using pip:
API Client Usage
Basic Usage
from shoutbox import ShoutboxClient, Email
# Initialize client
client = ShoutboxClient(api_key='your-api-key')
# Create and send a basic email
email = Email(
from_email="[email protected]",
to="[email protected]",
subject="Hello World",
html="<h1>Welcome!</h1><p>This is a test email.</p>"
)
response = client.send(email)
With Named Recipients
from shoutbox import ShoutboxClient, Email, EmailAddress
client = ShoutboxClient()
email = Email(
from_email=EmailAddress("[email protected]", "Sender Name"),
to=[
EmailAddress("[email protected]", "John Doe"),
EmailAddress("[email protected]", "Jane Smith")
],
subject="Hello",
html="<h1>Welcome!</h1>"
)
response = client.send(email)
With Attachments
from shoutbox import ShoutboxClient, Email, Attachment
client = ShoutboxClient()
# Create attachment
with open('document.pdf', 'rb') as f:
attachment = Attachment(
filename='document.pdf',
content=f.read(),
content_type='application/pdf'
)
email = Email(
from_email="[email protected]",
to="[email protected]",
subject="Document Attached",
html="<h1>Please find the document attached</h1>",
attachments=[attachment]
)
response = client.send(email)
from shoutbox import ShoutboxClient, Email
client = ShoutboxClient()
email = Email(
from_email="[email protected]",
to="[email protected]",
subject="Priority Email",
html="<h1>Important Message</h1>",
headers={
'X-Priority': '1',
'X-Custom-Header': 'Custom Value'
}
)
response = client.send(email)
SMTP Client Usage
Basic SMTP Usage
from shoutbox import SMTPClient, Email
# Initialize SMTP client
client = SMTPClient(api_key='your-api-key')
# Create and send email
email = Email(
from_email="[email protected]",
to="[email protected]",
subject="Hello via SMTP",
html="<h1>Welcome!</h1>"
)
success = client.send(email)
Custom SMTP Settings
from shoutbox import SMTPClient, Email
# Initialize with custom settings
client = SMTPClient(
api_key='your-api-key',
host='custom.smtp.server',
port=465,
use_tls=True,
timeout=60
)
email = Email(
from_email="[email protected]",
to="[email protected]",
subject="Custom SMTP Test",
html="<h1>Custom SMTP Test</h1>"
)
success = client.send(email)
Email Object Reference
Properties
- from_email (str | EmailAddress): Sender’s email address
- to (str | list[str] | EmailAddress | list[EmailAddress]): Recipient(s)
- subject (str): Email subject
- html (str): HTML content
- reply_to (Optional[str | EmailAddress]): Reply-to address
- headers (Optional[dict]): Custom headers
- attachments (Optional[list[Attachment]]): File attachments
EmailAddress Properties
- email (str): Email address
- name (Optional[str]): Display name
Attachment Properties
- filename (str): Name of the file
- content (bytes): File content
- content_type (Optional[str]): MIME type
Error Handling
The library provides specific exceptions for different error cases:
from shoutbox import ShoutboxClient, Email
from shoutbox.exceptions import ShoutboxError, ValidationError, APIError
client = ShoutboxClient()
try:
email = Email(
from_email="[email protected]",
to="[email protected]",
subject="Test Email",
html="<h1>Test</h1>"
)
response = client.send(email)
except ValidationError as e:
print(f"Validation error: {e}")
except APIError as e:
print(f"API error (status {e.status_code}): {e}")
except ShoutboxError as e:
print(f"General error: {e}")
Client Configuration
API Client Options
- api_key (Optional[str]): Your API key (can be set via SHOUTBOX_API_KEY env var)
- base_url (Optional[str]): API base URL (defaults to https://api.shoutbox.net)
- timeout (Optional[int]): Request timeout in seconds (default: 30)
- verify_ssl (Optional[bool]): Whether to verify SSL certificates (default: True)
SMTP Client Options
- api_key (Optional[str]): Your API key (can be set via SHOUTBOX_API_KEY env var)
- host (Optional[str]): SMTP host (default: smtp.shoutbox.net)
- port (Optional[int]): SMTP port (default: 587)
- use_tls (Optional[bool]): Whether to use TLS (default: True)
- timeout (Optional[int]): Connection timeout in seconds (default: 30)
Best Practices
-
Environment Variables
- Store API keys in environment variables
- Use .env files for development
-
Error Handling
- Always wrap API calls in try-except blocks
- Handle specific exceptions appropriately
- Log errors for debugging
-
Resource Management
- Use context managers (with statements) for clients
- Close connections properly
-
Security
- Always use TLS for SMTP connections
- Validate email addresses
- Sanitize HTML content
-
Performance
- Reuse client instances
- Use bulk operations when possible
- Set appropriate timeouts
Testing
The library includes comprehensive test utilities:
from shoutbox.testing import MockShoutboxClient
# Create a mock client for testing
mock_client = MockShoutboxClient()
# Test your email sending logic
email = Email(
from_email="[email protected]",
to="[email protected]",
subject="Test",
html="<h1>Test</h1>"
)
# No actual API calls will be made
response = mock_client.send(email)
Migration Guide
From Direct API to Library
From SMTP to API Client
# Before (SMTP)
smtp_client = SMTPClient(api_key=api_key)
smtp_client.send(email)
# After (API)
api_client = ShoutboxClient(api_key=api_key)
api_client.send(email) # Same email object works with both
Support
- GitHub Issues for bug reports
- Email support for critical issues
- Regular updates and maintenance
- Backward compatibility guaranteed