メールによるチケット登録
最終更新: 2017/10/03
Redmineは、メールによるチケット登録や更新ができるよう設定できます。また、 コメントを許可するように設定できます。また、メールに返信することでフォーラムのメッセージのコメントを追加することもできます。
設定
以下のいずれかの方法でRedmineがメールを受け取るよう設定できます:
- メールサーバからメールを転送:
- 利点: メールサーバがRedmineとは異なるサーバでもよい、メールがタイムラグなしで処理される、高速(アプリケーションのリロードが不要)
- 欠点: MTAの設定が必要 (PostfixやSendmailなど)
- IMAPサーバからの受信:
- 利点: 設定が容易、MTAの設定が不要、メールサーバがRedmineとは異なるサーバでもよい
- 欠点: メールがRedmineに反映されるまでタイムラグがある (定期的にメールの取得を行うためのcronのジョブを追加する必要がある)
- 標準入力からのメール読み込み:
- 利点: テスト用途に最適
- 欠点: 遅い(メールが到着するごとにRedmineのアプリケーションのリロードが行われる), MTAの設定が必要
メールサーバからメールを転送
受信したメールをメールサーバからRedmineに転送するためのスクリプトが利用できます。のスクリプトはメールを標準入力から読み込み、HTTP経由でRedmineに転送します。
スクリプトはRedmineのディレクトリ内にあります:
extra/mail_handler/rdm-mailhandler.rb
このスクリプトを利用するためには、メール受信のためのAPIを有効にする必要があります: 「設定」→「受信メール」に移動し、 受信メール用のWebサービスを有効にする のチェックボックスをonにして、APIキーを入力するか生成してください。
rdm-mailhandler.rb をメールサーバにコピーし、実行を許可するようパーミッションを設定し(chmod +x rdm-mailhandler.rb)、MTAの設定を行ってください。
使用方法:
rdm-mailhandler.rb [options] --url=<Redmine URL> --key=<API key>
必須の引数:
-u, --url URL RedmineサーバのURL
-k, --key KEY Redmineの受信メール用のAPIキー
汎用オプション:
--key-file FILE APIキーを格納したファイルのフルパス
(コマンドライン引数にAPIを書きたくない場合、
--key 引数の代わりに使用してください)
--no-check-certificate サーバ証明書のチェックを行わない
--certificate-bundle FILE
使用する証明書ファイル
-h, --help ヘルプを表示
-v, --verbose 追加の情報を表示
-V, --version バージョン情報を表示して終了
ユーザーと権限のオプション:
--unknown-user ACTION 未登録のアドレスからのメールの処理方法
ACTIONに指定可能な値:
* ignore: メールを無視 (デフォルト)
* accept: 匿名ユーザーとして受け付ける
* create: ユーザーアカウントを作成
--no-permission-check 権限のチェックを行わない
--default-group GROUP 作成したユーザーのグループ (デフォルト: なし)
コンマ区切りで複数のグループを指定可能
--no-account-notice 新たに作成したユーザーに対してアカウント情報を
送信しない
--no-notification 新たに作成したユーザーに対してメール通知を
行わない
チケット属性の制御用オプション:
--project-from-subaddress ADDR
ADDRで指定されたアドレスがTo、Cc、Bccにあった
とき、サブアドレスを登録先のプロジェクトとして
扱う
-p, --project PROJECT 登録先のプロジェクトの識別子
-s, --status STATUS チケット登録時のステータス
-t, --tracker TRACKER チケット登録時のトラッカー
--category CATEGORY チケット登録時のカテゴリ
--priority PRIORITY チケット登録時の優先度
--assigned-to ASSIGNEE 担当者 (ユーザー名またはグループ名)
--fixed-version VERSION 対象バージョン
--private プライベートチケットを作成
-o, --allow-override ATTRS ATTRSで指定した属性をメール本文内で指定する
ことを許可。ATTRはコンマ区切りで指定するか、
'all'ですべての属性を許可することができる
--allow-override で指定できる属性の一覧は「チケットの属性」を参照してください。
例:
# プロジェクトの指定無し。メール本文内に'Project'キーワードが必須:
rdm-mailhandler.rb --url http://redmine.domain.foo --key secret
# プロジェクトは固定でトラッカーはデフォルト値が指定されているが、
# メール本文内ではトラッカー・優先度を指定可能:
rdm-mailhandler.rb --url https://domain.foo/redmine --key secret \\
--project foo \\
--tracker bug \\
--allow-override tracker,priority
以下にPostfixのaliasの例を示します:
foo: "|/path/to/rdm-mailhandler.rb --url http://redmine.domain --key secret --project foo"
この行はaliasesファイル（一般的には /etc/aliases）に記述します。もしaliasesファイルのパスが不明な場合は postconf alias_maps を実行して確認してください。aliasesファイルを更新したら、忘れずに newaliases を実行してPostfixに新しい設定を読み込ませてください。
もしPostfixのvirtual mailbox mapによるバーチャルドメインを使用している場合（/etc/postfix/virtual_mailbox_maps で user@example.com 宛メールをメールボックス /path/example.com/user に割り当てている場合）は以下のようにする必要があります:
etc/virtual内でマッピングを追加。 例:foo@example.org foo/etc/postfix/main.cf内でtransportの検索テーブルの指定を追加。 例:transport_maps = hash:/etc/postfix/transport- 追加したtransport検索テーブル内で設定を追加。 例:
foo@example.org local:
Explanation: - When you define virtual_mailbox_maps for a domain the default transport is virtual, which means specifying a local alias in @/etc/postfix/virtual@ will fail (with "unknown user"). To fix this, we override the default transport by specifying a local transport for the email address in question, which means the local alias will resolve correctly, and your script will be executed.
IMAPサーバからの取得
IMAPサーバからメールを取得するためにはrakeタスク(redmine:email:receive_imap)を使用します。cronからrakeコマンドを実行する際は、rakeコマンドのスイッチとして -f /path/to/redmine/appdir/Rakefile を指定してください。指定しなければrakefileが見つからずエラーとなります。以下は30分ごとにメールを取得するためのcronの記述の例です:
*/30 * * * * redmineuser rake -f /path/to/redmine/appdir/Rakefile redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=redmine@somenet.foo password=xxx
設定後、cronデーモンから毎回メールが届く場合は、--silentオプションを指定するとrakeコマンドの出力を抑制してください。これによりコマンドを実行するたびにメールが届くことはなくなるはずです。
*/30 * * * * redmineuser rake -f /path/to/redmine/appdir/Rakefile --silent redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=redmine@somenet.foo password=xxx
コマンドはcrontabに1行で記述してください。また、以下に示した、-fオプションおよびcron固有がないrakeコマンドの例も併せてご覧ください。
Windowsをサーバとして使用している場合は、メール取得のタスクをスケジュール実行するために pycron が利用できます。
環境によっては、スクリプトを実行するサーバ上のファイアウォールで外向けのTCP接続のポート143(IMAP)を開く必要があるかもしれません。
利用可能なIMAPオプション:
host=HOST IMAPサーバのホスト名 (デフォルト: 127.0.0.1)
port=PORT IMAPサーバのポート番号 (デフォルト: 143)
ssl=SSL SSLを使用するか? (デフォルト: false)
starttls=STARTTLS STARTTLSを使用するか? (デフォルト: false)
username=USERNAME IMAPアカウント
password=PASSWORD IMAPパスワード
folder=FOLDER 読み込むIMAPフォルダ (デフォルト: INBOX)
move_on_success=MAILBOX 読み込みに成功したときにメールを削除せずにMAILBOXへ
移動
move_on_failure=MAILBOX 読み飛ばされたメールをMAILBOXへ移動
ユーザーと権限のオプション:
unknown_user=ACTION 未登録のアドレスからのメールの処理方法
ACTIONに指定可能な値:
* ignore: メールを無視 (デフォルト)
* accept: 匿名ユーザーとして受け付ける
* create: ユーザーアカウントを作成
no_permission_check=1 権限のチェックを行わない
no_account_notice=1 新たに作成したユーザーに対してアカウント情報を
送信しない
default_group=foo,bar 作成したユーザーのグループ (デフォルト: なし)
コンマ区切りで複数のグループを指定可能
チケット属性の制御用オプション:
project=PROJECT 登録先のプロジェクトの識別子
project_from_subaddress=ADDR
ADDRで指定されたアドレスがTo、Cc、Bccにあった
とき、サブアドレスを登録先のプロジェクトとして
扱う
status=STATUS チケット登録時のステータス
tracker=TRACKER チケット登録時のトラッカー
category=CATEGORY チケット登録時のカテゴリ
priority=PRIORITY チケット登録時の優先度
assigned_to=ASSIGNEE 担当者 (ユーザー名またはグループ名)
fixed_version=VERSION 対象バージョン
private プライベートチケットを作成
allow_override=ATTRS ATTRSで指定した属性をメール本文内で指定する
ことを許可。ATTRはコンマ区切りで指定するか、
'all'ですべての属性を許可することができる
--allow-override で指定できる属性の一覧は「チケットの属性」を参照してください。
rakeコマンドの例:
# プロジェクトの指定無し。メール本文内に'Project'キーワードが必須:
rake redmine:email:receive_imap RAILS_ENV="production" \\
host=imap.foo.bar username=redmine@somenet.foo password=xxx
# プロジェクトは固定でトラッカーはデフォルト値が指定されているが、
# メール本文内ではトラッカー・優先度を指定可能:
rake redmine:email:receive_imap RAILS_ENV="production" \\
host=imap.foo.bar username=redmine@somenet.foo password=xxx ssl=1 \\
project=foo \\
tracker=bug \\
allow_override=tracker,priority
# 正常に処理されたメールをメールボックス'read'に移動し、読み飛ばされたメールを
# メールボックス'failed'に移動:
rake redmine:email:receive_imap RAILS_ENV="production" \\
host=imap.foo.bar username=redmine@somenet.foo password=xxx \\
move_on_success=read move_on_failure=failed
読み飛ばされたメールは既読になりますがサーバからは削除されません。読み飛ばされる理由としては、不明なユーザー(FromのアドレスがRedmineに登録されていないメールアドレス)、存在しないプロジェクトが指定された、FromのアドレスがRedmineの「送信元メールアドレス」であるなどが挙げられます。
allow_override オプションは、rakeの引数で指定したデフォルト値を上書きする場合だけではなく、メールの本文内で指定したいすべての属性について指定が必要です。例えば、メールの本文内でトラッカーを指定したい場合は引数で allow_override=tracker を指定する必要があります。
POP3サーバからの取得
IMAPサーバからメールを取得するためにはrakeタスク(redmine:email:receive_pop3)を使用します。
利用可能なPOP3オプション:
host=HOST POP3サーバのホスト名 (デフォルト: 127.0.0.1)
port=PORT POP3サーバのポート番号 (デフォルト: 110)
username=USERNAME POP3アカウント
password=PASSWORD POP3パスワード
apop=1 APOP認証を使用 (デフォルト: false)
delete_unprocessed=1 処理できず読み飛ばされたメールを削除
(デフォルトではサーバに残す)
チケット属性の制御用オプションについては前述の IMAPサーバからの取得 の説明をご覧ください。
標準入力からの取得
rakeタスク(redmine:email:receive_imap)を使用すると標準入力からメールのメッセージを読み込むことができます。
チケット属性の制御用オプションについては前述の IMAPサーバからの取得 の説明をご覧ください。
例:
# プロジェクトの指定無し。メール本文内に'Project'キーワードが必須:
rake redmine:email:read RAILS_ENV="production" < raw_email
# プロジェクトは固定でトラッカーはデフォルト値が指定されているが、
# メール本文内ではトラッカー・優先度を指定可能:
rake redmine:email:read RAILS_ENV="production" \\
project=foo \\
tracker=bug \\
allow_override=tracker,priority < raw_email
allow_override オプションは、rakeの引数で指定したデフォルト値を上書きする場合だけではなく、メールの本文内で指定したいすべての属性について指定が必要です。例えば、メールの本文内でトラッカーを指定したい場合は引数で allow_override=tracker を指定する必要があります。
未登録のユーザーからのメールによるチケット登録
未登録のユーザーからのメールを受信してチケットを作成することもできます。この機能を利用するためには、追加のパラメータを指定します:
unknown_user=ACTION 未登録のユーザーからのメールの処理方法。
ACTIONに指定可能な値:
ignore: メールを無視 (デフォルト)
accept: 送信者を匿名ユーザーとして扱ってメールを処理
create: 送信者のアカウントを作成してメールを処理
(ユーザー名とパスワードはユーザーにメールで送られる)
指定するオプションに対する適切な権限がRedmine上で必要です。例えば、 create を指定した場合、「非メンバー」ロールに対して「チケットの追加」権限を付与する必要があります。accept を指定した場合は「匿名ユーザー」に対して同様に権限の付与が必要です。
rakeタスクを使ってメールを取得する場合は unknown_user オプションは以下のように指定してください:
unknown_user=[ignore|accept|create]
no_permission_check オプションを指定することで権限のチェックを行わないようにすることもできます:
no_permission_check=1 disable permission checking when receiving the email
no_permission_check と unknown-user を併用することで非公開のプロジェクトに対して誰もがメールを遅れるようになります。例えば、以下の例のように設定すると、誰もがプロジェクト「foo」に対してメールを遅れます。
例:
rdm-mailhandler.rb --unknown-user accept --no-permission-check --project=foo
TODO: Is this true and is this related to the @no_permission_check@ option?:
Since Redmine 0.9 the project doesn't have to be public, but authentication required in the Administration-> Settings->Authentication tab has to be unchecked.
もし rdm-mailhandler によって新しいユーザーが作成されたときに送信されるアカウント作成通知メールが不要な場合、 --no-account-notice を使用してください（Redmine 2.3.0, "#11498":http://www.redmine.org/issues/11498 で実装）:
rdm-mailhandler.rb --unknown-user accept --no-permission-check --project=foo --no-account-notice
動作の仕組み
メールを受信すると、対応するRedmineのユーザーをメールのFromアドレスを使って検索します。不明なユーザーもしくはロックされたユーザーからのメールは無視されます。
メールの件名に "Re: [xxxxxxx #123]" または "[#123]" のような文字列が含まれていると、そのメールは返信として扱われ既存のチケット #123 に注記が追加されます。それ以外の場合は新しいチケットが作成されます。
チケットを作成するためには、すべての必須入力のカスタムフィールドの値がメール本文内で指定されている必要があります。不足しているものがあるとチケットの作成は失敗します。これを防ぐためには、すべてのカスタムフィールドがデフォルト値を持つように設定することが考えられます。
対象のプロジェクト
受信メールを処理する際、対象のプロジェクトは project オプションで指定します。
このオプションを指定しない場合、どのプロジェクトにチケットを追加すべきかメール本文内で指定する必要があります。これは、メール本文内に次のような行を記述することにより行います: "Project: foo".
例(メール本文):
プロジェクトfooに追加される新規のチケットです。
チケットの説明を記述します。
[...]
Project: foo
project オプションでデフォルトプロジェクトを指定した上で、 allow-override オプションによりプロジェクトの指定を上書きすることができます。
# デフォルトではプロジェクト"foo"にチケットを作成
rake redmine:email:receive_imap [...] project=foo allow_override=project
もちろん、メールを送信したユーザーがプロジェクト"foo"にチケットを登録する権限がない場合はそのメールは無視されます。 対象のプロジェクトが、 必須 と指定されかつデフォルト値がないカスタムフィールドを使用している場合、チケットの登録は失敗します。注意してください。
チケットの属性
メール受信の設定で使用したオプションにより( allow-override オプションを参照)、チケットをメール送信する際にいくつかの属性を指定することができます。
これは、メールの本文内で下記のキーワードを使用することにより行うことができます(Project と同様): Tracker, Category, Priority, Status.
例(メール本文):
This is a new ticket that overrides a few attributes
[...]
Project: foo
Tracker: Bug
Priority: Urgent
Status: Resolved
ウォッチャー
メールを送信したユーザーが'Add issue watchers'権限を持っている場合、メールのToまたはCcフィールドに入っているユーザーは新しく作成されたチケットのウォッチャーとして自動的に登録されます。
メールの形式と添付ファイル
Redmineはメール内のPlain Textの部分をチケットの説明として利用します。 HTMLのみのメールを受信した場合、HTMLタグを除去します。
メールに添付されたファイルは、ファイルの大きさが「管理」→「設定」→「添付ファイルの最大サイズ」を超えない限り、自動的にチケットに添付されます。