Features

• Real-time sync — Uses IMAP IDLE for instant email forwarding
• Multiple sources — Forward from multiple email accounts to a single Gmail
• Original headers preserved — Emails arrive with their original From, Reply-To, and other headers intact
• Selective folders — Choose which folders to sync (e.g. only INBOX)
• Auto cleanup — Optionally delete messages after successful forwarding
• Production-grade — Auto reconnect with exponential backoff, health check endpoint
• Minimal footprint — Only 1 runtime dependency (imapflow)
• Docker ready — Alpine-based image with built-in health checks

Installation

npm

npm install -g imapforward

Docker

docker pull ghcr.io/sinedied/imapforward:latest

Configuration

Create a config.json file. You can use the online configuration generator to build it interactively.

{
  "target": {
    "host": "imap.gmail.com",
    "port": 993,
    "secure": true,
    "auth": {
      "user": "your-email@gmail.com",
      "pass": "your-app-password"
    }
  },
  "sources": [
    {
      "name": "Work Email",
      "host": "imap.work.com",
      "port": 993,
      "secure": true,
      "auth": {
        "user": "user@work.com",
        "pass": "password"
      },
      "folders": ["INBOX"],
      "deleteAfterForward": false
    }
  ],
}

Configuration Reference

Usage

CLI

# Run with default config.json in current directory
imapforward

# Set log level
imapforward --log-level debug

# Custom config path
imapforward --config /path/to/config.json

CLI Options

Environment Variables

Docker

Run with Docker

docker run -d \
  --name imapforward \
  -v $(pwd)/config.json:/app/config.json:ro \
  ghcr.io/sinedied/imapforward:latest

Docker Compose

services:
  imapforward:
    image: ghcr.io/sinedied/imapforward:latest
    restart: unless-stopped
    volumes:
      - ./config.json:/app/config.json:ro

Health Check

The health check server is always enabled (default port 8080). You can customize the port in your config:

{
  "healthCheck": {
    "port": 9090
  }
}

The HTTP health endpoint is available at:

curl http://localhost:8080/health

Response:

{
  "status": "ok",
  "sources": [
    {
      "name": "Work Email",
      "connected": true,
      "lastSync": "2026-02-25T10:30:00.000Z",
      "error": null
    }
  ]
}

Status values: ok (all connected), degraded (some connected), error (none connected).

How It Works

1. Connects to each configured IMAP source account
2. Scans for unseen messages that haven't been forwarded yet
3. Appends each message to the target mailbox via IMAP preserving all original headers (raw RFC822)
4. Marks forwarded messages with a $Forwarded IMAP flag
5. Enters IMAP IDLE mode to watch for new messages in real-time
6. Automatically reconnects with exponential backoff on connection loss