shoutbox-tluyben 0.1.2

A Python client for the Shoutbox Email API

Shoutbox.net Developer API - Python Library

Shoutbox.net is a Developer API designed to send transactional emails at scale. This documentation covers all Python integration methods, from direct API calls to full framework integration.

Integration Methods

There are four main ways to integrate with Shoutbox in Python:

1. Direct API calls (minimal dependencies)
2. Using our Python library with pip
3. SMTP integration
4. Web framework integration (Flask/Django)

1. Direct API Integration (Minimal Dependencies)

If you want minimal dependencies, you can make direct API calls using requests:

import requests

# Your API key from Shoutbox.net
api_key = 'your-api-key-here'

# Prepare email data
data = {
    'from': '[e-mail]',
    'to': '[e-mail]',
    'subject': 'Test Email',
    'html': '<h1>Hello!</h1><p>This is a test email.</p>',
    'name': 'Sender Name',
    'reply_to': '[e-mail]'
}

# Make the API call
response = requests.post(
    'https://api.shoutbox.net/send',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json=data
)

# Handle the response
if response.status_code >= 200 and response.status_code < 300:
    print("Email sent successfully!")
else:
    print(f"Failed to send email. Status code: {response.status_code}")

Direct API Features

• Minimal dependencies (only requests)
• Simple implementation
• Full control over the request
• Lightweight integration
• Suitable for simple implementations

2. Python Library with pip

Installation

pip install shoutbox

2.1 API Client Usage

The API client provides an object-oriented interface to the REST API:

from shoutbox import ShoutboxClient, Email, EmailAddress, Attachment

# Initialize client
api_key = os.getenv('SHOUTBOX_API_KEY') or 'your-api-key-here'
client = ShoutboxClient(api_key)

try:
    # Basic email
    email = Email(
        from_email="[e-mail]",
        to="[e-mail]",
        subject="Test Email",
        html="<h1>Hello!</h1><p>This is a test email.</p>",
        reply_to="[e-mail]"
    )

    client.send(email)
    
    # Email with attachments
    email_with_attachments = Email(
        from_email="[e-mail]",
        to="[e-mail]",
        subject="Test Email with Attachments",
        html="<h1>Hello!</h1><p>This email includes attachments.</p>",
        attachments=[
            # Just provide the filepath - content and type are handled automatically
            Attachment(filepath="path/to/document.pdf"),
            Attachment(filepath="path/to/spreadsheet.xlsx")
        ]
    )

    client.send(email_with_attachments)

    # You can still attach content directly if needed
    attachment = Attachment(
        filename='custom.txt',
        content=b"Custom content",
        content_type='text/plain'
    )

    email_with_custom = Email(
        from_email="[e-mail]",
        to="[e-mail]",
        subject="Test Email with Custom Attachment",
        html="<h1>Hello!</h1><p>This email includes a custom attachment.</p>",
        attachments=[attachment]
    )

    client.send(email_with_custom)

except Exception as e:
    print(f"Error: {str(e)}")

2.2 SMTP Client Usage

The SMTP client provides an alternative way to send emails:

from shoutbox import SMTPClient, Email

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

try:
    # Multiple recipients
    email = Email(
        from_email="[e-mail]",
        to=["[e-mail]", "[e-mail]"],
        subject="Test Email",
        html="<h1>Hello!</h1><p>This is a test email.</p>",
        headers={
            'X-Custom-Header': 'Custom Value',
            'X-Priority': '1'
        }
    )

    client.send(email)

except Exception as e:
    print(f"Error: {str(e)}")

Library Features

• Type-safe email options
• Built-in error handling
• Simple file attachment support (just provide filepath)
• Custom headers support
• Multiple recipient types (to, cc, bcc)
• Choice between API and SMTP clients

3. Web Framework Integration

Flask Integration

from flask import Flask
from shoutbox import ShoutboxClient, Email

app = Flask(__name__)
client = ShoutboxClient(api_key='your-api-key')

@app.route('/send-email', methods=['POST'])
def send_email():
    email = Email(
        from_email="[e-mail]",
        to=request.json['to'],
        subject=request.json['subject'],
        html=request.json['html']
    )
    
    result = client.send(email)
    return {'success': True}

Django Integration

1. Add configuration to settings.py:

SHOUTBOX_API_KEY = 'your-api-key'

2. Usage example:

from shoutbox import ShoutboxClient, Email

client = ShoutboxClient()

def send_notification(request):
    email = Email(
        from_email="[e-mail]",
        to="[e-mail]",
        subject="Notification",
        html="<h1>New notification</h1>"
    )
    
    client.send(email)
    return JsonResponse({'success': True})

Development

1. Clone the repository:

git clone https://github.com/shoutboxnet/shoutbox-python.git

2. Install dependencies:

pip install -r requirements-dev.txt

3. Run tests:

make test

Support

• GitHub Issues for bug reports
• Email support for critical issues
• Documentation for guides and examples
• Regular updates and maintenance

License

This library is licensed under the MIT License. See the LICENSE file for details.