I decided to set myself a little challenge to get ActiveSync working for free for a project I am working on. Most ActiveSync clients on the market are licensed directly from Microsoft.

I have an email service from the excellent MXRoute http://www.mxroute.com and I am not using the service much, they don’t currently offer a mobile solution so I thought I would see if it is possible to use a small virtual private server (VPS) to connect to IMAP and pass it to my mobile, turns out you can! I am using MXRoutes London servers, you will need to change the config if you are using any other locations.

Using Z-PUSH (2.3.5) to connect to MX Route

Known Issues:

Z-push syncs the shared address book, I haven’t worked out how to stop this, it’s a minor issue, but you do need to be aware of it.

Z-push fails to get the name of the calendar, so on an activesync device the calendar name shows up as unknown, but it works.

Z-push pulls the tasks through as a calendar, I have turned off syncing tasks.

Z-push itself isn’t the most reliable platform. This isn’t an issue per se, but it is something you need to be aware of.

Pre-Reqs

A VPS or server, I am running Ubuntu 16.04 LTS A MXRoute account Apache installed with an SSL cert (I’m using letencrypt) PHP7 with php-cli and php-soap Instructions

Add the z-push repo by creating /etc/apt/sources.list.d/z-push.list with the content

deb http://repo.z-hub.io/z-push:/final/Ubuntu_16.04/ /

Download and add the repo key to the keychain

wget -qO – http://repo.z-hub.io/z-push:/final/Debian_8.0/Release.key | sudo apt-key add –

Run apt-get update

We then need to install the z-push packages that we need

apt-get install z-push-common z-push-config-apache z-push-backend-caldav z-push-backend-carddav z-push-backend-combined z-push-backup-imap z-push-ipc-sharedmemory

This will install and configure z-push ready to go, we now need to edit the config files to tell it where to get the contacts, calendar and email from.

Start by editing /usr/share/z-push/config.php

Change the section “Default Settings” to match your timezone and ensure that the define(‘USE_FULLEMAIL_FOR_LOGIN’,true); is set to true.

Under the logging settings there is a specialLogUsers value, this is really useful to put a user in here when you need to troubleshoot, this generates debug logs for the named user and which can be found in the /var/log/z-push directory, but remember to remove them when you have done your testing as they can generate massive log files.

The only other setting we need to change is the Backend settings.

Change the backend provider setting to:

define(‘BACKEND_PROVIDER’,’BackendCombined’);

Save and exit the file

Next edit the /usr/share/z-push/backend/combined/config.php

Update it to match the following values

‘backends’ => array(
‘i’ => array(

‘name’ => ‘BackendIMAP’,

),

‘d’ => array(

‘name’ => ‘BackendCardDAV’,

),

‘c’ => array(

‘name’ => ‘BackendCalDAV’,

),

),

‘delimiter’ => ‘/’,

//force one type of folder to one backend

//it must match one of the above defined backends

‘folderbackend’ => array(

SYNC_FOLDER_TYPE_INBOX => ‘i’,

SYNC_FOLDER_TYPE_DRAFTS => ‘i’,

SYNC_FOLDER_TYPE_WASTEBASKET => ‘i’,

SYNC_FOLDER_TYPE_SENTMAIL => ‘i’,

SYNC_FOLDER_TYPE_OUTBOX => ‘i’,

// SYNC_FOLDER_TYPE_TASK => ‘c’,
SYNC_FOLDER_TYPE_APPOINTMENT => ‘c’,

SYNC_FOLDER_TYPE_CONTACT => ‘d’,

SYNC_FOLDER_TYPE_NOTE => ‘c’,

SYNC_FOLDER_TYPE_JOURNAL => ‘c’,

SYNC_FOLDER_TYPE_OTHER => ‘i’,

SYNC_FOLDER_TYPE_USER_MAIL => ‘i’,

SYNC_FOLDER_TYPE_USER_APPOINTMENT => ‘c’,

SYNC_FOLDER_TYPE_USER_CONTACT => ‘d’,

SYNC_FOLDER_TYPE_USER_TASK => ‘c’,

SYNC_FOLDER_TYPE_USER_JOURNAL => ‘c’,

SYNC_FOLDER_TYPE_USER_NOTE => ‘c’,

SYNC_FOLDER_TYPE_UNKNOWN => ‘i’,

),

//creating a new folder in the root folder should create a folder in one backend

‘rootcreatefolderbackend’ => ‘i’,

);

}

}

This tells z-push which backend is responsible for which function.

Next we need to edit the individual service files we will start with email.

Edit the file /usr/share/z-push/backend/imap/config.php

Update the following values, this is assuming you are using MXRoute’s London servers.

// Defines the server to which we want to connect

define(‘IMAP_SERVER’, ‘london.mxroute.com’);

// connecting to default port (143)

define(‘IMAP_PORT’, 993);

// best cross-platform compatibility (see http://php.net/imap_open for options)

define(‘IMAP_OPTIONS’, ‘/ssl/norsh’);

// Mark messages as read when moving to Trash.

// BE AWARE that you will lose the unread flag, but some mail clients do this so the Trash folder doesn’t get boldened

define(‘IMAP_AUTOSEEN_ON_DELETE’, false);

// Since I know you won’t configure this, I will raise an error unless you do.

// When configured set this to true to remove the error

define(‘IMAP_FOLDER_CONFIGURED’, true);

// Folder prefix is the common part in your names (3, 4)

define(‘IMAP_FOLDER_PREFIX’, ”);

// Inbox will have the preffix preppend (3 & 4 to true)

define(‘IMAP_FOLDER_PREFIX_IN_INBOX’, false);

// Inbox folder name (case doesn’t matter) – (empty in 4)

define(‘IMAP_FOLDER_INBOX’, ‘INBOX’);

// Sent folder name (case doesn’t matter)

define(‘IMAP_FOLDER_SENT’, ‘inbox.SENT’);

// Draft folder name (case doesn’t matter)

define(‘IMAP_FOLDER_DRAFT’, ‘inbox.DRAFTS’);

// Trash folder name (case doesn’t matter)

define(‘IMAP_FOLDER_TRASH’, ‘inbox.TRASH’);

// Spam folder name (case doesn’t matter). Only showed as special by iOS devices

define(‘IMAP_FOLDER_SPAM’, ‘inbox.junk’);

// Archive folder name (case doesn’t matter). Only showed as special by iOS devices

define(‘IMAP_FOLDER_ARCHIVE’, ‘ARCHIVE’);

You also want to update the method used for sending emails (I am using an SSL connection to MXRoute)

define(‘IMAP_SMTP_METHOD’, ‘smtp’);

global $imap_smtp_params;

$imap_smtp_params = array(‘host’ => ‘ssl://london.mxroute.com’, ‘port’ => 465, ‘auth’ => true, ‘username’ => ‘imap_username’, ‘password’ => ‘imap_password’ );

The above ‘imap_username’ and ‘imap_password’ are variables and do not need changing to the actual username and password.

Save and close the file.

Next we will setup syncing contacts

Edit /usr/share/z-push/backend/carddav/config.php update the following

// Server protocol: http or https

define(‘CARDDAV_PROTOCOL’, ‘https’);

// Server name

define(‘CARDDAV_SERVER’, ‘london.mxroute.com’);

// Server port

define(‘CARDDAV_PORT’, ‘2080’);

// Address book path

define(‘CARDDAV_PATH’, ‘/rpc/addressbooks/%u/’);

// Server path to the default address book

define(‘CARDDAV_DEFAULT_PATH’, ‘contacts/’);

// Support sync-collection

define(‘CARDDAV_SUPPORTS_SYNC’, false);

Save and close the file

Finally the calendar sync

Edit /usr/share/z-push/backend/caldav/config.php

// Server protocol: http or https

define(‘CALDAV_PROTOCOL’, ‘https’);

// Server name

define(‘CALDAV_SERVER’, ‘london.mxroute.com’);

// Server port

define(‘CALDAV_PORT’, ‘2080’);

// Path

define(‘CALDAV_PATH’, ‘/rpc/calendars/%u/’);

// Default CalDAV folder (calendar folder/principal). This will be marked as the default calendar in the mobile

define(‘CALDAV_PERSONAL’, ‘calendar’);

// If the CalDAV server supports the sync-collection operation

// DAViCal, SOGo and SabreDav support it

// SabreDav version must be at least 1.9.0, otherwise set this to false

// Setting this to false will work with most servers, but it will be slower

define(‘CALDAV_SUPPORTS_SYNC’, false);

// Maximum period to sync.

// Some servers don’t support more than 10 years so you will need to change this

define(‘CALDAV_MAX_SYNC_PERIOD’, 2147483647);

Save and close the file

Although not necessarily I restart apache at this point.

service apache2 restart

On your client device (iOS / Android / Outlook 2013+)

As there is no autodiscovery function you will need to enter the settings manually.

Username: Full email address

Password: Users MXRoute Password

Server: Your VPS address (i.e. z-push.yourdomain.com)

Basic Troubleshooting

Check the apache and z-push logs, both of which can be found in /usr/var/log/

Turn on debugging for a single user (see above for details)

Check you can access activesync on your server https://z-push.yourdomain.com/Microsoft-Server-ActiveSync, you should be promoted for a username and password use the email address and the users mxroute password, you should see a page that gives you the activesync information and tell you that “GET is not supported”.

You should now be good to go!