# DripEmails SMTP Server
A modern, async SMTP server built with `aiosmtpd` for Python 3.11+. Perfect for development, testing, and production email handling.
## 🚀 Features
- **Modern Async Architecture**: Built with `aiosmtpd` for high-performance async email handling
- **Python 3.11+ Compatible**: Optimized for modern Python versions
- **Django Integration**: Seamless integration with Django applications
- **Webhook Support**: Forward email metadata to external services
- **Database Logging**: Store email metadata in your database
- **Rate Limiting**: Built-in protection against spam and abuse
- **Authentication**: Support for PLAIN and LOGIN authentication
- **Debug Mode**: Comprehensive logging and debugging capabilities
- **Production Ready**: Designed for both development and production use
## 📋 Requirements
- Python 3.11 or higher
- `aiosmtpd>=1.4.4`
- Optional: Django 4.0+ for database integration
- Optional: `aiohttp>=3.8.0` for webhook support
## 🛠️ Installation
### From PyPI (Coming Soon)
```bash
pip install dripemails-smtp-server
```
### From Source
```bash
git clone https://github.com/dripemails/smtp_server.git
cd smtp_server
pip install -e .
```
## 🚀 Quick Start
### Basic Usage
```python
from core.smtp_server import create_smtp_server
# Create server with default configuration
server = create_smtp_server()
# Start server on localhost:1025
server.start('localhost', 1025)
# Keep server running
import time
try:
while True:
time.sleep(1)
except KeyboardInterrupt:
server.stop()
```
### Django Integration
```python
# In your Django management command
from django.core.management.base import BaseCommand
from core.smtp_server import run_smtp_server
class Command(BaseCommand):
help = 'Run SMTP server'
def handle(self, *args, **options):
config = {
'debug': True,
'save_to_database': True,
'allowed_domains': ['yourdomain.com'],
}
run_smtp_server('localhost', 1025, config)
```
### Command Line Usage
```bash
# Run with debug mode
python -m core.smtp_server --debug --port 1025
# Run with custom configuration
python -m core.smtp_server --config smtp_config.json --port 1025
```
## ⚙️ Configuration
### Basic Configuration
```python
config = {
'debug': False, # Enable debug output
'save_to_database': True, # Save emails to database
'log_to_file': True, # Log to file
'log_file': 'email_log.jsonl', # Log file path
'allowed_domains': [ # Allowed recipient domains
'yourdomain.com',
'localhost',
'127.0.0.1'
],
'webhook_url': None, # Webhook URL for notifications
'forward_to_webhook': False, # Enable webhook forwarding
'auth_enabled': True, # Enable authentication
'allowed_users': ['founders'], # Allowed users for auth
}
```
### Configuration File (JSON)
```json
{
"debug": true,
"save_to_database": true,
"log_to_file": true,
"log_file": "email_log.jsonl",
"allowed_domains": ["yourdomain.com", "localhost"],
"webhook_url": "https://api.yourdomain.com/webhook",
"forward_to_webhook": true,
"auth_enabled": true,
"allowed_users": ["founders", "admin"],
"max_message_size": 10485760,
"timeout": 30
}
```
## 🔧 Django Integration
### 1. Add to INSTALLED_APPS
```python
INSTALLED_APPS = [
# ... other apps
'core',
]
```
### 2. Run Migrations
```bash
python manage.py makemigrations core
python manage.py migrate
```
### 3. Create Management Command
```python
# core/management/commands/run_smtp_server.py
from django.core.management.base import BaseCommand
from core.smtp_server import run_smtp_server
class Command(BaseCommand):
help = 'Run SMTP server'
def add_arguments(self, parser):
parser.add_argument('--port', type=int, default=1025)
parser.add_argument('--debug', action='store_true')
parser.add_argument('--config', type=str)
def handle(self, *args, **options):
config = {
'debug': options['debug'],
'save_to_database': True,
}
run_smtp_server('localhost', options['port'], config)
```
### 4. Run Server
```bash
python manage.py run_smtp_server --debug --port 1025
```
## 📧 Email Processing
### Email Metadata Structure
```python
{
'from': 'sender@example.com',
'to': 'recipient@yourdomain.com',
'subject': 'Test Email',
'date': '2024-01-01T12:00:00',
'message_id': '<unique-message-id>',
'received_at': '2024-01-01T12:00:00.123456',
'size': 1024,
'body': 'Email content...'
}
```
### Database Model (Django)
```python
from django.db import models
class EmailLog(models.Model):
sender = models.EmailField(max_length=254)
recipient = models.EmailField(max_length=254)
subject = models.CharField(max_length=255)
body = models.TextField()
message_id = models.CharField(max_length=255, blank=True)
received_at = models.DateTimeField(auto_now_add=True)
size = models.IntegerField(default=0)
processed = models.BooleanField(default=False)
error_message = models.TextField(blank=True)
class Meta:
ordering = ['-received_at']
indexes = [
models.Index(fields=['sender']),
models.Index(fields=['recipient']),
models.Index(fields=['received_at']),
]
```
## 🔐 Authentication
### Supported Methods
- **PLAIN**: Simple username/password authentication
- **LOGIN**: Base64 encoded credentials
### Django User Authentication
The server integrates with Django's authentication system:
```python
# Users must exist in Django and be active
# Authentication checks against Django's User model
# Supports user groups and permissions
```
## 🌐 Webhook Support
### Webhook Payload
```json
{
"from": "sender@example.com",
"to": "recipient@yourdomain.com",
"subject": "Test Email",
"date": "2024-01-01T12:00:00",
"message_id": "<unique-message-id>",
"received_at": "2024-01-01T12:00:00.123456",
"size": 1024,
"body": "Email content..."
}
```
### Configuration
```python
config = {
'webhook_url': 'https://api.yourdomain.com/webhook',
'forward_to_webhook': True,
}
```
## 🧪 Testing
### Test Script
```python
import smtplib
from email.mime.text import MIMEText
def test_smtp_server(host='localhost', port=1025):
# Create message
msg = MIMEText('Test email content')
msg['From'] = 'test@example.com'
msg['To'] = 'test@yourdomain.com'
msg['Subject'] = 'Test Email'
# Send email
server = smtplib.SMTP(host, port)
server.send_message(msg)
server.quit()
print("Test email sent successfully!")
# Run test
test_smtp_server()
```
### Automated Tests
```bash
# Run tests
pytest tests/
# Run with coverage
pytest --cov=core tests/
```
## 📊 Monitoring
### Server Statistics
```python
server = create_smtp_server()
stats = server.get_stats()
print(f"Emails received: {stats['emails_received']}")
print(f"Emails processed: {stats['emails_processed']}")
print(f"Emails failed: {stats['emails_failed']}")
print(f"Uptime: {stats['uptime']} seconds")
```
### Logging
```python
import logging
# Configure logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```
## 🚀 Production Deployment
### Using Supervisord
```ini
[program:dripemails-smtp]
command=python manage.py run_smtp_server --port 25
directory=/path/to/your/project
user=www-data
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/dripemails-smtp.log
```
### Using Docker
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 25
CMD ["python", "manage.py", "run_smtp_server", "--port", "25"]
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone repository
git clone https://github.com/dripemails/smtp_server.git
cd smtp_server
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black core/ tests/
# Lint code
flake8 core/ tests/
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Documentation**: [GitHub Wiki](https://github.com/dripemails/dripemails-smtp/wiki)
- **Issues**: [GitHub Issues](https://github.com/dripemails/dripemails-smtp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/dripemails/dripemails-smtp/discussions)
- **Email**: founders@dripemails.org
## 🙏 Acknowledgments
- Built with [aiosmtpd](https://aiosmtpd.readthedocs.io/)
- Inspired by modern async Python patterns
- Community feedback and contributions
---
**Made with ❤️ by the DripEmails Team**
Raw data
{
"_id": null,
"home_page": "https://github.com/dripemails/dripemails-smtp",
"name": "dripemails-smtp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "DripEmails Team <founders@dripemails.org>",
"keywords": "smtp, email, server, aiosmtpd, async, python",
"author": "DripEmails Team",
"author_email": "DripEmails Team <founders@dripemails.org>",
"download_url": "https://files.pythonhosted.org/packages/5f/bc/45b628dffa915cbe0132c4e1b0c57ab6a2538cb6b41c57f0072bf245b529/dripemails_smtp_server-1.0.0.tar.gz",
"platform": "any",
"description": "# DripEmails SMTP Server\r\n\r\nA modern, async SMTP server built with `aiosmtpd` for Python 3.11+. Perfect for development, testing, and production email handling.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **Modern Async Architecture**: Built with `aiosmtpd` for high-performance async email handling\r\n- **Python 3.11+ Compatible**: Optimized for modern Python versions\r\n- **Django Integration**: Seamless integration with Django applications\r\n- **Webhook Support**: Forward email metadata to external services\r\n- **Database Logging**: Store email metadata in your database\r\n- **Rate Limiting**: Built-in protection against spam and abuse\r\n- **Authentication**: Support for PLAIN and LOGIN authentication\r\n- **Debug Mode**: Comprehensive logging and debugging capabilities\r\n- **Production Ready**: Designed for both development and production use\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n- Python 3.11 or higher\r\n- `aiosmtpd>=1.4.4`\r\n- Optional: Django 4.0+ for database integration\r\n- Optional: `aiohttp>=3.8.0` for webhook support\r\n\r\n## \ud83d\udee0\ufe0f Installation\r\n\r\n### From PyPI (Coming Soon)\r\n\r\n```bash\r\npip install dripemails-smtp-server\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/dripemails/smtp_server.git\r\ncd smtp_server\r\npip install -e .\r\n```\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom core.smtp_server import create_smtp_server\r\n\r\n# Create server with default configuration\r\nserver = create_smtp_server()\r\n\r\n# Start server on localhost:1025\r\nserver.start('localhost', 1025)\r\n\r\n# Keep server running\r\nimport time\r\ntry:\r\n while True:\r\n time.sleep(1)\r\nexcept KeyboardInterrupt:\r\n server.stop()\r\n```\r\n\r\n### Django Integration\r\n\r\n```python\r\n# In your Django management command\r\nfrom django.core.management.base import BaseCommand\r\nfrom core.smtp_server import run_smtp_server\r\n\r\nclass Command(BaseCommand):\r\n help = 'Run SMTP server'\r\n \r\n def handle(self, *args, **options):\r\n config = {\r\n 'debug': True,\r\n 'save_to_database': True,\r\n 'allowed_domains': ['yourdomain.com'],\r\n }\r\n run_smtp_server('localhost', 1025, config)\r\n```\r\n\r\n### Command Line Usage\r\n\r\n```bash\r\n# Run with debug mode\r\npython -m core.smtp_server --debug --port 1025\r\n\r\n# Run with custom configuration\r\npython -m core.smtp_server --config smtp_config.json --port 1025\r\n```\r\n\r\n## \u2699\ufe0f Configuration\r\n\r\n### Basic Configuration\r\n\r\n```python\r\nconfig = {\r\n 'debug': False, # Enable debug output\r\n 'save_to_database': True, # Save emails to database\r\n 'log_to_file': True, # Log to file\r\n 'log_file': 'email_log.jsonl', # Log file path\r\n 'allowed_domains': [ # Allowed recipient domains\r\n 'yourdomain.com',\r\n 'localhost',\r\n '127.0.0.1'\r\n ],\r\n 'webhook_url': None, # Webhook URL for notifications\r\n 'forward_to_webhook': False, # Enable webhook forwarding\r\n 'auth_enabled': True, # Enable authentication\r\n 'allowed_users': ['founders'], # Allowed users for auth\r\n}\r\n```\r\n\r\n### Configuration File (JSON)\r\n\r\n```json\r\n{\r\n \"debug\": true,\r\n \"save_to_database\": true,\r\n \"log_to_file\": true,\r\n \"log_file\": \"email_log.jsonl\",\r\n \"allowed_domains\": [\"yourdomain.com\", \"localhost\"],\r\n \"webhook_url\": \"https://api.yourdomain.com/webhook\",\r\n \"forward_to_webhook\": true,\r\n \"auth_enabled\": true,\r\n \"allowed_users\": [\"founders\", \"admin\"],\r\n \"max_message_size\": 10485760,\r\n \"timeout\": 30\r\n}\r\n```\r\n\r\n## \ud83d\udd27 Django Integration\r\n\r\n### 1. Add to INSTALLED_APPS\r\n\r\n```python\r\nINSTALLED_APPS = [\r\n # ... other apps\r\n 'core',\r\n]\r\n```\r\n\r\n### 2. Run Migrations\r\n\r\n```bash\r\npython manage.py makemigrations core\r\npython manage.py migrate\r\n```\r\n\r\n### 3. Create Management Command\r\n\r\n```python\r\n# core/management/commands/run_smtp_server.py\r\nfrom django.core.management.base import BaseCommand\r\nfrom core.smtp_server import run_smtp_server\r\n\r\nclass Command(BaseCommand):\r\n help = 'Run SMTP server'\r\n \r\n def add_arguments(self, parser):\r\n parser.add_argument('--port', type=int, default=1025)\r\n parser.add_argument('--debug', action='store_true')\r\n parser.add_argument('--config', type=str)\r\n \r\n def handle(self, *args, **options):\r\n config = {\r\n 'debug': options['debug'],\r\n 'save_to_database': True,\r\n }\r\n run_smtp_server('localhost', options['port'], config)\r\n```\r\n\r\n### 4. Run Server\r\n\r\n```bash\r\npython manage.py run_smtp_server --debug --port 1025\r\n```\r\n\r\n## \ud83d\udce7 Email Processing\r\n\r\n### Email Metadata Structure\r\n\r\n```python\r\n{\r\n 'from': 'sender@example.com',\r\n 'to': 'recipient@yourdomain.com',\r\n 'subject': 'Test Email',\r\n 'date': '2024-01-01T12:00:00',\r\n 'message_id': '<unique-message-id>',\r\n 'received_at': '2024-01-01T12:00:00.123456',\r\n 'size': 1024,\r\n 'body': 'Email content...'\r\n}\r\n```\r\n\r\n### Database Model (Django)\r\n\r\n```python\r\nfrom django.db import models\r\n\r\nclass EmailLog(models.Model):\r\n sender = models.EmailField(max_length=254)\r\n recipient = models.EmailField(max_length=254)\r\n subject = models.CharField(max_length=255)\r\n body = models.TextField()\r\n message_id = models.CharField(max_length=255, blank=True)\r\n received_at = models.DateTimeField(auto_now_add=True)\r\n size = models.IntegerField(default=0)\r\n processed = models.BooleanField(default=False)\r\n error_message = models.TextField(blank=True)\r\n \r\n class Meta:\r\n ordering = ['-received_at']\r\n indexes = [\r\n models.Index(fields=['sender']),\r\n models.Index(fields=['recipient']),\r\n models.Index(fields=['received_at']),\r\n ]\r\n```\r\n\r\n## \ud83d\udd10 Authentication\r\n\r\n### Supported Methods\r\n\r\n- **PLAIN**: Simple username/password authentication\r\n- **LOGIN**: Base64 encoded credentials\r\n\r\n### Django User Authentication\r\n\r\nThe server integrates with Django's authentication system:\r\n\r\n```python\r\n# Users must exist in Django and be active\r\n# Authentication checks against Django's User model\r\n# Supports user groups and permissions\r\n```\r\n\r\n## \ud83c\udf10 Webhook Support\r\n\r\n### Webhook Payload\r\n\r\n```json\r\n{\r\n \"from\": \"sender@example.com\",\r\n \"to\": \"recipient@yourdomain.com\",\r\n \"subject\": \"Test Email\",\r\n \"date\": \"2024-01-01T12:00:00\",\r\n \"message_id\": \"<unique-message-id>\",\r\n \"received_at\": \"2024-01-01T12:00:00.123456\",\r\n \"size\": 1024,\r\n \"body\": \"Email content...\"\r\n}\r\n```\r\n\r\n### Configuration\r\n\r\n```python\r\nconfig = {\r\n 'webhook_url': 'https://api.yourdomain.com/webhook',\r\n 'forward_to_webhook': True,\r\n}\r\n```\r\n\r\n## \ud83e\uddea Testing\r\n\r\n### Test Script\r\n\r\n```python\r\nimport smtplib\r\nfrom email.mime.text import MIMEText\r\n\r\ndef test_smtp_server(host='localhost', port=1025):\r\n # Create message\r\n msg = MIMEText('Test email content')\r\n msg['From'] = 'test@example.com'\r\n msg['To'] = 'test@yourdomain.com'\r\n msg['Subject'] = 'Test Email'\r\n \r\n # Send email\r\n server = smtplib.SMTP(host, port)\r\n server.send_message(msg)\r\n server.quit()\r\n \r\n print(\"Test email sent successfully!\")\r\n\r\n# Run test\r\ntest_smtp_server()\r\n```\r\n\r\n### Automated Tests\r\n\r\n```bash\r\n# Run tests\r\npytest tests/\r\n\r\n# Run with coverage\r\npytest --cov=core tests/\r\n```\r\n\r\n## \ud83d\udcca Monitoring\r\n\r\n### Server Statistics\r\n\r\n```python\r\nserver = create_smtp_server()\r\nstats = server.get_stats()\r\n\r\nprint(f\"Emails received: {stats['emails_received']}\")\r\nprint(f\"Emails processed: {stats['emails_processed']}\")\r\nprint(f\"Emails failed: {stats['emails_failed']}\")\r\nprint(f\"Uptime: {stats['uptime']} seconds\")\r\n```\r\n\r\n### Logging\r\n\r\n```python\r\nimport logging\r\n\r\n# Configure logging\r\nlogging.basicConfig(\r\n level=logging.INFO,\r\n format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'\r\n)\r\n```\r\n\r\n## \ud83d\ude80 Production Deployment\r\n\r\n### Using Supervisord\r\n\r\n```ini\r\n[program:dripemails-smtp]\r\ncommand=python manage.py run_smtp_server --port 25\r\ndirectory=/path/to/your/project\r\nuser=www-data\r\nautostart=true\r\nautorestart=true\r\nredirect_stderr=true\r\nstdout_logfile=/var/log/dripemails-smtp.log\r\n```\r\n\r\n### Using Docker\r\n\r\n```dockerfile\r\nFROM python:3.11-slim\r\n\r\nWORKDIR /app\r\nCOPY requirements.txt .\r\nRUN pip install -r requirements.txt\r\n\r\nCOPY . .\r\nEXPOSE 25\r\n\r\nCMD [\"python\", \"manage.py\", \"run_smtp_server\", \"--port\", \"25\"]\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone repository\r\ngit clone https://github.com/dripemails/smtp_server.git\r\ncd smtp_server\r\n\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npytest\r\n\r\n# Format code\r\nblack core/ tests/\r\n\r\n# Lint code\r\nflake8 core/ tests/\r\n```\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83c\udd98 Support\r\n\r\n- **Documentation**: [GitHub Wiki](https://github.com/dripemails/dripemails-smtp/wiki)\r\n- **Issues**: [GitHub Issues](https://github.com/dripemails/dripemails-smtp/issues)\r\n- **Discussions**: [GitHub Discussions](https://github.com/dripemails/dripemails-smtp/discussions)\r\n- **Email**: founders@dripemails.org\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Built with [aiosmtpd](https://aiosmtpd.readthedocs.io/)\r\n- Inspired by modern async Python patterns\r\n- Community feedback and contributions\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f by the DripEmails Team**\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern, async SMTP server built with aiosmtpd for Python 3.11+",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/dripemails/dripemails-smtp/issues",
"Discussions": "https://github.com/dripemails/dripemails-smtp/discussions",
"Documentation": "https://github.com/dripemails/dripemails-smtp/blob/main/README.md",
"Homepage": "https://github.com/dripemails/dripemails-smtp",
"Repository": "https://github.com/dripemails/dripemails-smtp"
},
"split_keywords": [
"smtp",
" email",
" server",
" aiosmtpd",
" async",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "094acd87a12abad688c692da544a58783e0e63169dd3bfe1ffdcd5ca9493c29f",
"md5": "acab7833d0f1bcfba7de1cdfa64a44cf",
"sha256": "bf7f96138ee2c196a6afa6cfb05fc367964245c40d7a4bd852cb320deadcea59"
},
"downloads": -1,
"filename": "dripemails_smtp_server-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "acab7833d0f1bcfba7de1cdfa64a44cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 6185,
"upload_time": "2025-07-28T00:48:48",
"upload_time_iso_8601": "2025-07-28T00:48:48.039270Z",
"url": "https://files.pythonhosted.org/packages/09/4a/cd87a12abad688c692da544a58783e0e63169dd3bfe1ffdcd5ca9493c29f/dripemails_smtp_server-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5fbc45b628dffa915cbe0132c4e1b0c57ab6a2538cb6b41c57f0072bf245b529",
"md5": "8e83fc9c2c75b8c37769a418b0a69d40",
"sha256": "92154733e772fb8c0602239099f923f627002c01e84fcb42baa42722bddd3a75"
},
"downloads": -1,
"filename": "dripemails_smtp_server-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8e83fc9c2c75b8c37769a418b0a69d40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 34382,
"upload_time": "2025-07-28T00:48:49",
"upload_time_iso_8601": "2025-07-28T00:48:49.265073Z",
"url": "https://files.pythonhosted.org/packages/5f/bc/45b628dffa915cbe0132c4e1b0c57ab6a2538cb6b41c57f0072bf245b529/dripemails_smtp_server-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 00:48:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dripemails",
"github_project": "dripemails-smtp",
"github_not_found": true,
"lcname": "dripemails-smtp-server"
}
JSON
