A production-ready Docker service that automatically monitors POP3 mailboxes for voicemails and forwards them via email with audio attachments. Perfect for integrating legacy voicemail systems with modern email workflows.

• 🔄 Automated POP3 Polling: Continuously monitors configured mailboxes with customizable intervals
• 📧 Smart Email Forwarding: Forwards voicemails via SMTP with preserved audio attachments
• 🎯 Duplicate Prevention: SQLite-based tracking ensures messages are never forwarded twice
• 🖥️ Web Management UI: Browser-based interface for easy configuration and monitoring
• 📁 Attachment Archiving: Automatically saves audio files locally for audit and backup
• 📊 Comprehensive Logging: Detailed logs with POP3 response codes and processing status
• 🔐 Secure: Supports TLS/STARTTLS for both POP3 and SMTP connections
• 🐳 Container-Ready: Minimal Alpine-based Docker image with persistent volumes

• Quick Start
• Configuration
• Web Interface
• Architecture
• Networking
• Volumes
• Environment Variables
• Building from Source
• Troubleshooting
• Contributing
• License

docker run -d \
  --name voicemail-forwarder \
  --network host \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  dblagbro/voicemail-forwarder:latest

services:
  voicemail-forwarder:
    image: dblagbro/voicemail-forwarder:latest
    container_name: voicemail-forwarder
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

After starting, access the web UI at http://localhost:8089

The easiest way to configure the service is through the web UI at http://localhost:8089:

1. Mailboxes Tab: Add POP3 mailboxes to monitor
2. Settings Tab: Configure SMTP server for forwarding
3. System Settings: Adjust polling interval and preferences

Configuration is stored in data/config.json:

{
  "mailboxes": [
    {
      "name": "4013",
      "pop3_host": "mail.example.com",
      "pop3_port": 110,
      "pop3_user": "4013",
      "pop3_pass": "password",
      "use_stls": false,
      "dest_to": "[email protected]",
      "enabled": true
    }
  ],
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "use_tls": true,
    "username": "[email protected]",
    "password": "your-app-password"
  },
  "poll_interval_seconds": 300,
  "smtp_from": "[email protected]"
}

The web interface provides comprehensive monitoring and management:

• Manual poll trigger button
• System status overview
• Recent activity summary

• Add/edit/delete mailbox configurations
• Enable/disable individual mailboxes
• Test connections
• Change mailbox passwords

• Browse archived audio files
• Listen to voicemails directly in browser
• Download attachments
• View metadata (date, size, mailbox)

• Real-time log viewer
• Filter by log level
• Search functionality
• Download logs

• Configure SMTP server
• Adjust polling intervals
• Test email delivery

┌──────────────┐
│  POP3 Server │
└──────┬───────┘
       │ Poll every N seconds
       ▼
┌──────────────────┐
│ Voicemail        │
│ Forwarder        │
│                  │
│ 1. Connect       │
│ 2. Authenticate  │
│ 3. List messages │
│ 4. Check UIDL    │───► SQLite (seen messages)
│ 5. Fetch new     │
│ 6. Forward       │───► SMTP Server ───► Recipient
│ 7. Archive       │───► Local storage
└──────────────────┘

• Flask Web Server: Provides REST API and web UI
• Core Poller: Handles POP3 polling and message processing
• State Manager: SQLite database for tracking processed messages
• Archive Manager: Saves audio attachments to persistent storage
• Gunicorn: Production WSGI server

This service requires network_mode: host to access POP3 servers on local networks:

network_mode: host

Why host networking?

• Direct access to LAN-based POP3 servers
• No NAT traversal issues
• Simplified configuration

If using Docker bridge networking:

1. Ensure proper routing to POP3 servers
2. Map port 8089: ports: ["8089:8089"]
3. Configure firewall rules if needed

Example nginx configuration for HTTPS access:

location /voicemail-forwarder {
    proxy_pass http://localhost:8089;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

data/
├── config.json           # Configuration file
└── state.db             # SQLite database (processed messages)

logs/
└── forwarder.log        # Application logs

attachments/             # Created automatically
├── mailbox_4013/
│   ├── 2026-01-10_voicemail.wav
│   └── ...
└── mailbox_1000/
    └── ...

Example:

docker run -d \
  -e TZ=America/New_York \
  -e PORT=8090 \
  --network host \
  dblagbro/voicemail-forwarder:latest

# Clone the repository
git clone https://github.com/dblagbro/voicemail-forwarder.git
cd voicemail-forwarder

# Build the image
docker build -t voicemail-forwarder:local .

# Run the container
docker run -d \
  --name voicemail-forwarder \
  --network host \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  voicemail-forwarder:local

# Install dependencies
pip install -r requirements.txt

# Run locally
cd app
python app.py

Symptoms: Logs show timeout or connection refused errors

Solutions:

• Verify POP3 host/port are correct
• Check firewall rules
• Test connection: telnet pop3_host 110
• Ensure using network_mode: host if on LAN

Symptoms: Logs show "already_seen" for new messages

Solutions:

• Check SMTP configuration in Settings
• Test SMTP connection
• Clear state database: rm data/state.db (will reprocess all messages)
• Check logs for SMTP errors

Symptoms: Cannot reach http://localhost:8089

Solutions:

• Verify container is running: docker ps
• Check port mapping: docker port voicemail-forwarder
• Review container logs: docker logs voicemail-forwarder
• Ensure no port conflicts

Symptoms: Logs show forwarding but attachments missing

Solutions:

• Check volume permissions
• Verify disk space: df -h
• Review logs for file I/O errors

Enable detailed logging by checking the logs tab in the web UI or:

docker exec -it voicemail-forwarder tail -f /app/logs/forwarder.log

Test POP3 connection manually:

# Install telnet or nc
telnet pop3_server 110

# Commands to test
USER username
PASS password
STAT
UIDL
QUIT

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Built with Flask and Gunicorn
• Uses SQLite for state management
• Containerized with Docker Alpine

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Note: This is designed for enterprise voicemail systems that use POP3 for message delivery. Common use cases include Avaya Communication Manager, Cisco Unity, and similar systems.