How To Create Mailing Lists

One of the frequent questions on the James-User Mailing List is how to create a mailing list. This document explains one way of using the currently supplied Matchers and Mailets in James v2.3.

Basically, the process requires creating two <mailet> entries and a repository. The first mailet handles list commands (currently only list-name-on and list-name-off). The second mailet handles list messages. The repository will hold the e-mail addresses of list subscribers.

The mailets go into the processor chain (e.g., at the top of the transport processor), the repository goes into the <users-store> block.

Setting up the Mailets

You need to setup two mailets.

The first mailet that you need to setup is an instance of the Avalon Listserv Manager mailet. This will handle subscribing and unsubscribing. [Note: the current code does not support confirmed opt-in, just basic commands.] The CommandForListserv matcher is used to invoke match messages containing commands for the mailing list.

The second mailet is an instance of the Avalon Listserv mailet. That mailet actually receives messages for the list and causes them to be distributed. The RecipientIs matcher is used to match messages intended for the mailing list.

The following illustrates the two <mailet> elements that need to be added:

  <mailet match="CommandForListserv=list-name@domain"
          class="AvalonListservManager">
    <repositoryName>list-name</repositoryName>
  </mailet>

  <mailet match="RecipientIs=list-name@domain" class="AvalonListserv">
    <repositoryName>list-name</repositoryName>
    ... list options ...
  </mailet>

Setting up the Repository

The mailing list mailets need a repository within which to store the subscriber list. There is a separate repository for each mailing list, and is completely independent of the user repository used by James to manage e-mail accounts. This is configured in the <users-store> block of config.xml.

The following illustrates a database-backed repository using JDBC with the ListUsersJdbcRepository class. Notice that there will be a single table, lists, created in the db://maildb resource defined elsewhere. There are currently two columns: the list name and the list subscriber.

  <repository name="list-name"
                 class="org.apache.james.userrepository.ListUsersJdbcRepository"
                 destinationURL="db://maildb/lists/list-name">
    <sqlFile>file://conf/sqlResources.xml</sqlFile>
  </repository>

The following illustrates a file-system repository using the UsersFileRepository class. [Note: the destination URL is a child element when configuring a file-system repository, and an attribute when configuring a database-backed repository. This inconsistency will be addressed in a future version of James.]

  <repository name="list-name"
                 class="org.apache.james.userrepository.UsersFileRepository">
    <destination URL="file://var/lists/list-name/" /> 
  </repository>