gh-christianlouis-inboxconverge/docs/QUICKSTART.md

Quick Start Guide

Get your InboxConverge instance 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

git clone https://github.com/christianlouis/inboxconverge.git
cd inboxconverge

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 "InboxConverge" as the name
6. Click "Generate"
7. Copy the 16-character password (you'll need this in step 3)

3. Create Configuration File

cp .env.example .env
nano .env  # or use your preferred editor

Edit the following required fields:

# 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

docker-compose up -d

5. Verify It's Working

Check the logs:

docker-compose logs -f

You should see:

inboxconverge | INFO - InboxConverge starting...
inboxconverge | INFO - Loaded POP3 account: ...
inboxconverge | INFO - Configuration validated successfully
inboxconverge | 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:

# 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:

# 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

# 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:

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:

# 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 for detailed documentation
• Review MVP.md for current features
• Check ROADMAP.md for planned features

Need Help?

• Open an issue: https://github.com/christianlouis/inboxconverge/issues
• Check existing discussions
• Review troubleshooting section in README.md

Success! 🎉

Your InboxConverge instance 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