OfflineIMAP

関連記事

• isync
• notmuch
• msmtp

OfflineIMAP は IMAP サーバーからメールを同期する Python ユーティリティです。POP3 プロトコルや mbox は使えないため、通常 Mutt などの MUA と組み合わされて使われます。

インストール

offlineimap をインストールしてください。

設定

Offlineimap には2つのデフォルト設定ファイルが付属しており、どちらも /usr/share/offlineimap/ にあります。offlineimap.conf には全ての設定が含まれておりコメントが付与されています。一方、offlineimap.conf.minimal にはコメントが付いておらず多少の設定しか含まれていません (参照: #最小)。

デフォルト設定ファイルのどちらかを ~/.offlineimaprc または $XDG_CONFIG_HOME/offlineimap/config にコピーしてください。

ノート: 同じ行内に、オプションや値の後ろにコメントを書くのは無効な構文なので、コメントは別の独立した行に書いて下さい。

最小

offlineimap.conf.minimal のコメントが付いたバージョンは以下になります:

~/.offlineimaprc

[general]
# 同期するアカウントのリスト。コンマで区切る。
accounts = main

[Account main]
# ローカルリポジトリの識別子。例: IMAP経由で同期されるmaildir。
localrepository = main-local
# リモートリポジトリの識別子。すなわち実際のIMAPで、通常はローカルではありません。
remoterepository = main-remote

[Repository main-local]
# OfflineImapは、Maildir、GmailMaildir、およびIMAPをローカルリポジトリとしてサポートしています。
type = Maildir
# メールを配置する場所
localfolders = ~/mail

[Repository main-remote]
# リモートレポジトリはIMAPまたはGmailであり、後者は事前に設定されたIMAPです。
type = IMAP
remotehost = host.domain.tld
remoteuser = username
# OfflineImapのバージョンが6.5.4より高い場合、SSL接続に必要です。
sslcacertfile = /etc/ssl/certs/ca-certificates.crt

フォルダの同期の選択

特定のフォルダだけを同期したい場合、~/.offlineimaprc でアカウントの remote セクションに folderfilter を使います。例えば、以下の設定では Inbox と Sent フォルダだけが同期されます:

~/.offlineimaprc

[Repository main-remote]
# InboxとSentフォルダーのみ同期します:
folderfilter = lambda foldername: foldername in ["Inbox", "Sent"]
...

他のオプションについては、公式ドキュメント を見て下さい。

カスタムポート

IMAPサーバーの中には、デフォルトの993ポートではなく、カスタムポートの接続を要求してくるものがあります。そのようにするには、~/.offlineimaprcの remote セクションに remoteport オプションを追加します:

~/.offlineimaprc

[Repository main-remote]
remoteport=1234

使用方法

offlineimap を実行する前に、ローカルリポジトリに割り当てる親ディレクトリを作成してください:

$ mkdir ~/Maildir

そして、プログラムを実行してください:

$ offlineimap

メールアカウントが同期されます。何か問題が発生した場合、エラーメッセージをよく見て下さい。OfflineIMAP は基本的に問題について詳しい出力を表示します。最終的な製品からのトレースバックを取得するのに開発者が悩む必要がないようにするためです。

ヒントとテクニック

バックグラウンドで offlineimap を実行

大抵のメール転送エージェントはデフォルトで、プログラムを定期的に同期させることでデーモンとしてツールを使うのが前提になっています。offlineimap では、バックグラウンドで作業を制御する設定はあまりありません。

紛らわしいことに、バックグラウンドの設定は設定ファイルのあらゆるところに散らばっています:

~/.offlineimaprc

# generalセクション
[general]
# 同時に同期するアカウントの数を制御します
maxsyncaccounts = 1

# アカウント識別子
[Account main]
# 同期の間隔(分)
autorefresh = 0.5
# IMAPフラグにのみ変更があった場合、quick-syncsは更新されません。
# autorefresh=0.5 と quick=10 を組み合わせると、
# タイプに関係なく、各完全更新の間に0.5分の間隔で
# 10回のクイック更新が行われます。
quick = 10

# リモートリポジトリ識別子
[Repository main-remote]
# 同期が完了すると接続を閉じる代わりに、offlineimapはサーバーに空のデータを送信して接続を維持します。
# この値を60に設定すると、同期（クイックと自動更新の両方）の間に1分間接続を維持しようとします。
# この設定は、autorefresh と holdconnectionopen の両方が設定されていない場合は無効です。
keepalive = 60
# OfflineIMAPは通常、autorefreshグローバルオプションが指定されている場合、更新の合間にIMAPサーバ接続を閉じます。
# 接続を維持したい場合は、この設定をtrueに設定してください。
# autorefreshが設定されていない場合、この設定は効果がありません。
holdconnectionopen = yes

ログイン時にデーモンを自動的に起動するには、systemd/ユーザーサービスであるofflineimap.serviceを--userフラグ付きで起動/有効化してください。

複数のアカウントを設定している場合は、maxsyncaccountsパラメータ[1]を増やすのではなく、offlineimap@.serviceを使用することをお勧めします。offlineimap@youraccountname.serviceを起動/有効化するだけです。

systemd timer

あるいは、systemd-user タイマーを使って、offlineimap-oneshot.timerを--userフラグで起動/有効化することで、OfflineIMAPを完全に管理することもできます。

このタイマーはデフォルトで15分ごとにOfflineIMAPを実行します。これは、ドロップインファイルを作成することで変更することができます。例えば、以下では5分ごとにチェックするようにタイマーを修正しています:

~/.config/systemd/user/offlineimap-oneshot.timer.d/timer.conf

[Timer]
OnUnitInactiveSec=5m

より堅牢な解決法としては、フリーズした場合にOfflineIMAPをkillするウォッチドッグを設定することができます。

~/.config/systemd/user/offlineimap-oneshot.service.d/service.conf

[Service]
WatchdogSec=300

mutt 用に自動的にメールボックスを作成

Muttは 単にIMAP や Maildir のディレクトリを指し示したり、どのサブディレクトリがメールボックスであるかを推測することはできませんが、 offlineimap は同期するメールボックスを含む muttrc フラグメントを生成することができます。

~/.offlineimaprc

[mbnames]
enabled = yes
filename = ~/.mutt/mailboxes
header = "mailboxes "
peritem = "+%(accountname)s/%(foldername)s"
sep = " "
footer = "\n"

そして以下の行を~/.mutt/muttrcに追加します。

~/.mutt/muttrc

# IMAP: offlineimap
set folder = "~/Mail"
source ~/.mutt/mailboxes
set spoolfile = "+account/INBOX"
set record = "+account/Sent\ Items"
set postponed = "+account/Drafts"

accountは~/.offlineimaprcでIMAPアカウントにつけた名前です。

Gmail の設定

このリモートリポジトリは Gmail をサポートするために特別に設定されており、フォルダ名を大文字から小文字に置き換えたり、その他の細かい追加を行います。この設定では「すべてのメール」フォルダーを同期しないことに注意して下さい。「すべてのメール」は通常不要であり、この同期をスキップすることにより帯域幅コストを抑えるためです:

~/.offlineimaprc

[Repository gmail-remote]
type = Gmail
remoteuser = user@gmail.com
remotepass = password
nametrans = lambda foldername: re.sub ('^\[gmail\]', 'bak',
                               re.sub ('sent_mail', 'sent',
                               re.sub ('starred', 'flagged',
                               re.sub (' ', '_', foldername.lower()))))
folderfilter = lambda foldername: foldername not in ['[Gmail]/All Mail']
# OfflineImap 6.5.4 で必要
sslcacertfile = /etc/ssl/certs/ca-certificates.crt
# https://github.com/OfflineIMAP/offlineimap/issues/573（バージョン7.0.12、7.2.1）の対処に必要
ssl_version = tls1_2

ノート:

• Gmailが別の言語に設定されている場合、フォルダ名も翻訳されているように見える場合があります。 例: 「sent_mail」の代わりに「送信済みメール」
• バージョン6.3.5以降では、offlineimapはローカルのフォルダに合わせてリモートのフォルダも作成します。そのため、この名前の翻訳ルールの効果を逆転させる名前の翻訳ルールがローカルリポジトリにも必要になるかもしれません。名前の逆翻訳ルールを作りたくない場合は、リモートの設定に次のように記述することで、リモートフォルダの作成を無効にできます: createfolders = False
• 2012年10月1日現在、gmail の SSL 証明書のフィンガープリントはいつも同じだとは限りません。このため cert_fingerprint を使うよりも sslcacertfile を使って SSL の確認をするほうが良いでしょう (#SSL フィンガープリントが一致しないを参照)。

oama経由のOAuth2アクセストークン

oama (oama-bin^AUR)は、IMAP/SMTPクライアントにOAuth2認証の更新機能と承認を提供するユーティリティです。

OfflineIMAPは、設定からPythonコードを呼び出すことができます。したがって、まず[general]セクションで、以下の行を追加します。

~/.offlineimaprc

[general]
pythonfile = ~/.offlineimap.py

Pythonファイルに以下のコードを追加して、oamaを経由してOAuth2アクセストークンを取得します:

~/.offlineimap.py

import subprocess

def get_token(email_address):
    return subprocess.run(["oama", "access", email_address], capture_output=True, text=True).stdout

そして設定ファイルに戻り、Gmailアカウントのrepositoryセクションに以下を追加してください:

~/.offlineimaprc

auth_mechanisms = XOAUTH2
oauth2_client_id = YOUR_OAUTH2_CLIENT_ID
oauth2_client_secret = YOUR_OAUTH2_CLIENT_SECRET
oauth2_request_url = https://accounts.google.com/o/oauth2/token
oauth2_access_token_eval = get_token("YOUR_EMAIL_ADDRESS_FOR_THIS_ACCOUNT")

パスワードの管理

.netrc

以下の行を ~/.netrc に追加してください:

machine hostname.tld
    login [your username]
    password [your password]

ファイルに600や700のような適切な権限を与えることを忘れないでください。

$ chmod 600 ~/.netrc

ノート: OfflineIMAPは、.netrcファイルに複数のアカウントが保存されている場合、パスワードを取得する方法を知りません。

GPG を使う

GNU Privacy Guard を使うことで暗号化ファイルにパスワードを保存することができます。このセクションの設定を行う前にまず GnuPG をセットアップしてください。パスワードを入力しなくても GPG の秘密鍵をいつでも使えるようにしておく必要があります。

まずプレーンテキストファイルにメールアカウントのパスワードを入力してください。暗号化されていないパスワードがディスクに書き込まれないように、ファイルの作成は tmpfs 上の 700 パーミッションの安全なディレクトリで行って下さい。それから、GnuPGで自身を受信者にしてファイルを暗号化します:

必要なくなったプレーンテキストファイルは削除してください。暗号化したファイルは最終的に必要な場所 (例: ~/.offlineimappass.gpg) に移動してください。

次にパスワードを復号化する python 関数を作成します:

~/.offlineimap.py

#! /usr/bin/env python
from subprocess import check_output

def get_pass():
    return check_output("gpg -dq ~/.offlineimappass.gpg", shell=True).rstrip(b"\n")

上記のファイルを ~/.offlineimaprc からロードして、定義した関数を指定してください:

~/.offlineimaprc

[general]
# 任意のロードするPythonコードのパス
pythonfile = ~/.offlineimap.py
...

[Repository example]
# 暗号化されたパスワードを復号化して読み取る
remotepasseval = get_pass()
...

pass を使う

pass は GPG ベースのシンプルなコマンドラインのパスワードマネージャです。

最初にメールアカウントのパスワードを作成:

$ pass insert Mail/account

次にパスワードを復号化する python 関数を作成:

~/.offlineimap.py

#! /usr/bin/env python
from subprocess import check_output

def get_pass(account):
    return check_output("pass Mail/" + account, shell=True).splitlines()[0]

上記はマルチアカウントセットアップの例です。前述の pass の引数はカスタマイズできます。

~/.offlineimaprc からファイルをロードして、定義した関数を指定:

~/.offlineimaprc

[general]
# 任意のロードするPythonコードのパス
pythonfile = ~/.offlineimap.py
...

[Repository Gmail]
# 暗号化されたパスワードを復号化して読み取る
remotepasseval = get_pass("Gmail")
...

Gnome Keyring

リモートリポジトリの設定では、remoteusereval/remotepassevalフィールドを、ユーザー名/パスワードに評価するカスタムPythonコードに設定できます。このコードは、'pythonfile' 設定フィールドで示されたpythonスクリプト上で定義された関数への呼び出しにすることができます。以下のサブセクションに従って~/.offlineimap.pyを作成し、設定で使用します。

[general]
pythonfile = ~/.offlineimap.py

[Repository examplerepo]
type = IMAP
remotehost = mail.example.com
remoteusereval = get_username("examplerepo")
remotepasseval = get_password("examplerepo")

gkgetsecret.py

gnome-keyring、python2^AUR、python2-gobject^AUR、libsecretがインストールされていることを確認して下さい。そして、~/.offlineimap.pyを次の内容で作成します: gkgetsecret.py。さらに、上記のように~/.offlineimaprcにpythonfile = ~/.offlineimap.pyを設定します。

seahorseを使ってパスワードを作成した場合、その説明からパスワードを取得できます。例えば、Password for me@myworkemail.com という説明つきのgnome-keyringに保存された work レポジトリのパスワードは、~/.offlineimaprcに以下の行を追加することによって取得できます。

[Repository Work]
...
remotepasseval = get_pw_from_desc("Password for me@myworkemail.com")

同様にユーザー名も保存したい設定の場合、 secret-tool でパスワードを生成する方が、ユーザー名やリポジトリ名などの属性を設定するのに使えるのでよいでしょう。以下のコマンドでパスワードを作成することを検討して下さい。

$ secret-tool store --label "Password for Work Email" username me@myworkemail.com repo Work

このアカウントのユーザー名とパスワードは~/.offlineimaprcに以下の行を追加することによって取得できます。

[Repository Work]
...
remoteusereval = get_val_from_attrs("username", "repo", "Work")
remotepasseval = get_pw_from_attrs("repo", "Work")

python-keyring

どのキーリングでも使える一般的な解決策があります。python-keyringをインストールし、~/.offlineimaprcを以下のように変更して下さい。

[general]
pythonfile = /home/user/offlineimap.py
...
[Repository RemoteEmail]
remoteuser = username@host.net
remotepasseval = keyring.get_password("host","username")
...

そして、 ~/offlineimap.py のどこかに import keyring を追加して下さい.

あとはパスワードを設定するだけです。次のようなpythonスクリプトか、

$ python
>>> import keyring
>>> keyring.set_password("host","username", "MYPASSWORD")

あるいはpython-keyringパッケージで提供されているkeyringコマンドを使えます。

$ keyring --help
$ keyring set host username
Password for 'username' in 'host':
$ keyring get host username
password

これで、平文として保存したり毎回入力したりする必要なく、(kwallet/gnome-)キーリングからパスワードを取り出せるようになります。

Emacs EasyPG

http://www.emacswiki.org/emacs/OfflineIMAP#toc2 を見てください。

KeePassXCとFreedesktop.orgのsecret-service

libsecretをインストールし、KeepassXCの設定でFreedesktop.org secret-service統合を有効化、Database Settings > Secret Service Integrationでエントリを公開し、Edit Entry > Advanced設定でTitle追加属性にaccount@name.orgを追加します。これで、secret-tool lookup Title account@name.orgコマンドでパスワードがコンソールに表示されるはずです。次に、pythonスクリプトを作成します:

 ~/.script.py

#! /usr/bin/env python
import os
from subprocess import check_output

def get_pass(account):
    return check_output("secret-tool lookup Title " + account, shell=True).splitlines()[0].decode("UTF-8")

python-secretstorageに依存する同等のスクリプトは以下の通りです:

 ~/.script.py

#! /usr/bin/env python
import secretstorage
from contextlib import closing
def get_pass(title):
    with closing(secretstorage.dbus_init()) as conn:
        assert(secretstorage.check_service_availability(conn))
        collection = secretstorage.get_default_collection(conn)
        if collection.is_locked():
            collection.unlock()
        matches = collection.search_items({"Title": title})
        entry = next(matches)
        if entry.is_locked():
            entry.unlock()
        return(entry.get_secret())

~/.offlineimaprcからこのファイルをロードし、定義された関数を指定します:

~/.offlineimaprc

[general]
# 任意のロードするPythonコードのパス
pythonfile = ~/.script.py
...
[Repository Gmail]
# 暗号化されたパスワードを復号化して読み取る
remotepasseval = get_pass("account@name.org")
...

トラブルシューティング

UI の上書きと自動更新の設定

トラブルシューティングのために、より詳細なUI、バックグラウンド同期なし、場合によってはデバッグレベルでofflineimapを起動すると便利な場合があります:

$ offlineimap [ -o ] [ -d <debug_type> ] [ -u <ui> ]

-o

自動更新、キープアライブ等を無効にします。

-d <debug_type>

<debug_type>はimap、maildir、threadのいずれかです。imapとmaildirのデバッグが圧倒的に最も便利です。

-u <ui>

<ui>はCURSES.BLINKENLIGHTS、TTY.TTYUI、NONINTERACTIVE.BASIC、NONINTERACTIVE.QUIET、MACHINE.MACHINEUIのいずれかです。デバッグ目的ではTTY.TTYUIで十分です。

ノート: 新しいバージョンでは以下を<ui>に使います: blinkenlights、ttyui、basic、quiet、machineui

フォルダが作成できない

こちらにあるように、バージョン6.5.3でofflineimapはリモートリポジトリにフォルダを作成できるようになりました。

これにより、リモートリポジトリでnametransを使用すると以下のようなエラーが発生する可能性があります:

ERROR: Creating folder bar on repository foo-remote
  Folder 'bar'[foo-remote] could not be created. Server responded: ('NO', ['[ALREADYEXISTS] Duplicate folder name bar (Failure)'])

解決策は、ローカルリポジトリに逆nametransラムダを提供することです。例:

~/.offlineimaprc

[Repository foo-local]
nametrans = lambda foldername: foldername.replace('bar', 'BAR')

[Repository foo-remote]
nametrans = lambda foldername: foldername.replace('BAR', 'bar')

• 正しい逆マッピングを行うには、offlineimap --infoの出力が役に立つでしょう。
• マッピングを更新したら、影響を受けるアカウントの$HOME/.offlineimap/下のフォルダを全て削除する必要があるかもしれません。

SSL フィンガープリントが一致しない

ERROR: Server SSL fingerprint 'keykeykey' for hostname 'example.com' does not match configured fingerprint. Please verify and set 'cert_fingerprint' accordingly if not set yet.

これを解決するには、~/.offlineimaprc (ssl = yesと同じセクション)に以下のいずれかを追加します。

• リモートサーバーの証明書のフィンガープリントをcert_fingerprintに追加します。これは、リモートサーバーの証明書が与えられたフィンガープリントに一致するかチェックします。

cert_fingerprint = keykeykey

• もしくは、システムのCA証明書ファイルをsslcacertfileに追加します。ca-certificatesのインストールが必要です。これは、リモートのSSL証明書チェーンを、そのファイルの認証局に対して検証します。

sslcacertfile = /etc/ssl/certs/ca-certificates.crt

Copying message, connection closed

ERROR: Copying message -2 [acc: email] connection closed
Folder sent [acc: email]: ERROR: while syncing sent [account email] connection closed

上記の問題はローカルとサーバーで同じメッセージが作成されていることが原因です。メールのプロバイダが自動的にローカルクライアントと同じフォルダに送信したメールを保存した場合に発生します。この問題が起こったときはローカルクライアントで送信済みメッセージの保存を無効化してください。

参照

• OfflineIMAP 公式メーリングリスト
• Mutt + Gmail + Offlineimap - brisbinによるシンプルなgmail/muttの設定の概要。cronでofflineimapの同期を保持させています。