Using sup with other clients

TODO: Delete Maildir-syncback when this goes live.

If you use sup as the only means to access your mail, the default settings are fine. However, if you want to access your mail both via sup and, for example Google Mail, you will notice a problem: even though you read your mail in sup or star messages, these changes will not appear in the GMail interface. To do so, you need to enable two-way synchronization between your local Maildir source and sup, a.k.a. Maildir syncback.

How does it work?

Two-way synchronization writes changes you make in sup back to the original messages. The Maildir format supports several flags (read/unread, favorite, forwarded, replied, ...) that sup can set for you. Then, the next time you run OfflineIMAP, these changes will be replicated back to your server.

Note: labels are currently not synchronized.

Enabling Two-Way Synchronization

To enable two-way synchronization, you need to do two things:

1. enable it
2. perform a one-time synchronization of your existing sup flags back to your Maildir

Step 0: Backup

Although no problems are expected during these steps, it's always a good idea to perform a backup when trying something new with your mail. Since any changes will be reflected back to your server, cautious users may also want to disable OfflineIMAP (if they're using it) or back up e-mails and check they are happy with the result first before enabling OfflineIMAP again.

Step 1: Configuration

sup needs to be already set up correctly. If you're a new user, plese have a look at the New User Guide first.

Make sure sup is not running and open the file $HOME/.sup/config.yaml. Check if you have the following setting:

:sync_back_to_maildir: false

Change that line to

:sync_back_to_maildir: true

If your a long-time sup user, this setting might be missing. In that case, just add it.

This globally enables two-way synchronization, so it's active for all of your Maildir sources. See below on how to disable synchronization for specific accounts again, if you want to do so.

Step 2: Initial Synchronization

After configuration, the next time you start sup, it will complain:

WARNING
-------

It appears that the "sync_back_to_maildir" option has been changed
from false to true since the last execution of sup.

It is *strongly* recommended that you run "sup-sync-back-maildir"
before continuing, otherwise you might lose informations in your
Xapian index.

This script should be executed each time the "sync_back_to_maildir" is
changed from false to true.

Please run "sup-sync-back-maildir -h" to see why it is useful.

Are you really sure you want to continue? (y/N)

As recommended, you should run the sup-sync-back-maildir script. It will prompt you for each source and then synchronize all flags back into that source. If you skip a source, sup will complain again the next time you start it. See below on how to disable synchronization for specific sources.

Once sup is happy with your configuration and starts without complaining, you do not need to perform this step again, unless you add a new Maildir source.

Source-Specific Synchronization Configuration

You can disable synchronization for certain sources. When adding new sources via sup-add, you will be prompted if you wish to enable synchronization for each Maildir source - just answer "no". For existing sources, you can update the file $HOME/.sup/sources.yaml and add the following setting:

sync_back: false

If the setting is true or missing, synchronization will be performed.

Troubleshooting

I keep getting startup warnings even though I ran sup-sync-back-maildir!

Running sup-sync-back-maildir without parameters only synchronizes "usual" sources. If you have Maildir sources with usual: false, you need to pass these as parameters to sup-sync-back-maildir.

Something went wrong during sup-sync-back-maildir - can I run it again?

Yes. The master state is in sup and is only written to your Maildir sources via sup-sync-back-maildir. You can perform this several times - the result should always be OK. Just keep in mind that any changes performed outside of sup between runs - e.g. via GMail - will be lost.

I told sup to stop complaining about unsynchronized accounts, but I'd like to enable it again!

Just delete the file $HOME/.sup/sync-back-ok and perform Step 2 again.

I used an old version of the experimental maildir-sync branch and now I'm getting warnings during startup!

The file $HOME/.sup/sync-back-ok contains different information now. Just delete it and perform Step 2 again.