Elephant uses a mail queue system to allow modules to send notifications, status information and publications. Each user can configure whether to receive messages from specific categories and, when available, in which period.

Module senders and user configurations

Periods

The API treats the don't want to receive these emails as a especial period, in order to remind when a user explicitly set this option. Also, categories define which periods are allowed and the default period to use when not specified. The periods are:

User wants vs. user may want

The notifiers behavior may vary when the user hasn't specifically set a period option. User will be treated as a Participant (may want) or as an Observer (wants), depending on how module qualifies it. The following table shows how operates:

Similar behavior applies to user's agreements. See Agreements .

To better understand the differences, lets take two examples: issue tracking and publications.

Issue tracking

Issues depend on users participation, a role sharing type of share. We know a user may want to know when an issue changes state, if he participates in this issue. The default notifier action will be try to send the notification. If the user hasn't specifically set a period option, the default category option will be used.

Publications

Publications are sent to subscribers. The notifier will send the publication to those users whom specifically have set a period option.

Mail queue tasks

The Elephant Mail Queue API requires a task to be created for each existent period. These tasks are configured by default. The idea behind is to permit platform administrators to change things like the hour in which daily summaries are sent, the day for monthly summaries, and so forth.

Mail macros

Images

Images aren't included in emails. Instead, images are links to the site. This means that the email client is responsible of reading them in order to be shown. Some god practices when uploading images are:

• Do not use punctuation symbols. Due differences among site encoding, mail clients and web mail clients, some symbols may appear translated and site would not be allowed to read them.
• Do not use spaces. It shouldn't be a problem, but it is with some mail clients. Even worst if you think newer versions may broke previous good behavior.
• Remember, the only characters that wont get translated are simple a to z, A to Z, . (point), - (hyphen), _ (underline) and 0 to 9. (Notice that ç, Ç, ñ and Ñ are not in these ranges)

Links

The recommendation for images with live links (auto-authenticated links) is:

[link({liveref:live-link})]
[img image-to-show]
[/link]

System notification queue

System queue is used to send admin notifications to site administradors, password reminders to users and more of the kind. The system queue is private, users can't change sending period. The logic used when sending is the User may want approach, which means that users will receive notifications except when explicitly set to DONT_SEND. Although administradors can set periods for this queue, it's not recommended. System notifications are better sent AS_GENERATED.

Elephant allows sending direct emails through the Mail API. This method is used, for instance, when sending activity emails from BrightSide Dossiers module.

Intercepting responses to direct emails

The Elephant Mail API defines a way for intercepting responses to direct emails. The method requires to declare a MailReader. The usual form to declare a MailReader is in the elephant_[module].xml file.

Processed messages will be flagged as configured in MailReader. The rest will be left as they were.

The xml element for MailReader

The xml element for MailReaders is a <impl interface java-class/> using org.turro.mail.reader.MailReader. The attributes are:

Example for IMAP protocol on Gmail

<impl interface="IMailReader_Dossier" java-class="org.turro.mail.reader.MailReader">
  <attrib name="mailhost" value="imap.gmail.com"/>
  <attrib name="type" value="imaps"/>
  <attrib name="count" value="10"/>
  <attrib name="user" value="user@gmail.com"/>
  <attrib name="cryptpass" value="xxxxxxx"/>
  <attrib name="port" value="993"/>
  <attrib name="ssl" value="true"/>
  <attrib name="tls" value="false"/>
</impl>

Example for POP3 protocol on Gmail

<impl interface="IMailReader_Dossier" java-class="org.turro.mail.reader.MailReader">
  <attrib name="mailhost" value="pop.gmail.com"/>
  <attrib name="type" value="pop3s"/>
  <attrib name="count" value="10"/>
  <attrib name="user" value="user@gmail.com"/>
  <attrib name="cryptpass" value="xxxxxxx"/>
  <attrib name="port" value="995"/>
  <attrib name="ssl" value="true"/>
  <attrib name="tls" value="false"/>
</impl>