<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" xml:lang="en" xml:id="services.mail.config"><info><title>mail service configuration</title></info>
  

  <para>The <emphasis role="bold">mail</emphasis> service is an optional
  service that may be used to send emails.</para>

  <para>It is based on JavaMail and on JavaBeans Activation Framework (JAF)
  API.The default implementation of the <emphasis role="bold">mail</emphasis>
  service rely on the GNUMail implementation of these API.</para>

  <para>A mail factory is required in order to send or receive mails. JOnAS
  provides two types of mail factories:
  <classname>javax.mail.Session</classname> and
  <classname>javax.mail.internet.MimePartDataSource</classname>.
  <classname>MimePartDataSource</classname> factories allow mail to be sent
  with a subject and the recipients already set.</para>

  <para>Mail factory objects must be configured according to their type. The
  subsections that follow briefly describe how to configure
  <classname>Session</classname> and <classname>MimePartDataSource</classname>
  mail factory objects, in order to run the SessionMailer SessionBean and the
  MimePartDSMailer SessionBean delivered with the platform.</para>

  <para>Here is the part of <filename>jonas.properties</filename> concerning
  the <emphasis role="bold">mail</emphasis> service:</para>

  <screen>###################### JOnAS Mail service configuration
#
#  Set the name of the implementation class of the mail service
jonas.service.mail.class org.ow2.jonas.mail.internal.JOnASMailService

#  Set the jonas mail factories.
#  This property is set with a coma-separated list of MailFactory properties
#  file names (without the '.properties' suffix).
#  Ex: MailSession1,MailMimePartDS1 (while the properties file names are
#                  MailSession1.properties and MailMimePartDS1.properties)
jonas.service.mail.factories</screen>

  <para>Mail factory objects created by <xi:include href="../../variables.xml" xpointer="appserver"/> must be
  given a name. For example, consider two factories called
  <literal>MailSession1</literal> and <literal>MailMimePartDS1</literal>. Each
  factory must have a configuration file whose name is the name of the factory
  with the <filename class="extension">.properties</filename> extension
  (<filename>MailSession1.properties </filename>for the MailSession1
  factory).</para>

  <para>For this example jonas.service.mail.factories property must be set
  to:</para>

  <screen>jonas.service.mail.factories MailSession1,MailMimePartDS1</screen>

  <section><info><title>Configuring Session mail factory</title></info>
    

    <para>A template <filename>MailSession1.properties</filename> file is
    supplied in <filename class="directory">$JONAS_BASE/conf.</filename> It
    contains two mandatory properties :</para>

    <screen>#Factory Name/Type
mail.factory.name mailSession_1
mail.factory.type javax.mail.Session</screen>

    <para>The JNDI name of the mail factory object is mailSession_1. This
    template must be updated with values appropriate to your installation. See
    the section "Configuring a mail factory" below for the list of available
    properties.</para>
  </section>

  <section><info><title>Configuring MimePartDataSource mail factory</title></info>
    

    <para>A template <filename>MimePartDS1.properties</filename> is supplied
    in <filename class="directory">$JONAS_BASE/conf</filename>. It contains
    two mandatory properties :</para>

    <screen>#Factory Name/Type
mail.factory.name mailMimePartDS_1
mail.factory.type javax.mail.internet.MimePartDataSource
</screen>

    <para>The JNDI name of the mail factory object is mailMimePartDS_1. This
    template must be updated with values appropriate to your installation. See
    the section "Configuring a mail factory" below for the list of available
    properties.</para>
  </section>

  <section><info><title>Configuring a mail factory</title></info>
    

    <para>Here are the possible properties</para>

    <itemizedlist>
      <listitem>
        <para>Required properties:</para>
      </listitem>
    </itemizedlist>

    <informaltable>
      <tgroup cols="2">
        <tbody>
          <row>
            <entry align="center">Property name</entry>

            <entry align="center">Description</entry>
          </row>

          <row>
            <entry><property>mail.factory.name</property></entry>

            <entry>JNDI name of the mail factory</entry>
          </row>

          <row>
            <entry><property>mail.factory.type</property></entry>

            <entry>The type of the factory. This property can be
            javax.mail.Session or
            javax.mail.internet.MimePartDataSource.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <itemizedlist>
      <listitem>
        <para>Optional properties: Authentication properties</para>
      </listitem>
    </itemizedlist>

    <informaltable>
      <tgroup cols="2">
        <tbody>
          <row>
            <entry align="center">Property name</entry>

            <entry align="center">Description</entry>
          </row>

          <row>
            <entry><property>mail.authentication.username</property></entry>

            <entry>Set the username for the authentication.</entry>
          </row>

          <row>
            <entry><property>mail.authentication.password</property></entry>

            <entry>Set the password for the authentication.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <itemizedlist>
      <listitem>
        <para>Optional properties: javax.mail.Session.properties (refer to
        JavaMail documentation for more information)</para>
      </listitem>
    </itemizedlist>

    <informaltable>
      <tgroup cols="2">
        <tbody>
          <row>
            <entry align="center">Property name</entry>

            <entry align="center">Description</entry>
          </row>

          <row>
            <entry><property>mail.debug</property></entry>

            <entry>The initial debug mode. Default is false.</entry>
          </row>

          <row>
            <entry><property>mail.from</property></entry>

            <entry>The return email address of the current user, used by the
            InternetAddress method getLocalAddress.</entry>
          </row>

          <row>
            <entry><property>mail.mime.address.strict</property></entry>

            <entry>The MimeMessage class uses the InternetAddress method
            parseHeader to parse headers in messages. This property controls
            the strict flag passed to the parseHeader method. The default is
            true.</entry>
          </row>

          <row>
            <entry><property>mail.host</property></entry>

            <entry>The default host name of the mail server for both Stores
            and Transports. Used if the mail.protocol.host property is not
            set.</entry>
          </row>

          <row>
            <entry><property>mail.store.protocol</property></entry>

            <entry>Specifies the default message access protocol. The Session
            method getStore() returns a Store object that implements this
            protocol. By default the first Store provider in the configuration
            files is returned.</entry>
          </row>

          <row>
            <entry><property>mail.transport.protocol</property></entry>

            <entry>Specifies the default message access protocol. The Session
            method getTransport() returns a Transport object that implements
            this protocol. By default, the first Transport provider in the
            configuration files is returned.</entry>
          </row>

          <row>
            <entry><property>mail.user</property></entry>

            <entry>The default user name to use when connecting to the mail
            server. Used if the mail.protocol.user property is not
            set.</entry>
          </row>

          <row>
            <entry><property>mail.&lt;protocol&gt;.class</property></entry>

            <entry>Specifies the fully- qualified class name of the provider
            for the specified protocol. Used in cases where more than one
            provider for a given protocol exists; this property can be used to
            specify which provider to use by default. The provider must still
            be listed in a configuration file.</entry>
          </row>

          <row>
            <entry><property>mail.&lt;protocol&gt;.host</property></entry>

            <entry>The host name of the mail server for the specified
            protocol. Overrides the mail.host property.</entry>
          </row>

          <row>
            <entry><property>mail.&lt;protocol&gt;.port</property></entry>

            <entry>The port number of the mail server for the specified
            protocol. If not specified, the protocol's default port number is
            used.</entry>
          </row>

          <row>
            <entry><property>mail.&lt;protocol&gt;.user</property></entry>

            <entry>The user name to use when connecting to mail servers using
            the specified protocol. Overrides the mail.user property.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <itemizedlist>
      <listitem>
        <para>Optional properties:MimePartDataSource properties (Only used if
        mail.factory.type is javax.mail.internet.MimePartDataSource)</para>
      </listitem>
    </itemizedlist>

    <informaltable>
      <tgroup cols="2">
        <tbody>
          <row>
            <entry align="center">Property name</entry>

            <entry align="center">Description</entry>
          </row>

          <row>
            <entry><property>mail.to</property></entry>

            <entry>Set the list of primary recipients ("to") of the
            message.</entry>
          </row>

          <row>
            <entry><property>mail.cc</property></entry>

            <entry>Set the list of Carbon Copy recipients ("cc") of the
            message. mail.bcc</entry>
          </row>

          <row>
            <entry><property>mail.bcc</property></entry>

            <entry>Set the list of Blind Carbon Copy recipients ("bcc") of the
            message.</entry>
          </row>

          <row>
            <entry><property>mail.subject</property></entry>

            <entry>Set the subject of the message.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>
</section>