Integrating James to dotCMS

Integrating James to dotCMS

Overview and Configuration

The listserv for dotCMS can be based on the James project:

which is a fully functional mail server written entirely in Java. It provides mail retrieval, delivery as well as configuration components. It can be extended with a number of Java classes specific to the client needs.

The James listserv can be located on the same server as the dotCMS application.

It can be stopped and started using the init script, like most other linux services:

/etc/init.d/james start|stop
post image

The configuration files relevant to the basic listserv functionality are as follows:


The latter is a config only for users repositories and is included in the former which is a general configuration file for the application.

Communication with the dotCMS Application

The James server can communicate with the dotCMS application for:

  • obtaining Listservs, Subscribers and their permissions
  • storing email messages as Subscribers Area Updates (on front-end if required)

The communication runs over the HTTP protocol with simple HTTP Services exposed by the dotCMS application. These are essentially servlets producing plain text responses to the James server. The servlets are restricted with the list of IP addresses they can be accessed from - this is done by setting the param "allowFrom" in the servlets configurations in the dotCMS plugin configuration file:


which on deployment is merged with the well known web application config file:


By default the servlets are restricted to only be accessible on the local loopback interface and since the dotCMS application and the James server run on the same host, they are not exposed to the outside world.

Handling Listserv Emails in James

Whenever an incoming email is detected to be addressed to the address at the local host as defined in the config.xml or the recipient address is listserv@client.domain, it is picked up for processing by a Mailet.

Incoming emails, which are not detected as either of these two types are simply ignored and discarded.

The Mailets perform the following sequence of operations:

  1. get Listservs, subscribers and their permissions via the relevant HTTP service
  2. verify if the sender has the permissions to write to the Listservs
  3. if the sender has the permissions, distribute the message to subscribers
  4. send the message to the mail store service for storage in the updates database (accessible via frong page) - only applies to the normal Listserv emails and broadcast messages.

Getting Listservs, Subscribers and permissions

For getting the mailing lists aka Listservs, the Subscribers of the Listservs and their permissions the Mailet retrieves data via HTTP servlet.
Users repositories are databases of users who are allowed to use the listserv. James communicates via HTTP servlet.
The response from the servlet is translated to plain Java objects, which contain the Listserv data (name, address etc.) as well as the list of subscribed Subscribers with permissions. Subscribers are also Java objects of some class.

Verifying Sender's permissions

The sender is verified against the subscribers list and permissions obtained in the previous step. This is done for each Listserv the email is being sent to.

The email is bounced back with a relevant error message if:

  • the sender's address is not in the list, which means that the user is not subscribed to the Listserv
  • the sender is in the list but only has permissions to read the messages from the Listserv
  • the user is trying to initiate a new thread in the Listserv but only has permission to reply to existing threads

Otherwise the email is further processed and distributed.

Distributing Email Messages

After checking sender's permissions and obtaining the list of recipents the Mailer prepares the Listserv message for sending and distributes it to the recipients.

Preparing the message involves removing certain RFC2822 mail headers and prepending the Listserv name to the original mail subject.

James handles message sending. Its mechanism is triggered with the specialized Java classes called mailets.

The mail is then processed by a mail repository class for storing it in the Subscribers Area Updates (for front-end update notifications if required).

Broadcast Messages

Broadcasts are a special type of messages sent to several Listservs at once which means:

  • subscribers of those lists will only receive one copy of the email regardless of how many lists they are subscribed to
  • the original sender's address is kept while the real addresses of lists it was sent to is concealed with the address "broadcast@client.domain" to make replies impossible
  • a footer is appended to the original email body stating which mailing lists the email was sent to

To broadcast an email, its subcject has to be prefixed with "Broadcast -" string.

The prefix will be stripped off in the email that is distributed to the subscribers.

Broadcast messages are handled by Mailet class. Instead of being sent to each Listserv separately, a set of recipients is collected from all Listservs from the original mail recipients list (TO: field) the sender has permissions to write to and at the end of processing the Listservs one message is sent to all these recipients.

Post on