​
Python SMTP Integration

The Shoutbox Python library provides SMTP support for sending emails through our SMTP servers, offering an alternative to the REST API.

​
SMTP vs API Client

​
When to Use SMTP

  • Legacy system integration
  • Firewall restrictions on HTTP
  • Specific SMTP requirements
  • Need for custom SMTP settings
  • Direct server-to-server communication

​
When to Use API Client

  • Modern application development
  • RESTful architecture
  • Webhook support needed
  • Advanced analytics required
  • Simpler implementation preferred

​
Installation

Install using pip:

pip install shoutbox

​
Basic Usage

​
Simple Email

from shoutbox import SMTPClient, Email

client = SMTPClient(api_key='your-api-key')

email = Email(
    from_email="[email protected]",
    to="[email protected]",
    subject="Hello via SMTP",
    html="<h1>Welcome!</h1><p>This is a test email via SMTP.</p>"
)

success = client.send(email)

​
Multiple Recipients

from shoutbox import SMTPClient, Email, EmailAddress

client = SMTPClient()

email = Email(
    from_email="[email protected]",
    to=[
        EmailAddress("[email protected]", "John Doe"),
        EmailAddress("[email protected]", "Jane Smith")
    ],
    subject="Group Message",
    html="<h1>Hello Everyone!</h1>"
)

success = client.send(email)

​
With Attachments

from shoutbox import SMTPClient, Email, Attachment

client = SMTPClient()

# 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]
)

success = client.send(email)

​
Advanced Configuration

​
Custom SMTP Settings

from shoutbox import SMTPClient, Email

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)

​
Custom Headers

from shoutbox import SMTPClient, Email

client = SMTPClient()

email = Email(
    from_email="[email protected]",
    to="[email protected]",
    subject="Priority Message",
    html="<h1>Important!</h1>",
    headers={
        'X-Priority': '1',
        'X-MSMail-Priority': 'High',
        'Importance': 'High'
    }
)

success = client.send(email)

​
Error Handling

from shoutbox import SMTPClient, Email
from shoutbox.exceptions import ShoutboxError

client = SMTPClient()

try:
    email = Email(
        from_email="[email protected]",
        to="[email protected]",
        subject="Test Email",
        html="<h1>Test</h1>"
    )
    success = client.send(email)
except ShoutboxError as e:
    print(f"SMTP error: {e}")

​
Configuration Options

​
Client Settings

OptionTypeDefaultDescription
api_keystrNoneYour API key
hoststrsmtp.shoutbox.netSMTP server hostname
portint587SMTP server port
use_tlsboolTrueWhether to use TLS
timeoutint30Connection timeout in seconds

​
Security Considerations

  1. TLS Usage

    • Always use TLS in production
    • Verify SSL certificates
    • Use secure ports (587/465)

  2. Authentication

    • Use API key for authentication
    • Store credentials securely
    • Use environment variables

  3. Network Security

    • Configure firewalls appropriately
    • Monitor SMTP logs
    • Set appropriate timeouts

​
Best Practices

​
Connection Management

# Use context manager for automatic cleanup
with SMTPClient() as client:
    email = Email(
        from_email="[email protected]",
        to="[email protected]",
        subject="Test",
        html="<h1>Test</h1>"
    )
    success = client.send(email)

​
Bulk Sending

from shoutbox import SMTPClient, Email

client = SMTPClient()

# Create multiple emails
emails = [
    Email(
        from_email="[email protected]",
        to=f"recipient{i}@example.com",
        subject=f"Bulk Email {i}",
        html=f"<h1>Email {i}</h1>"
    )
    for i in range(1, 4)
]

# Send emails
for email in emails:
    try:
        success = client.send(email)
    except Exception as e:
        print(f"Failed to send to {email.to}: {e}")

​
Error Recovery

from shoutbox import SMTPClient, Email
import time

def send_with_retry(client, email, max_retries=3, delay=1):
    for attempt in range(max_retries):
        try:
            return client.send(email)
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(delay * (attempt + 1))

​
Testing

​
Mock SMTP Client

from shoutbox.testing import MockSMTPClient

# Create mock client
mock_client = MockSMTPClient()

# Test email sending
email = Email(
    from_email="[email protected]",
    to="[email protected]",
    subject="Test",
    html="<h1>Test</h1>"
)

# No actual SMTP connection will be made
success = mock_client.send(email)

​
Troubleshooting

​
Common Issues

  1. Connection Errors

    • Check network connectivity
    • Verify firewall settings
    • Confirm port availability

  2. Authentication Failures

    • Verify API key
    • Check credentials
    • Confirm TLS settings

  3. Timeout Issues

    • Adjust timeout settings
    • Check network latency
    • Monitor server response time

​
Logging

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('shoutbox.smtp')

client = SMTPClient()
# SMTP operations will now be logged

​
Migration

​
From API to SMTP

# Before (API Client)
api_client = ShoutboxClient()
response = api_client.send(email)

# After (SMTP Client)
smtp_client = SMTPClient()
success = smtp_client.send(email)  # Same email object works with both

​
Support

  • Technical documentation
  • GitHub Issues
  • Email support
  • Regular updates
  • Security patches