gitea-admin/gh-christianlouis-inboxconverge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add QUICKSTART guide, LICENSE, and CONTRIBUTING documentation

Browse Source 
Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-02-01 12:17:59 +00:00
parent 810ebed3e2
commit a7b0466d98
3 changed files with 403 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+176
View File
@@ -0,0 +1,176 @@
# Contributing to POP3 to Gmail Forwarder
Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
## Code of Conduct
Be respectful and inclusive. We welcome contributions from everyone.
## How to Contribute
### Reporting Bugs
1. Check if the bug has already been reported in [Issues](https://github.com/christianlouis/pop_puller_to_gmail/issues)
2. If not, create a new issue with:
- Clear title and description
- Steps to reproduce
- Expected vs actual behavior
- Environment details (OS, Docker version, etc.)
- Relevant logs (remove sensitive info!)
### Suggesting Features
1. Check the [Roadmap](ROADMAP.md) to see if it's already planned
2. Open an issue with the "enhancement" label
3. Describe the feature and its use case
4. Explain why it would be useful
### Pull Requests
1. **Fork the repository**
2. **Create a feature branch**
```bash
git checkout -b feature/your-feature-name
```
3. **Make your changes**
- Follow existing code style
- Add comments for complex logic
- Update documentation if needed
4. **Test your changes**
```bash
# Test Python syntax
python3 -m py_compile pop3_forwarder.py
# Test Docker build
docker build -t pop3-test .
# Test with your configuration
docker-compose up
```
5. **Commit your changes**
```bash
git commit -m "Add feature: brief description"
```
Use clear, descriptive commit messages:
- `Add feature: ...`
- `Fix bug: ...`
- `Update docs: ...`
- `Improve performance: ...`
6. **Push to your fork**
```bash
git push origin feature/your-feature-name
```
7. **Open a Pull Request**
- Describe what changes you made
- Reference any related issues
- Include screenshots for UI changes
## Development Setup
### Local Development
```bash
# Clone your fork
git clone https://github.com/YOUR-USERNAME/pop_puller_to_gmail.git
cd pop_puller_to_gmail
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Copy example config
cp .env.example .env
# Edit .env with test credentials
# Run locally
python pop3_forwarder.py
```
### Docker Development
```bash
# Build image
docker build -t pop3-dev .
# Run with your config
docker run --env-file .env pop3-dev
```
## Code Style
- Follow PEP 8 for Python code
- Use meaningful variable and function names
- Add docstrings to functions and classes
- Keep functions focused and small
- Handle errors gracefully
## Testing
Before submitting a PR:
1. **Syntax check**
```bash
python3 -m py_compile pop3_forwarder.py
```
2. **Docker build**
```bash
docker build -t pop3-test .
```
3. **Manual testing**
- Test with real POP3 account (or mock)
- Verify emails are forwarded correctly
- Check error handling
- Review logs
## Documentation
Update documentation when:
- Adding new features
- Changing configuration options
- Modifying behavior
- Adding dependencies
Files to update:
- `README.md` - Main documentation
- `QUICKSTART.md` - If setup changes
- `MVP.md` - If MVP scope changes
- `ROADMAP.md` - If adding future plans
## Security
- **Never commit credentials** or sensitive data
- Use environment variables for secrets
- Report security issues privately (see below)
- Follow security best practices
### Reporting Security Issues
**Do NOT open public issues for security vulnerabilities.**
Email security concerns to the maintainers privately.
## Questions?
- Open a discussion in GitHub Discussions
- Comment on relevant issues
- Ask in pull requests
## Recognition
Contributors will be recognized in:
- GitHub contributors list
- Release notes for significant contributions
- README acknowledgments section
Thank you for contributing! 🎉
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 POP3 to Gmail Forwarder Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
QUICKSTART.md
+206
View File
@@ -0,0 +1,206 @@
# Quick Start Guide
Get your POP3 to Gmail forwarder running in under 10 minutes!
## Prerequisites
- Docker and Docker Compose installed
- Gmail account with 2FA enabled
- POP3 email account credentials
## Step-by-Step Setup
### 1. Clone the Repository
```bash
git clone https://github.com/christianlouis/pop_puller_to_gmail.git
cd pop_puller_to_gmail
```
### 2. Generate Gmail App Password
1. Visit: https://myaccount.google.com/apppasswords
2. Sign in to your Google Account
3. Select "App passwords" under Security
4. Choose "Mail" and "Other (Custom name)"
5. Enter "POP3 Forwarder" as the name
6. Click "Generate"
7. **Copy the 16-character password** (you'll need this in step 3)
### 3. Create Configuration File
```bash
cp .env.example .env
nano .env # or use your preferred editor
```
Edit the following required fields:
```bash
# Your POP3 mailbox
POP3_ACCOUNT_1_HOST=pop.yourprovider.com
POP3_ACCOUNT_1_USER=your-email@provider.com
POP3_ACCOUNT_1_PASSWORD=your-pop3-password
# Your Gmail account
SMTP_USER=youremail@gmail.com
SMTP_PASSWORD=xxxx-xxxx-xxxx-xxxx # The 16-char app password from step 2
GMAIL_DESTINATION=youremail@gmail.com
```
**Important**: Keep the same email for `SMTP_USER` and `GMAIL_DESTINATION`
### 4. Start the Container
```bash
docker-compose up -d
```
### 5. Verify It's Working
Check the logs:
```bash
docker-compose logs -f
```
You should see:
```
pop3-gmail-forwarder | INFO - POP3 to Gmail Forwarder starting...
pop3-gmail-forwarder | INFO - Loaded POP3 account: ...
pop3-gmail-forwarder | INFO - Configuration validated successfully
pop3-gmail-forwarder | INFO - Starting email processing cycle
```
### 6. Test the Forwarder
1. Send a test email to your POP3 account
2. Wait up to 5 minutes (or check the logs)
3. Check your Gmail inbox
4. You should see: `[Fwd from your-email@provider.com] Test Subject`
## Common Issues
### "Username and Password not accepted"
**Problem**: Gmail rejects login
**Fix**:
1. Make sure 2FA is enabled on your Google account
2. Generate a new App Password (don't use your regular Gmail password)
3. Copy it exactly without spaces into `SMTP_PASSWORD`
### "No address associated with hostname"
**Problem**: Can't connect to POP3 server
**Fix**:
1. Verify `POP3_ACCOUNT_1_HOST` is correct
2. Check if POP3 is enabled in your email provider's settings
3. Try port 110 with `POP3_ACCOUNT_1_USE_SSL=false` if port 995 doesn't work
### Container stops immediately
**Problem**: Container exits right after starting
**Fix**:
```bash
# Check logs for errors
docker-compose logs
# Common fixes:
# 1. Check .env file exists and has correct values
# 2. Verify all required fields are set
# 3. Check Docker has internet access
```
## Adding More POP3 Accounts
To forward from multiple email accounts:
```bash
# Edit .env and add more accounts:
POP3_ACCOUNT_2_HOST=pop.another.com
POP3_ACCOUNT_2_USER=user@another.com
POP3_ACCOUNT_2_PASSWORD=another-password
POP3_ACCOUNT_3_HOST=pop.yetanother.com
POP3_ACCOUNT_3_USER=user@yetanother.com
POP3_ACCOUNT_3_PASSWORD=yetanother-password
# Restart the container
docker-compose restart
```
## Managing the Service
```bash
# View logs
docker-compose logs -f
# Stop the service
docker-compose down
# Restart after config changes
docker-compose restart
# Rebuild after code updates
docker-compose up -d --build
```
## Optional: Error Notifications
To receive email alerts when errors occur:
1. Sign up at https://postmarkapp.com (free tier available)
2. Get your Server API Token
3. Add to `.env`:
```bash
POSTMARK_API_TOKEN=your-token-here
POSTMARK_FROM_EMAIL=errors@yourdomain.com
POSTMARK_TO_EMAIL=admin@yourdomain.com
```
4. Restart: `docker-compose restart`
## Customizing Settings
All settings in `.env` can be adjusted:
```bash
# Check every 10 minutes instead of 5
CHECK_INTERVAL_MINUTES=10
# Process up to 100 emails per run
MAX_EMAILS_PER_RUN=100
# Send up to 20 emails per minute
THROTTLE_EMAILS_PER_MINUTE=20
# Enable debug logging
LOG_LEVEL=DEBUG
```
Restart after changes: `docker-compose restart`
## Next Steps
- Read the full [README.md](README.md) for detailed documentation
- Review [MVP.md](MVP.md) for current features
- Check [ROADMAP.md](ROADMAP.md) for planned features
## Need Help?
- Open an issue: https://github.com/christianlouis/pop_puller_to_gmail/issues
- Check existing discussions
- Review troubleshooting section in README.md
## Success! 🎉
Your POP3 to Gmail forwarder is now running. Emails will be automatically forwarded every 5 minutes (or your configured interval).
**Remember**:
- The forwarder deletes emails from POP3 after successful forwarding
- Check Gmail spam folder if emails don't appear in inbox
- Monitor logs occasionally to ensure everything is working