Email API Python Client
Simple, powerful email sending API with support for attachments and custom headers.
Quick Start
import requests
response = requests.post(
'https://api.shoutbox.net/send',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'from': '[email protected]',
'to': '[email protected]',
'subject': 'Hello World',
'html': '<h1>Welcome!</h1>'
}
)
Authentication
All API requests require an API key passed in the headers dictionary:
headers = {
'Authorization': 'Bearer key_XXXXXXXXX'
}
Basic Request Structure
| Field | Type | Required | Description |
|---|
from | str | Yes | Sender email address |
to | str | Yes | Recipient email address(es) |
subject | str | Yes | Email subject line |
html | str | Yes | HTML content of the email |
name | str | No | Sender name |
reply_to | str | No | Reply-to email address |
Recipients
Multiple Recipients
You can send to multiple recipients by separating email addresses with commas:
response = requests.post(
'https://api.shoutbox.net/send',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'from': '[email protected]',
'to': '[email protected],[email protected]',
'subject': 'Team Update',
'html': '<h1>Important Announcement</h1>'
}
)
Named Recipients
You can include recipient names using the format Name <[email protected]>:
response = requests.post(
'https://api.shoutbox.net/send',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'from': '[email protected]',
'to': 'John Doe <[email protected]>,Jane Smith <[email protected]>',
'subject': 'Team Meeting',
'html': '<h1>Meeting Invitation</h1>'
}
)
Reply-To Address
Set a different reply-to address using the reply_to field:
response = requests.post(
'https://api.shoutbox.net/send',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'from': '[email protected]',
'reply_to': '[email protected]',
'to': '[email protected]',
'subject': 'Support Ticket Update',
'html': '<h1>Your ticket has been updated</h1>'
}
)
You can also include a name in the reply-to address:
response = requests.post(
'https://api.shoutbox.net/send',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'from': '[email protected]',
'reply_to': 'Support Team <[email protected]>',
'to': '[email protected]',
'subject': 'Support Ticket Update',
'html': '<h1>Your ticket has been updated</h1>'
}
)
Attachments
Complete Example with Attachment
import base64
response = requests.post(
'https://api.shoutbox.net/send',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'from': '[email protected]',
'name': 'Reports Team',
'to': 'John Smith <[email protected]>',
'subject': 'Monthly Report - January 2024',
'html': '<h1>Monthly Report</h1><p>Please find your report attached.</p>',
'attachments': [
{
'content': base64.b64encode(open('january_report.pdf', 'rb').read()).decode(),
'filename': 'january_report.pdf'
},
{
'content': base64.b64encode(open('data.xlsx', 'rb').read()).decode(),
'filename': 'data.xlsx'
}
]
}
)
response = requests.post(
'https://api.shoutbox.net/send',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'from': '[email protected]',
'name': 'Document System',
'to': 'Jane Doe <[email protected]>,[email protected]',
'reply_to': 'Support <[email protected]>',
'subject': 'Your Requested Documents',
'html': '<h1>Documents Ready</h1><p>Please find your requested documents attached.</p>',
'attachments': [
{
'content': base64.b64encode(open('document1.pdf', 'rb').read()).decode(),
'filename': 'document1.pdf'
},
{
'content': base64.b64encode(open('document2.pdf', 'rb').read()).decode(),
'filename': 'document2.pdf'
}
],
'headers': {
'X-Priority': '1',
'X-Document-Type': 'confidential',
'List-Unsubscribe': '<https://yourdomain.com/unsubscribe>',
'X-Tracking-ID': 'doc-123456'
}
}
)
response = requests.post(
'https://api.shoutbox.net/send',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'from': '[email protected]',
'name': 'Newsletter Team',
'to': 'Subscriber <[email protected]>',
'reply_to': 'Newsletter Support <[email protected]>',
'subject': 'Your Weekly Newsletter',
'html': "<h1>This Week's Updates</h1><p>Latest news and updates...</p>",
'headers': {
'List-Unsubscribe': '<https://yourdomain.com/unsubscribe>',
'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
'X-Campaign-ID': 'newsletter_2024_01',
'X-Mailer': 'ShoutboxAPI/1.0',
'Precedence': 'bulk',
'X-Auto-Response-Suppress': 'OOF, AutoReply'
}
}
)
Security Best Practices
API Key Management
Use environment variables to store your API key:
import os
api_key = os.getenv('SHOUTBOX_API_KEY')
Error Handling
Implement proper error handling:
try:
response = requests.post(...)
response.raise_for_status()
except requests.exceptions.RequestException as e:
print(f"Error sending email: {e}")
File Operations
Use context managers for file operations:
with open('file.pdf', 'rb') as f:
content = base64.b64encode(f.read()).decode()
Additional Security Measures
- Never share your API key publicly
- Validate email addresses before sending
- Use HTTPS for all API calls
- Base64 encode attachments properly
- Keep attachment sizes reasonable
Rate Limits
Please contact support for information about rate limits for your API key.
Support
For additional support or questions, please contact our support team.