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

Clean up repo: move docs to docs/, add SECURITY.md, .editorconfig, update README with badges, fix cross-references, correct documentation to reflect actual project state

Browse Source 
Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
Agent-Logs-Url: https://github.com/christianlouis/pop_puller_to_gmail/sessions/71f26285-5584-42b2-8255-8ad2c9e9ecb4
This commit is contained in:
copilot-swe-agent[bot]
2026-03-23 10:57:31 +00:00
parent 88a44dfe73
commit b3a0c4bfd8
22 changed files with 223 additions and 316 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+117 -275
View File
@@ -1,135 +1,61 @@
# POP3 to Gmail Forwarder
[![CI Tests](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/test.yml/badge.svg)](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/test.yml)
[![Lint](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/lint.yml/badge.svg)](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/lint.yml)
[![Security Scan](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/security.yml/badge.svg)](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/security.yml)
[![Docker Build](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/docker-build.yml/badge.svg)](https://github.com/christianlouis/pop_puller_to_gmail/actions/workflows/docker-build.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)
A Docker-based solution that automatically fetches emails from POP3 mailboxes and forwards them to Gmail, replacing Google's discontinued POP3 import feature.
## Features
- ✅ **Multiple POP3 Accounts**: Support for unlimited POP3 mailboxes via environment variables
- ✅ **Automatic Forwarding**: Sends emails to your Gmail account via SMTP
- ✅ **Smart Throttling**: Rate limiting to avoid Gmail quotas (configurable emails per minute)
- ✅ **Error Reporting**: Email notifications via Postmarkapp when issues occur
- ✅ **Scheduled Polling**: Configurable check intervals (default: every 5 minutes)
- ✅ **Docker Ready**: Fully containerized with docker-compose support
- ✅ **Secure**: Runs as non-root user, uses SSL/TLS for connections
- ✅ **Production Ready**: Comprehensive logging, error handling, and best practices
- **Multiple POP3 Accounts** — support for unlimited POP3 mailboxes via environment variables
- **Automatic Forwarding** — sends emails to your Gmail account via SMTP
- **Smart Throttling** — configurable rate limiting to stay within Gmail quotas
- **Error Reporting** — notifications via Postmarkapp when issues occur
- **Scheduled Polling** — configurable check intervals (default: every 5 minutes)
- **Docker Ready** — fully containerized with Docker Compose support
- **Secure** — runs as non-root user, SSL/TLS connections
### SaaS Platform (in development)
The repository also includes a multi-tenant SaaS backend built with FastAPI, PostgreSQL, Redis, and Celery. It adds multi-user support, OAuth2 authentication, POP3/IMAP protocol support, encrypted credential storage, and background job processing. See the [SaaS README](docs/README_SAAS.md) for details.
## Quick Start
### Prerequisites
- Docker and Docker Compose installed
- A Gmail account with [App Password](https://support.google.com/accounts/answer/185833) enabled
- POP3 account credentials
- (Optional) Postmarkapp account for error notifications
### Option 1: Using Pre-built Docker Image (Recommended)
The Docker images are automatically built and published to GitHub Container Registry.
1. **Create configuration file**
```bash
# Download the docker-compose.yml and .env.example
curl -O https://raw.githubusercontent.com/christianlouis/pop_puller_to_gmail/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/christianlouis/pop_puller_to_gmail/main/.env.example
# Edit .env with your credentials
nano .env
```
2. **Update docker-compose.yml to use the pre-built image**
```yaml
version: '3.8'
services:
pop3-forwarder:
image: ghcr.io/christianlouis/pop_puller_to_gmail:latest
container_name: pop3-gmail-forwarder
restart: unless-stopped
env_file:
- .env
```
3. **Run the container**
```bash
docker-compose up -d
```
### Option 2: Building from Source
1. **Clone the repository**
```bash
git clone https://github.com/christianlouis/pop_puller_to_gmail.git
cd pop_puller_to_gmail
```
2. **Configure environment variables**
```bash
cp .env.example .env
# Edit .env with your credentials
nano .env
```
3. **Essential Configuration**
Edit `.env` and set:
```bash
# Your POP3 account(s)
POP3_ACCOUNT_1_HOST=pop.yourprovider.com
POP3_ACCOUNT_1_PORT=995
POP3_ACCOUNT_1_USER=your-email@provider.com
POP3_ACCOUNT_1_PASSWORD=your-password
# Your Gmail SMTP settings
SMTP_USER=your-gmail@gmail.com
SMTP_PASSWORD=your-app-password # Generate at myaccount.google.com/apppasswords
GMAIL_DESTINATION=your-gmail@gmail.com
# Optional: Postmarkapp for error notifications
POSTMARK_API_TOKEN=your-token
POSTMARK_FROM_EMAIL=errors@yourdomain.com
POSTMARK_TO_EMAIL=admin@yourdomain.com
```
4. **Run with Docker Compose**
```bash
docker-compose up -d
```
5. **Check logs**
```bash
docker-compose logs -f
```
## Using Pre-built Docker Images
Docker images are automatically built and published to GitHub Container Registry for every release and commit to the main branch.
### Available Image Tags
- `ghcr.io/christianlouis/pop_puller_to_gmail:latest` - Latest build from main branch
- `ghcr.io/christianlouis/pop_puller_to_gmail:v1.0.0` - Specific version tags
- `ghcr.io/christianlouis/pop_puller_to_gmail:main` - Main branch builds
### Pull and Run
### Using a Pre-built Docker Image (Recommended)
```bash
# Pull the latest image
docker pull ghcr.io/christianlouis/pop_puller_to_gmail:latest
# Pull and configure
curl -O https://raw.githubusercontent.com/christianlouis/pop_puller_to_gmail/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/christianlouis/pop_puller_to_gmail/main/.env.example
# Run directly with Docker
docker run -d \
--name pop3-forwarder \
--env-file .env \
--restart unless-stopped \
ghcr.io/christianlouis/pop_puller_to_gmail:latest
# Edit .env with your credentials
nano .env
# Start
docker-compose up -d
```
### Building from Source
```bash
git clone https://github.com/christianlouis/pop_puller_to_gmail.git
cd pop_puller_to_gmail
cp .env.example .env # then edit .env
docker-compose up -d
```
See the [Quick Start Guide](docs/QUICKSTART.md) for detailed instructions.
## Configuration
### POP3 Accounts
Add multiple POP3 accounts by incrementing the account number:
Add multiple POP3 accounts by incrementing the account number in your `.env`:
```bash
POP3_ACCOUNT_1_HOST=pop.provider1.com
@@ -139,199 +65,115 @@ POP3_ACCOUNT_1_PASSWORD=password1
POP3_ACCOUNT_2_HOST=pop.provider2.com
POP3_ACCOUNT_2_USER=user2@provider2.com
POP3_ACCOUNT_2_PASSWORD=password2
# ... add more as needed
```
### Gmail App Password
1. Go to your Google Account: https://myaccount.google.com/
2. Select Security
3. Under "Signing in to Google," select App Passwords
4. Generate a new app password for "Mail"
5. Use this password in `SMTP_PASSWORD`
1. Go to your [Google Account Security](https://myaccount.google.com/security)
2. Under "Signing in to Google," select **App Passwords**
3. Generate a new app password for "Mail"
4. Use this password as `SMTP_PASSWORD`
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `POP3_ACCOUNT_N_HOST` | Yes | - | POP3 server hostname |
| `POP3_ACCOUNT_N_PORT` | No | 995 | POP3 server port |
| `POP3_ACCOUNT_N_USER` | Yes | - | POP3 username |
| `POP3_ACCOUNT_N_PASSWORD` | Yes | - | POP3 password |
| `POP3_ACCOUNT_N_USE_SSL` | No | true | Use SSL/TLS |
| `SMTP_HOST` | No | smtp.gmail.com | SMTP server |
| `SMTP_PORT` | No | 587 | SMTP port |
| `SMTP_USER` | Yes | - | SMTP username |
| `SMTP_PASSWORD` | Yes | - | SMTP password (App Password) |
| `SMTP_USE_TLS` | No | true | Use STARTTLS |
| `GMAIL_DESTINATION` | Yes | - | Destination Gmail address |
| `CHECK_INTERVAL_MINUTES` | No | 5 | How often to check for new mail |
| `MAX_EMAILS_PER_RUN` | No | 50 | Max emails to process per account per run |
| `THROTTLE_EMAILS_PER_MINUTE` | No | 10 | Rate limit for sending emails |
| `POSTMARK_API_TOKEN` | No | - | Postmarkapp API token |
| `POSTMARK_FROM_EMAIL` | No | - | Error notification sender |
| `POSTMARK_TO_EMAIL` | No | - | Error notification recipient |
| `LOG_LEVEL` | No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `POP3_ACCOUNT_N_HOST` | Yes | — | POP3 server hostname |
| `POP3_ACCOUNT_N_PORT` | No | `995` | POP3 server port |
| `POP3_ACCOUNT_N_USER` | Yes | — | POP3 username |
| `POP3_ACCOUNT_N_PASSWORD` | Yes | — | POP3 password |
| `POP3_ACCOUNT_N_USE_SSL` | No | `true` | Use SSL/TLS |
| `SMTP_HOST` | No | `smtp.gmail.com` | SMTP server |
| `SMTP_PORT` | No | `587` | SMTP port |
| `SMTP_USER` | Yes | — | SMTP username |
| `SMTP_PASSWORD` | Yes | — | SMTP password (App Password) |
| `SMTP_USE_TLS` | No | `true` | Use STARTTLS |
| `GMAIL_DESTINATION` | Yes | — | Destination Gmail address |
| `CHECK_INTERVAL_MINUTES` | No | `5` | Polling interval |
| `MAX_EMAILS_PER_RUN` | No | `50` | Max emails per account per run |
| `THROTTLE_EMAILS_PER_MINUTE` | No | `10` | Rate limit |
| `POSTMARK_API_TOKEN` | No | — | Postmarkapp API token |
| `POSTMARK_FROM_EMAIL` | No | — | Error notification sender |
| `POSTMARK_TO_EMAIL` | No | — | Error notification recipient |
| `LOG_LEVEL` | No | `INFO` | Logging level |
## How It Works
1. **Polling**: The application checks configured POP3 mailboxes at regular intervals
2. **Fetching**: Retrieves new emails from each POP3 account
3. **Forwarding**: Sends emails to your Gmail account via SMTP with original metadata preserved
4. **Cleanup**: Deletes emails from POP3 server after successful forwarding
5. **Throttling**: Respects rate limits to avoid Gmail quota issues
6. **Error Handling**: Sends notifications via Postmarkapp if issues occur
## Email Format
Forwarded emails include:
- Original sender information in the subject line: `[Fwd from user@provider.com] Original Subject`
- Header section with original From, Date, Subject, and source account
- Original email body preserved
## Monitoring and Logs
### View logs
```bash
docker-compose logs -f pop3-forwarder
```
### Check container status
```bash
docker-compose ps
```
### Restart the service
```bash
docker-compose restart
```
## Troubleshooting
### Gmail Authentication Issues
**Problem**: "Username and Password not accepted"
**Solution**:
- Ensure 2FA is enabled on your Google account
- Generate an App Password (don't use your regular Gmail password)
- Use the 16-character app password without spaces
### POP3 Connection Issues
**Problem**: "Connection refused" or "SSL error"
**Solution**:
- Verify POP3 server hostname and port
- Check if POP3 is enabled in your email provider settings
- Try with `POP3_ACCOUNT_N_USE_SSL=false` for non-SSL connections (port 110)
### No Emails Being Forwarded
**Problem**: Container runs but no emails are forwarded
**Solution**:
- Check if there are emails in your POP3 mailbox
- Review logs for errors: `docker-compose logs -f`
- Verify `GMAIL_DESTINATION` is correct
- Check Gmail spam folder
### Rate Limiting
**Problem**: "Too many requests" or quota errors
**Solution**:
- Increase `CHECK_INTERVAL_MINUTES`
- Decrease `THROTTLE_EMAILS_PER_MINUTE`
- Reduce `MAX_EMAILS_PER_RUN`
## Security Best Practices
1. **Never commit `.env` file** - It contains sensitive credentials
2. **Use App Passwords** - Don't use your main Gmail password
3. **Rotate credentials regularly** - Update passwords periodically
4. **Enable 2FA** - On all email accounts
5. **Review logs** - Monitor for suspicious activity
6. **Use SSL/TLS** - Keep `USE_SSL` and `USE_TLS` enabled
7. **Limit network access** - Use firewall rules if needed
## Development
### Local Development (without Docker)
```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Copy and configure .env
cp .env.example .env
# Edit .env with your settings
# Run the application
python pop3_forwarder.py
```
### Building the Docker Image
```bash
docker build -t pop3-gmail-forwarder .
```
### Running Tests
```bash
# Run with verbose logging
LOG_LEVEL=DEBUG docker-compose up
```
## Architecture
```
┌─────────────────┐
│ POP3 Server 1 │
└────────┬────────┘
│
│ (Fetch emails)
│
▼
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
│ POP3 Server 2 │─────▶│ Forwarder │─────▶│ Gmail │
└─────────────────┘ │ Container │ │ (SMTP) │
│ └──────┬───────┘ └─────────────┘
│ │
┌────────▼────────┐ │
│ POP3 Server N │ │
└─────────────────┘ │
│ (Error notifications)
▼
┌─────────────────┐
┌────────▼────────┐ │ (Error notifications)
│ POP3 Server N │ ▼
└─────────────────┘ ┌─────────────────┐
│ Postmarkapp │
└─────────────────┘
```
1. **Polling** — checks POP3 mailboxes at the configured interval
2. **Fetching** — retrieves new emails from each account
3. **Forwarding** — delivers to Gmail with original metadata preserved
4. **Cleanup** — deletes from POP3 after successful forwarding
5. **Throttling** — respects rate limits to avoid quota issues
6. **Error Handling** — sends notifications if something goes wrong
## Development
```bash
# Install dependencies
make install-dev
# Run linting & formatting
make lint
make format
# Run tests
make test
# Start backend in dev mode
make run-dev
```
See the [Testing Guide](docs/TESTING_GUIDE.md) for the full test workflow.
## Documentation
Detailed documentation lives in the [`docs/`](docs/) directory:
| Document | Description |
|----------|-------------|
| [Architecture](docs/ARCHITECTURE.md) | System design and component overview |
| [Quick Start](docs/QUICKSTART.md) | Step-by-step setup guide |
| [Migration Guide](docs/MIGRATION_GUIDE.md) | Upgrading from v1 to v2 |
| [Deployment Checklist](docs/DEPLOYMENT_CHECKLIST.md) | Production deployment guide |
| [Roadmap](docs/ROADMAP.md) | Planned features and milestones |
| [Testing Guide](docs/TESTING_GUIDE.md) | How to run and write tests |
| [Coding Patterns](docs/CODING_PATTERNS.md) | Code style and conventions |
| [SaaS README](docs/README_SAAS.md) | Multi-tenant SaaS platform details |
## Contributing
Contributions are welcome! Please:
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
- Reporting bugs and suggesting features
- Development setup and code style
- Pull request process
## Security
To report a vulnerability, please see [SECURITY.md](SECURITY.md). **Do not open public issues for security concerns.**
## License
MIT License - See LICENSE file for details
This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
## Support
- **Issues**: https://github.com/christianlouis/pop_puller_to_gmail/issues
- **Discussions**: https://github.com/christianlouis/pop_puller_to_gmail/discussions
## Acknowledgments
Built to replace Gmail's discontinued POP3 import feature. Uses industry-standard Python libraries for email handling and Docker for easy deployment.
- [Issue Tracker](https://github.com/christianlouis/pop_puller_to_gmail/issues)
- [Discussions](https://github.com/christianlouis/pop_puller_to_gmail/discussions)