[[PageOutline(2-5,Contents,pullout)]]

= Email archive for storing emails in Trac

== Description

This plugin allows you to browse and view archived emails and email attachments. It adds a new item '''Mail Archive''' to the main menu:

[[Image(MailArchiveList.png, border=2)]]

When clicking on an item in the mail archive, the contents can be viewed:

[[Image(MailArchiveExample.png, border=2)]]

Key features:
* Import emails to Trac's database from an IMAP account.
* Search emails with Trac Search.
* Link to emails or attachments with `mailarchive:` wiki links, or `mail:`, `email:`, and `emailarchive:` synonyms.
* List relevant emails in wiki pages with the `[[MailQuery(searchterm)]]` macro.
* New Trac permission `MAIL_ARCHIVE_VIEW`.
* New Trac admin command `trac-admin mailarchive fetch`.

For example, you can schedule a task to call the following command every 15 minutes:
{{{#!sh
$ trac-admin path/to/trac/environment mailarchive fetch imap.example.com trac-archive@example.com password123
}}}

Make sure that the emails to be archived are marked as unread or from today, as only such emails will be archived.

=== Known Problems

* A reset of uids on the IMAP server could lead to problems, eg duplicate / unarchived emails (#11535).

=== Similar Plugins
* [https://ja.osdn.net/projects/shibuya-trac/wiki/plugins/MailArchivePlugin Shibuya.trac MailArchivePlugin]
* [https://ja.osdn.net/projects/shibuya-trac/wiki/plugins/MailArchiveExtPlugin Shibuya.trac MailArchiveExtPlugin]

== !Bugs/Feature Requests

Existing bugs and feature requests for MailArchivePlugin are 
[report:9?COMPONENT=MailArchivePlugin here].

If you have any issues, create a 
[/newticket?component=MailArchivePlugin new ticket].

[[TicketQuery(component=MailArchivePlugin,group=type,format=progress)]]

== Download

Download the zipped source from [export:mailarchiveplugin here].

== Source

You can check out MailArchivePlugin from [/svn/mailarchiveplugin here] using Subversion, or [source:mailarchiveplugin browse the source] with Trac.

== Installation

Installation of the plugin requires the usual step:
* Trac 1.4: `easy_install https://trac-hacks.org/svn/mailarchiveplugin/trunk`
* Trac 1.2: `easy_install https://trac-hacks.org/svn/mailarchiveplugin/tags/mailarchive-1.1`.
* Trac 1.0: `easy_install https://trac-hacks.org/svn/mailarchiveplugin/tags/mailarchive-1.0`.

Then enable the plugin in Trac's plugin admin page or in your `trac.ini` file:
{{{#!ini
[components]
mailarchive.* = enabled
}}}

A database upgrade will be required as usual: 
{{{#!sh
$ trac-admin path/to/trac/environment upgrade
}}}

== Configuration

Assign the new `MAIL_ARCHIVE_VIEW` permission to the appropriate Trac groups / users, eg in Trac's permission admin page.

Additionally you need an email IMAP account that only contains all the emails you want to archive. If you don't already have this, you could create a new separate email account (e.g. `trac-archive@example.com`) and copy all emails you want to appear in Trac's mail archive to that account.

Actually archiving the emails from that IMAP account into Trac's database must be done separately using a new `trac-admin mailarchive fetch <host> <username> <password>` command. You should configure it to be periodically called, for example by using a cron job in Unix or using a scheduled task in Windows. Replace `<host>`, `<username>` and `<password>` with your email host, username and password.

== Recent Changes

[[ChangeLog(mailarchiveplugin, 3)]]

== !Author/Contributors

'''Author:''' [wiki:lucid] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''