200ms/imapsync_ah2 repository overview

⁠ImapSync docker container

This container is a tool for e-mail synchronization (between two e-mail boxes). Emails can be synchronized from command line, or via Local Webserver.

You can jump to 'Docker compose YAML examples' below for a self-explaining YAML examples.

⁠Command line sync.

To synchronize mailboxes via IMAP define the following environmental variables (for source and target mailboxes):

  S_HOST: 'tls://imap.source-mail:585'
  S_USER: 'user_old@source-mail'
  T_HOST: 'ssl://imap.target-mail:993'
  T_USER: 'user_new@target-mail'
  # or, use short reference, see details below ⬇⬇
  # S_HOST: ':yahoo'
  # T_HOST: ':gmail'
  
  # Not obligatory: 
  S_PASS: 'secret6397/for-source_mail'
  T_PASS: 'secret837\for-target--mail'

NOTE: S_PASS and T_PASS are not obligatory, if not set, user will be prompted for a passwords (safer as passwords do not touch storage).

Example usage from the command line:

docker run -it  -e S_HOST=tls://imap.source-mail:585 \
                -e S_USER=user_old@source-mail \
                -e T_HOST=ssl://imap.target-mail:993 \
                -e T_USER=user_new@target-mail \
                --name cmd_imap_sync \
                200ms/imapsync_ah2

# in other terminal initiate synchronization: 
docker exec -it cmd_imap_sync mailsync
# at this point application will ask for passwords

mailsync command initiates synchronization between mailboxes. If S_PASS/T_PASS is not set, the program will prompt for passwords.

To see what would be done (without starting synchronization) use mailsync -p or mailsync --pretend.

⁠Short references - for popular email providers

For popular services, a colon ':' followed by a short service name ':service' can be used for S_HOST/T_HOST, e.g.:

(more in 'Short references' at the end).

⁠Local web server sync.

ImapSync comes with a simple webserver that provides a nice interface where user can define source and target mail servers. With this, user can synchronize mail boxes using web interface instead of a command line.

To use it, set variable 'WEBSERVER' to 'y' and open port 8080, example:

docker run -it -e WEBSERVER=y -p 8080:8080 \
          200ms/imapsync_ah2

and open http://localhost:8080/⁠

⁠Docker compose YAML examples

Below examples of usage with a docker compose.

⁠Synchronization from command line:

# command line synchronization: 
services:
  imap_sync:
    image: 200ms/imapsync_ah2
    environment:
      S_HOST: 'tls://host1:585'
      S_USER: '[email protected]'
      T_HOST: 'ssl://host2'
      T_USER: '[email protected]'

and run:

docker exec -it imap_sync mailsync

This will launch e-mail synchronization via IMAP protocol.

⁠Synchronization with local webserver (port 8080):

# Local webserver: 
services:
  imap_sync:
    image: 200ms/imapsync_ah2
    ports:
      - 8080:8080
    environment:
      WEBSERVER: 'y'

Synchronization can be initiated with a web application: http://localhost:8080/.

⁠URL schemas

S_HOST and T_HOST urls follows the following schemas:

⁠For secure connections:

If no port is specified, e.g.: ssl://example.com, default 993 is used.

⁠For unencrypted connections:

If no port provided, e.g.: localhost default 143 is used.

⁠For popular public services (GMail, ProtonMail):

See below the list of short references.

⁠Short references

mailsync comes with a predefined default IMAP URLs for a popular email services. You can use below shorts for S_HOST and T_HOST settings:

• :fastmail - FastMail
• :gmail - Gmail and Google Workspace IMAP
• :gmx - GMX Mail
• :icloud - iCloud Mail
• :ms365 - Microsoft Office 365 mailboxes
• :outlook - Microsoft Outlook.com mailboxes
• :ovh-europe - OVH IMAP settings for a European region
• :ovh-north_america - OVH IMAP settings for North America
• :ovh-asia_pacific - OVH IMAP settings for an Asia-Pacific region
• :yahoo - Yahoo Mail
• :yandex - Yandex Mail
• :zoho - Zoho Mail and Zoho Mail Business

If IMAPSync throws authentication errors, it might be due to the restrictive approach of a service provider (such as Gmail). The service may require two-factor authentication, which is not supported by IMAPSync.

To synchronize mail for a Gmail account, navigate to Google Account Settings → Security and turn ON "Less secure app access." This setting allows password-only authentication; however, it is advisable to turn it off again after synchronization.

⁠Encrypted mailboxes (ProtonMail)

To use Proton Mail end-to-end encryption with a regular e-mail clients, Proton Mail provides Proton Bridge application⁠.

An e-mail client connects to 'bridge' that is at the same localhost. It does encryption/decription (at the 'end') of a mailbox content. To sync e-mail via Proton Bridge, ImapSync must access that localhost service. However, by default, Docker sets a small NAT-ed network; preventing from accessing host's localhost. To connect with a Proton Bridge (:protonb), it is advised to set docker --network parameter to host (--network=host) - or use network_mode: host in compose.yaml. Notice that the actual password is set up with a Proton Bridge, that creates a new password to be used with an e-mail clinet — or with ImapSync.

• :protonb - default setting for proton mail bridge via localhost

ProtonMail example:

docker run -it -e S_HOST=:gmail -e t_HOST:protonb \
        -e [email protected] -e [email protected] \
        --network=host \
        200ms/imapsync_ah2

⁠ImapSync and MailSync

ImapSync is a command-line tool for migrating and syncing emails between IMAP servers, preserving folder structure and metadata. MailSync is a wrapper for ImapSync, providing documented here features.

Use mailsync -h for more information.

⁠TODO

• Add secure Gmail authentication support.
• Consider 'periodic syncs.', eg. mailsync --every 2h

⁠Troubleshooting

⁠Webserver fails: (option WEBSERVER=Y)

ImapSync's web server attempts to bind to IPv6 socket, but if IPv6 is disabled (a rare case), then the program fails. Ensure IPv6 is on (sysctl net.ipv6.conf.all.disable_ipv6 should be '0').

⁠Quality

This Docker Image is covered with tests, including fault injection testing. Images are build automatically for x86_64 and ARM64. Any issues are welcome at issues site⁠.

⁠About

Project's homepage:

https://bitbucket.org/200ms/docker-imapsync_ah2/⁠

Proposals, bugs or issues can be committed below:

https://bitbucket.org/200ms/docker-imapsync_ah2/issues?status=new&status=open⁠

Do you like the project? Star or coffee is very appreciated:

https://buymeacoffee.com/tools200ms⁠

⁠References

This project is a wrapper for ImapSync:

https://github.com/imapsync/imapsync.git⁠