# AEmail - Simple Email Receive Server
[](https://www.python.org/downloads/)
[](https://python-poetry.org/)
[](LICENSE)
A simple SMTP server for receiving emails with REST API access. Perfect for testing, development, and automation scenarios where you need to receive emails programmatically.
## Features
- 🚀 **Simple SMTP Server**: Receives emails on any address with your domain
- 🌐 **REST API**: Easy access to received emails via HTTP endpoints
- 💾 **Flexible Storage**: In-memory or SQLite database storage
- 🔧 **Easy Configuration**: Environment variables and config file support
- 📦 **Poetry Package**: Professional Python packaging with wheel support
- 🖥️ **Command Line Tool**: Simple CLI for starting the server
- 🎨 **Web Interface**: Modern web UI for browsing emails
- 🔍 **Search Functionality**: Find emails by sender or recipient
## Use Cases
- **Batch Registration**: Register multiple accounts and receive verification emails
- **Email Testing**: Test email functionality in development environments
- **Automation**: Programmatically access received emails for processing
- **Development**: Mock email server for local development
## Quick Start
### Installation
```bash
# Install with pip
pip install aemail
# Or install with Poetry
poetry add aemail
```
### Basic Usage
```bash
# Start the server with default settings
aemail-server
# Start with custom ports
aemail-server --smtp-port 2525 --rest-port 8080
# Start with persistent database
aemail-server --db-file emails.db
# Start with custom config
aemail-server --config my-config.ini
```
## DNS Configuration
To receive emails for your domain, configure DNS records:
### A Record
Point your mail subdomain to your server IP:
```
A mx YOUR.SERVER.IP.ADDRESS
```
### MX Record
Configure MX record to route emails to your server:
```
MX * mx.yourdomain.com
```
> The `*` wildcard means ALL subdomains will be routed to your server.
> Examples: `test@yourdomain.com`, `anything@sub.yourdomain.com`
> This gives you unlimited email addresses!
## API Endpoints
The server provides a REST API for accessing received emails:
### GET /all
Get all stored messages (last 100)
```bash
curl http://localhost:14000/all
```
### GET /from/{email}
Get messages from a specific sender
```bash
curl http://localhost:14000/from/sender@example.com
```
### GET /to/{email}
Get messages to a specific recipient
```bash
curl http://localhost:14000/to/recipient@example.com
```
### GET /health
Health check endpoint
```bash
curl http://localhost:14000/health
```
### Response Format
```json
[
{
"from": "sender@example.com",
"to": ["recipient@example.com"],
"to0": "recipient@example.com",
"subject": "Test Email",
"content": "Email content here...",
"time": "2024-01-01T12:00:00"
}
]
```
## Configuration
### Config File (cfg.ini)
```ini
[smtpd]
host = :: # Listen on all interfaces (IPv4 and IPv6)
port = 25
[rest]
port = 14000
```
### Environment Variables
Override config file settings with environment variables:
- `SMTP_HOST` - SMTP server host (default: :: - all interfaces)
- `SMTP_PORT` - SMTP server port (default: 25)
- `REST_PORT` - REST API port (default: 14000)
### Command Line Options
```bash
aemail-server --help
Options:
--config, -c Path to configuration file
--smtp-host SMTP server host
--smtp-port SMTP server port
--rest-port REST API port
--db-file SQLite database file path
--verbose, -v Enable verbose logging
--version Show version
```
## Development
### From Source
```bash
# Clone the repository
git clone https://github.com/lycying/aemail.git
cd aemail
# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -
# Install dependencies
poetry install
# Run the server
poetry run aemail-server
# Run tests
poetry run pytest
# Build wheel package
poetry build
```
### Project Structure
```
aemail/
├── crazy_email_recv_srv/ # Main package
│ ├── __init__.py
│ ├── cli.py # Command line interface
│ ├── config.py # Configuration management
│ ├── data.py # Data access layer
│ ├── email_handler.py # SMTP email processing
│ ├── server.py # Main server
│ ├── utils.py # Utility functions
│ └── web_api.py # REST API
├── tests/ # Test suite
├── static/ # Web interface files
├── pyproject.toml # Poetry configuration
└── README.md
```
## Testing
Send a test email to any address at your domain:
```bash
# Example: Send email to test@yourdomain.com
# Then query the API:
curl http://localhost:14000/to/test@yourdomain.com
```
Or use the web interface at: http://localhost:14000
## License
MIT License - see LICENSE file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## Support
- 🐛 **Issues**: [GitHub Issues](https://github.com/lycying/crazy-email-recv-srv/issues)
- 📖 **Documentation**: [GitHub Wiki](https://github.com/lycying/crazy-email-recv-srv/wiki)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/lycying/crazy-email-recv-srv/discussions)
---
**Note**: This tool is for testing and development purposes. Use responsibly and in compliance with applicable laws and regulations.
Raw data
{
"_id": null,
"home_page": "https://github.com/lycying/aemail",
"name": "aemail",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8.1",
"maintainer_email": null,
"keywords": "smtp, email, server, api, testing",
"author": "lycying",
"author_email": "lycying@example.com",
"download_url": "https://files.pythonhosted.org/packages/56/46/46bf124972c36dfdf4c37175a2418ed943c329063a7f50059aecb309a870/aemail-0.2.0.tar.gz",
"platform": null,
"description": "# AEmail - Simple Email Receive Server\n\n[](https://www.python.org/downloads/)\n[](https://python-poetry.org/)\n[](LICENSE)\n\nA simple SMTP server for receiving emails with REST API access. Perfect for testing, development, and automation scenarios where you need to receive emails programmatically.\n\n## Features\n\n- \ud83d\ude80 **Simple SMTP Server**: Receives emails on any address with your domain\n- \ud83c\udf10 **REST API**: Easy access to received emails via HTTP endpoints\n- \ud83d\udcbe **Flexible Storage**: In-memory or SQLite database storage\n- \ud83d\udd27 **Easy Configuration**: Environment variables and config file support\n- \ud83d\udce6 **Poetry Package**: Professional Python packaging with wheel support\n- \ud83d\udda5\ufe0f **Command Line Tool**: Simple CLI for starting the server\n- \ud83c\udfa8 **Web Interface**: Modern web UI for browsing emails\n- \ud83d\udd0d **Search Functionality**: Find emails by sender or recipient\n\n## Use Cases\n\n- **Batch Registration**: Register multiple accounts and receive verification emails\n- **Email Testing**: Test email functionality in development environments\n- **Automation**: Programmatically access received emails for processing\n- **Development**: Mock email server for local development\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install with pip\npip install aemail\n\n# Or install with Poetry\npoetry add aemail\n```\n\n### Basic Usage\n\n```bash\n# Start the server with default settings\naemail-server\n\n# Start with custom ports\naemail-server --smtp-port 2525 --rest-port 8080\n\n# Start with persistent database\naemail-server --db-file emails.db\n\n# Start with custom config\naemail-server --config my-config.ini\n```\n\n## DNS Configuration\n\nTo receive emails for your domain, configure DNS records:\n\n### A Record\nPoint your mail subdomain to your server IP:\n```\nA mx YOUR.SERVER.IP.ADDRESS\n```\n\n### MX Record\nConfigure MX record to route emails to your server:\n```\nMX * mx.yourdomain.com\n```\n\n> The `*` wildcard means ALL subdomains will be routed to your server.\n> Examples: `test@yourdomain.com`, `anything@sub.yourdomain.com`\n> This gives you unlimited email addresses!\n\n## API Endpoints\n\nThe server provides a REST API for accessing received emails:\n\n### GET /all\nGet all stored messages (last 100)\n```bash\ncurl http://localhost:14000/all\n```\n\n### GET /from/{email}\nGet messages from a specific sender\n```bash\ncurl http://localhost:14000/from/sender@example.com\n```\n\n### GET /to/{email}\nGet messages to a specific recipient\n```bash\ncurl http://localhost:14000/to/recipient@example.com\n```\n\n### GET /health\nHealth check endpoint\n```bash\ncurl http://localhost:14000/health\n```\n\n### Response Format\n```json\n[\n {\n \"from\": \"sender@example.com\",\n \"to\": [\"recipient@example.com\"],\n \"to0\": \"recipient@example.com\",\n \"subject\": \"Test Email\",\n \"content\": \"Email content here...\",\n \"time\": \"2024-01-01T12:00:00\"\n }\n]\n```\n\n## Configuration\n\n### Config File (cfg.ini)\n```ini\n[smtpd]\nhost = :: # Listen on all interfaces (IPv4 and IPv6)\nport = 25\n\n[rest]\nport = 14000\n```\n\n### Environment Variables\nOverride config file settings with environment variables:\n- `SMTP_HOST` - SMTP server host (default: :: - all interfaces)\n- `SMTP_PORT` - SMTP server port (default: 25)\n- `REST_PORT` - REST API port (default: 14000)\n\n### Command Line Options\n```bash\naemail-server --help\n\nOptions:\n --config, -c Path to configuration file\n --smtp-host SMTP server host\n --smtp-port SMTP server port\n --rest-port REST API port\n --db-file SQLite database file path\n --verbose, -v Enable verbose logging\n --version Show version\n```\n\n## Development\n\n### From Source\n```bash\n# Clone the repository\ngit clone https://github.com/lycying/aemail.git\ncd aemail\n\n# Install Poetry (if not already installed)\ncurl -sSL https://install.python-poetry.org | python3 -\n\n# Install dependencies\npoetry install\n\n# Run the server\npoetry run aemail-server\n\n# Run tests\npoetry run pytest\n\n# Build wheel package\npoetry build\n```\n\n### Project Structure\n```\naemail/\n\u251c\u2500\u2500 crazy_email_recv_srv/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli.py # Command line interface\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u251c\u2500\u2500 data.py # Data access layer\n\u2502 \u251c\u2500\u2500 email_handler.py # SMTP email processing\n\u2502 \u251c\u2500\u2500 server.py # Main server\n\u2502 \u251c\u2500\u2500 utils.py # Utility functions\n\u2502 \u2514\u2500\u2500 web_api.py # REST API\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 static/ # Web interface files\n\u251c\u2500\u2500 pyproject.toml # Poetry configuration\n\u2514\u2500\u2500 README.md\n```\n\n## Testing\n\nSend a test email to any address at your domain:\n```bash\n# Example: Send email to test@yourdomain.com\n# Then query the API:\ncurl http://localhost:14000/to/test@yourdomain.com\n```\n\nOr use the web interface at: http://localhost:14000\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## Support\n\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/lycying/crazy-email-recv-srv/issues)\n- \ud83d\udcd6 **Documentation**: [GitHub Wiki](https://github.com/lycying/crazy-email-recv-srv/wiki)\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/lycying/crazy-email-recv-srv/discussions)\n\n---\n\n**Note**: This tool is for testing and development purposes. Use responsibly and in compliance with applicable laws and regulations.\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple SMTP server for receiving emails with REST API access",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/lycying/aemail",
"Homepage": "https://github.com/lycying/aemail",
"Repository": "https://github.com/lycying/aemail"
},
"split_keywords": [
"smtp",
" email",
" server",
" api",
" testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "10b47e9b55124cbb9237e3628abc1769a1f2fd523735bf5e61ddc553164fbada",
"md5": "b1a0098c5e7a2bf6790f8ad672ecc21d",
"sha256": "6a2e5f46bc9d6f70d24ba6b2fb706c57f4667488cbc20b90e1308dd63dd5ea8c"
},
"downloads": -1,
"filename": "aemail-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b1a0098c5e7a2bf6790f8ad672ecc21d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8.1",
"size": 17669,
"upload_time": "2025-07-13T10:24:46",
"upload_time_iso_8601": "2025-07-13T10:24:46.738336Z",
"url": "https://files.pythonhosted.org/packages/10/b4/7e9b55124cbb9237e3628abc1769a1f2fd523735bf5e61ddc553164fbada/aemail-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "564646bf124972c36dfdf4c37175a2418ed943c329063a7f50059aecb309a870",
"md5": "31c53355b8412c9f5256545c6b24c1e3",
"sha256": "c9977ae2bca1b565456dee82db76dd38d229e6075120b13a115e46819642b564"
},
"downloads": -1,
"filename": "aemail-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "31c53355b8412c9f5256545c6b24c1e3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8.1",
"size": 14840,
"upload_time": "2025-07-13T10:24:48",
"upload_time_iso_8601": "2025-07-13T10:24:48.317963Z",
"url": "https://files.pythonhosted.org/packages/56/46/46bf124972c36dfdf4c37175a2418ed943c329063a7f50059aecb309a870/aemail-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 10:24:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lycying",
"github_project": "aemail",
"github_not_found": true,
"lcname": "aemail"
}
JSON
