RSS Feeds
*********


About RSS Feeds
===============

Use the RSS module to allow read-only access to some mailboxes over
RSS.

An authenticated user can see the list of available mailboxes at the
*/rss/* URL on the Cyrus server. The mailbox list for RSS is limited
to only the mailboxes the RSS module has been configured to expose
**and** the mailboxes the authenticated user has permission to see,
according to the normal mailbox ACLs.


Configuration
=============


List of mailboxes: rss_feeds
----------------------------


rss_feeds
^^^^^^^^^

   *This shows the default value: change it in imapd.conf to suit your
   needs.*

   "rss_feeds:" *

      A wildmat pattern specifying which mailbox hierarchies should be
      treated as RSS feeds.  Only mailboxes matching the wildmat will
      have their messages available via RSS.  If not set, a default
      wildmat of "*" (ALL mailboxes) will be used.

The list of available RSS feeds can be obtained by clients by
accessing the "/rss/" URL on the Cyrus server.

The rss_feeds option uses the "wildmat" (**RFC 3977#section-4**)
format to specify which mailboxes/folders will be made available via
RSS. This list is further limited to only those mailboxes and folders
that the authenticated user has permissions to see.

The rss_feeds option uses the internal namespace, which uses "." as a
hierarchy separator, regardless of what "unixhierarchysep" is set to.

Examples:

* "user.bob" - will serve only user "Bob"'s inbox.

* "rss.*" - will serve all folders under the shared mailbox called
  "rss".

* "rss*" - will serve all content under mailboxes that start with
  "rss": rss-cool and rss-important will be included, for example.

* "*,!user" - will serve all shared mailboxes, but no personal
  mailboxes.

* "*" - will serve all shared and personal mailboxes.


Display of mailbox list: rss_feedlist_template
----------------------------------------------


rss_feedlist_template
^^^^^^^^^^^^^^^^^^^^^

   *This shows the default value: change it in imapd.conf to suit your
   needs.*

   "rss_feedlist_template:" <none>

      File containing HTML that will be used as a template for
      displaying the list of available RSS feeds.  A single instance
      of the variable %RSS_FEEDLIST% should appear in the file, which
      will be replaced by a nested unordered list of feeds.  The
      toplevel unordered list will be tagged with an id of "feed" (<ul
      id='feed'>) which can be used by stylesheet(s) in your template.
      The dynamically created list of feeds based on the HTML template
      will be accessible at the "/rss" URL on the server.

By default, the server will present the list as a simple unordered
list in an HTML document. To customize the look and feel of the feed
list, the "rss_feedlist_template" option can be used to point to a
HTML template file. This file can use Cascading Style Sheets,
JavaScript, etc. All content that the template uses **must** reside
under the "httpdocroot". Consult imapd.conf(5) for specifics on the
required contents of this custom file.

Note that for sites running Cyrus Murder, "rss_feedlist_template" only
needs to be set on frontend servers, since only those servers have the
complete mailbox list.