netandreus/imap-sync

IMAP ➝ SQL syncing engine

v0.0.1 2020-03-24 07:40 UTC

Requires

• php: >=7.0
• ext-iconv: *
• ext-mbstring: *
• ext-pdo: *
• cboden/ratchet: ^0.4.1
• evenement/evenement: ^3.0
• ilya/belt: ^2.1
• league/climate: ^3.5
• mkraemer/react-pcntl: ^3.0
• monolog/monolog: ^1.24
• neitanod/forceutf8: ^2.0
• netandreus/imap: ^2.0
• netandreus/zend_mail: @dev
• particle/validator: ^2.3
• particlebits/pdo: @dev
• particlebits/zend-mime: @dev
• pimple/pimple: ^3.2.3
• react/child-process: ^0.5.2
• react/event-loop: @dev
• symfony/event-dispatcher: ^5.0.0
• zendframework/zend-crypt: ~2.5
• zendframework/zend-loader: ~2.5
• zendframework/zend-mime: ~2.5
• zendframework/zend-servicemanager: ^3.4
• zendframework/zend-validator: ~2.5

Suggests

• ext-intl: Handle IDN in AddressList hostnames
• ext-mysqlnd: MySQL Native Driver

MIT

• Mike Gioia
• Andrey Tokarchuk

README

This application synchronises IMAP accounts to a local MySQL database. You can use this as a standalone method to periodically download your email. The script is meant to run forever with almost zero maintenance :D

Web Client Admin Interface

Command Line Interface

Contents

• Dependencies
  1. Support for PHP 5.6
• Installation
  1. Create Database
  2. Configure the Application
  3. Install Composer Dependencies
  4. Running the Diagnostic Tests
  5. Running SQL Migration Scripts
• Run the IMAP Sync
• Using an Init Script or Supervisor
• Submitting Bugs

Dependencies

At a glance, this application requires the following:

• PHP 7.0 or newer
• MySQL / MariaDB 10.0 or newer
• ext-pdo, ext-iconv, and ext-mbstring

It's recommented to install ext-mysqlnd as well. php7.0-common should already be installed on your system.

Versions 7.1 and 7.2 are confirmed working, and this codebase is actively developed in version 7.2. See below for info about PHP 5.6.

1. Support for PHP 5.6

Version 1.0.0 of this application supports PHP 5.6, with compatibility for all of the composer dependencies at that snapshot.

If you'd like to use that, run the following command:

$> git checkout 1.0.0

All current and future updates will only support PHP 7.0 and higher!

Installation

1. Create Database

To get started, make sure you have MariaDB or MySQL running and issue the following command:

MariaDB [(none)]> CREATE DATABASE `libremail`;

The database name is a configuration option, so if you'd like to change this to be something other than libremail, make sure you update the config setting.

1.1 max_allowed_packet (MariaDB/MySQL)

Because of the amount of data that may be written to SQL (long email message text) a configuration setting needs to be enabled for MySQL databases allowing a larger packet size to be sent in a query. To do this, add the following line to your SQL config file:

[mysqld]
max_allowed_packet = 512M

You don't have to use 512MB as your packet size, but anything 16MB or higher is advised.

2. Configure the Application

Configuration options are saved in config/default.ini. Do not modify this file or anything in it. All of your changes should go into config/local.ini and should be in the INI file format, just like the default file. If you would like to make changes to config/local.ini but not ever commit them, run the following:

$> git update-index --assume-unchanged config/local.ini

View all possible configuration options: Configuration Options

3. Install Composer Dependencies

Download the vendor packages via Composer:

$> composer install

This will create a vendor directory with all of the project's PHP dependencies.

4. Running the Diagnostic Tests

You can run a test to see if the application is installed correctly, and that all dependencies and pre-requisites are met. To do that, run:

$> ./sync --diagnostics

You can also use -d as a short flag. This will go through and check the database connection, that all paths are writeable, and some other tests and see if the sync script will run correctly. These tests are run in the background before any sync happens, but you can access them this way for more detailed information in the case that something is failing.

5. Running SQL Migration Scripts

Before you can start syncing, run the SQL database scripts:

$> ./sync --updatedb

You can also use -u as a short flag. This will create all the SQL tables and run any other database operations.

Run the Sync

If you'd like, you can run ./sync --help to see a list of what options you have. View all possible configuration options and their details: Configuration Options

To use the CLI tool (debug mode), run:

$> ./sync

and follow the onscreen instructions.

To use the Web tool, run:

$> ./libremail

This tool will run silently and write to /logs. Open your browser and go to localhost:9898 to view the Web client.

Using an Init Script or Supervisor

If you'd like to run this sync script in the background all the time, then it is recommended to use some sort of supervisor or watchdog program to monitor if the script fails for any reason. Here are some guides for Linux and MacOS:

• SystemD
• SysV Init
• MacOS LaunchD

Submitting Bugs

All bugs and requests are tracked in the Github Issues for this repository. See the Issues Page for a listing of the open and closed tickets. Please search the closed issues before reporting anything to see if it has been resolved :)

This is an open source project that is worked on in spare time, so there is no guarantee that anything that you report will be looked at or fixed! However I will make a personal effort to resolve everything in a timely manner, and odds are good that I'll check it out quickly as I'm personally using this project to manage my own email.