# 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`:
```python
import requests
# Your API key from Shoutbox.net
api_key = 'your-api-key-here'
# Prepare email data
data = {
'from': 'sender@example.com',
'to': 'recipient@example.com',
'subject': 'Test Email',
'html': '<h1>Hello!</h1><p>This is a test email.</p>',
'name': 'Sender Name',
'reply_to': 'reply@example.com'
}
# 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
```bash
pip install shoutbox
```
### 2.1 API Client Usage
The API client provides an object-oriented interface to the REST API:
```python
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="sender@example.com",
to="recipient@example.com",
subject="Test Email",
html="<h1>Hello!</h1><p>This is a test email.</p>",
reply_to="reply@example.com"
)
client.send(email)
# Email with attachments
email_with_attachments = Email(
from_email="sender@example.com",
to="recipient@example.com",
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="sender@example.com",
to="recipient@example.com",
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:
```python
from shoutbox import SMTPClient, Email
client = SMTPClient('your-api-key-here')
try:
# Multiple recipients
email = Email(
from_email="sender@example.com",
to=["recipient1@example.com", "recipient2@example.com"],
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
```python
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="your-app@domain.com",
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`:
```python
SHOUTBOX_API_KEY = 'your-api-key'
```
2. Usage example:
```python
from shoutbox import ShoutboxClient, Email
client = ShoutboxClient()
def send_notification(request):
email = Email(
from_email="your-app@domain.com",
to="recipient@example.com",
subject="Notification",
html="<h1>New notification</h1>"
)
client.send(email)
return JsonResponse({'success': True})
```
## Development
1. Clone the repository:
```bash
git clone https://github.com/shoutboxnet/shoutbox-python.git
```
2. Install dependencies:
```bash
pip install -r requirements-dev.txt
```
3. Run tests:
```bash
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](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/shoutboxnet/python",
"name": "shoutbox-tluyben",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "email, api, client",
"author": "Your Name",
"author_email": "Tycho Luyben <tycho@e-lab.nl>",
"download_url": "https://files.pythonhosted.org/packages/1f/b9/d0ebf61b70896d9134ef8511cd229fafd840f930b74edc567733fde37449/shoutbox_tluyben-0.1.1.tar.gz",
"platform": null,
"description": "# Shoutbox.net Developer API - Python Library\n\nShoutbox.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.\n\n## Integration Methods\n\nThere are four main ways to integrate with Shoutbox in Python:\n\n1. Direct API calls (minimal dependencies)\n2. Using our Python library with pip\n3. SMTP integration\n4. Web framework integration (Flask/Django)\n\n## 1. Direct API Integration (Minimal Dependencies)\n\nIf you want minimal dependencies, you can make direct API calls using `requests`:\n\n```python\nimport requests\n\n# Your API key from Shoutbox.net\napi_key = 'your-api-key-here'\n\n# Prepare email data\ndata = {\n 'from': 'sender@example.com',\n 'to': 'recipient@example.com',\n 'subject': 'Test Email',\n 'html': '<h1>Hello!</h1><p>This is a test email.</p>',\n 'name': 'Sender Name',\n 'reply_to': 'reply@example.com'\n}\n\n# Make the API call\nresponse = requests.post(\n 'https://api.shoutbox.net/send',\n headers={\n 'Authorization': f'Bearer {api_key}',\n 'Content-Type': 'application/json'\n },\n json=data\n)\n\n# Handle the response\nif response.status_code >= 200 and response.status_code < 300:\n print(\"Email sent successfully!\")\nelse:\n print(f\"Failed to send email. Status code: {response.status_code}\")\n```\n\n### Direct API Features\n- Minimal dependencies (only requests)\n- Simple implementation\n- Full control over the request\n- Lightweight integration\n- Suitable for simple implementations\n\n## 2. Python Library with pip\n\n### Installation\n\n```bash\npip install shoutbox\n```\n\n### 2.1 API Client Usage\n\nThe API client provides an object-oriented interface to the REST API:\n\n```python\nfrom shoutbox import ShoutboxClient, Email, EmailAddress, Attachment\n\n# Initialize client\napi_key = os.getenv('SHOUTBOX_API_KEY') or 'your-api-key-here'\nclient = ShoutboxClient(api_key)\n\ntry:\n # Basic email\n email = Email(\n from_email=\"sender@example.com\",\n to=\"recipient@example.com\",\n subject=\"Test Email\",\n html=\"<h1>Hello!</h1><p>This is a test email.</p>\",\n reply_to=\"reply@example.com\"\n )\n\n client.send(email)\n \n # Email with attachments\n email_with_attachments = Email(\n from_email=\"sender@example.com\",\n to=\"recipient@example.com\",\n subject=\"Test Email with Attachments\",\n html=\"<h1>Hello!</h1><p>This email includes attachments.</p>\",\n attachments=[\n # Just provide the filepath - content and type are handled automatically\n Attachment(filepath=\"path/to/document.pdf\"),\n Attachment(filepath=\"path/to/spreadsheet.xlsx\")\n ]\n )\n\n client.send(email_with_attachments)\n\n # You can still attach content directly if needed\n attachment = Attachment(\n filename='custom.txt',\n content=b\"Custom content\",\n content_type='text/plain'\n )\n\n email_with_custom = Email(\n from_email=\"sender@example.com\",\n to=\"recipient@example.com\",\n subject=\"Test Email with Custom Attachment\",\n html=\"<h1>Hello!</h1><p>This email includes a custom attachment.</p>\",\n attachments=[attachment]\n )\n\n client.send(email_with_custom)\n\nexcept Exception as e:\n print(f\"Error: {str(e)}\")\n```\n\n### 2.2 SMTP Client Usage\n\nThe SMTP client provides an alternative way to send emails:\n\n```python\nfrom shoutbox import SMTPClient, Email\n\nclient = SMTPClient('your-api-key-here')\n\ntry:\n # Multiple recipients\n email = Email(\n from_email=\"sender@example.com\",\n to=[\"recipient1@example.com\", \"recipient2@example.com\"],\n subject=\"Test Email\",\n html=\"<h1>Hello!</h1><p>This is a test email.</p>\",\n headers={\n 'X-Custom-Header': 'Custom Value',\n 'X-Priority': '1'\n }\n )\n\n client.send(email)\n\nexcept Exception as e:\n print(f\"Error: {str(e)}\")\n```\n\n### Library Features\n- Type-safe email options\n- Built-in error handling\n- Simple file attachment support (just provide filepath)\n- Custom headers support\n- Multiple recipient types (to, cc, bcc)\n- Choice between API and SMTP clients\n\n## 3. Web Framework Integration\n\n### Flask Integration\n\n```python\nfrom flask import Flask\nfrom shoutbox import ShoutboxClient, Email\n\napp = Flask(__name__)\nclient = ShoutboxClient(api_key='your-api-key')\n\n@app.route('/send-email', methods=['POST'])\ndef send_email():\n email = Email(\n from_email=\"your-app@domain.com\",\n to=request.json['to'],\n subject=request.json['subject'],\n html=request.json['html']\n )\n \n result = client.send(email)\n return {'success': True}\n```\n\n### Django Integration\n\n1. Add configuration to `settings.py`:\n```python\nSHOUTBOX_API_KEY = 'your-api-key'\n```\n\n2. Usage example:\n```python\nfrom shoutbox import ShoutboxClient, Email\n\nclient = ShoutboxClient()\n\ndef send_notification(request):\n email = Email(\n from_email=\"your-app@domain.com\",\n to=\"recipient@example.com\",\n subject=\"Notification\",\n html=\"<h1>New notification</h1>\"\n )\n \n client.send(email)\n return JsonResponse({'success': True})\n```\n\n## Development\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/shoutboxnet/shoutbox-python.git\n```\n\n2. Install dependencies:\n```bash\npip install -r requirements-dev.txt\n```\n\n3. Run tests:\n```bash\nmake test\n```\n\n## Support\n\n- GitHub Issues for bug reports\n- Email support for critical issues\n- Documentation for guides and examples\n- Regular updates and maintenance\n\n## License\n\nThis library is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client for the Shoutbox Email API",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/shoutboxnet/python/issues",
"Documentation": "https://shoutbox.net/docs",
"Homepage": "https://shoutbox.net",
"Repository": "https://github.com/shoutboxnet/python.git"
},
"split_keywords": [
"email",
" api",
" client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dfe3916ec1ebf24960c669c65176699acbf1dfb1ef25f89bd138280988b50fc8",
"md5": "6a2fcc932f093e5f78884387b0406299",
"sha256": "64747ef2332afcd963da488e4fc02a30525a0594722644e525f85010e6619be4"
},
"downloads": -1,
"filename": "shoutbox_tluyben-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6a2fcc932f093e5f78884387b0406299",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9266,
"upload_time": "2024-12-09T08:17:04",
"upload_time_iso_8601": "2024-12-09T08:17:04.813861Z",
"url": "https://files.pythonhosted.org/packages/df/e3/916ec1ebf24960c669c65176699acbf1dfb1ef25f89bd138280988b50fc8/shoutbox_tluyben-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1fb9d0ebf61b70896d9134ef8511cd229fafd840f930b74edc567733fde37449",
"md5": "631c0f79f5f96caa1f832293d8d31c12",
"sha256": "d62840639f96ae4e1ea7da275b5c5f5f0936931ec7a34a291c77db70bc8a5509"
},
"downloads": -1,
"filename": "shoutbox_tluyben-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "631c0f79f5f96caa1f832293d8d31c12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 346521,
"upload_time": "2024-12-09T08:17:06",
"upload_time_iso_8601": "2024-12-09T08:17:06.861015Z",
"url": "https://files.pythonhosted.org/packages/1f/b9/d0ebf61b70896d9134ef8511cd229fafd840f930b74edc567733fde37449/shoutbox_tluyben-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-09 08:17:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shoutboxnet",
"github_project": "python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "shoutbox-tluyben"
}
JSON
