From a7b0466d98496a435c80890859006893c7efabc5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 1 Feb 2026 12:17:59 +0000 Subject: [PATCH] Add QUICKSTART guide, LICENSE, and CONTRIBUTING documentation Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com> --- CONTRIBUTING.md | 176 +++++++++++++++++++++++++++++++++++++++++ LICENSE | 21 +++++ QUICKSTART.md | 206 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 403 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 QUICKSTART.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e704f79 --- /dev/null +++ b/CONTRIBUTING.md @@ -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! 🎉 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..fbf1a33 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..b2f900d --- /dev/null +++ b/QUICKSTART.md @@ -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