Configuration

Role Configuration

  <role
    name="org.apache.fulcrum.commonsemail.CommonsEmailService"
    shorthand="CommonsEmailService"
    default-class="org.apache.fulcrum.commonsemail.impl.CommonsEmailServiceImpl"
    early-init="true"
    description="Simplifies the usage of commons-email"
  />

Component Configuration

Item Datatype Cardinality Description
defaultDomain String [0|1] The default domain to use if the caller-supplied domain name was not found
domains Complex [1] Contains a list of domains
domains\domain Complex [1..n] Represents a single domain
domains\domain\domainName String [1] The name of the domain.
domains\domain\domainMatch String [0|1] This field is used to match a given argument to a domain. If no value is supplied than the 'domainName' is used
domains\domain\mailSmtpHost String [0|1] The SMTP host being used for creating the underlying mail session. If no value is supplied than the SystemProperty 'mail.smtp.host' is used.
domains\domain\mailSmtpPort Integer [0|1] The SMTP port being used for creating the underlying mail session.
domains\domain\mailSmtpConnectionTimeout Integer [0|1] The socket connection timeout value in milliseconds. This settings is only applicable for javamail-1.3.3 or higer.
domains\domain\mailSmtpTimeout Integer [0|1] The socket I/O timeout value in milliseconds. This settings is only applicable for javamail-1.3.3 or higer.
domains\domain\mailFromEmail String [0|1] The email address of the email sender
domains\domain\mailFromName String [0|1] The name of the email sender. This setting is ignored if no 'mailFromEmail' is defined.
domains\domain\mailReplyToEmail String [0|1] The email address of the email reply address
domains\domain\mailReplyToName String [0|1] The name of the email reply address. This setting is ignored if no 'mailReplyToEmail' is defined.
domains\domain\mailBounceAddress String [0|1] The bounce address being used by the SMTP server.
domains\domain\mailDebug Boolean [0|1] Setting the 'mail.debug' property for the underlying mail session. If it is not set the default value 'false' is used.
domains\domain\mailDump Boolean [0|1] Shall we dump the generated MimeMessage before sending it? If it is not set the default value 'false' is used.
domains\domain\mailDoNotSend Boolean [0|1] Skip sending of the MimeMessage?
domains\domain\authentication Complex [0|1] Contains the authentication related stuff
domains\domain\authentication\type String [0|1] The type of authentication being used [smtpauth|popbeforesmtp|none]
domains\domain\authentication\popHost String [0|1] The POP server for 'popbeforesmtp'. This setting is only useful in combination with 'popbeforesmtp'. If no value is supplied the default value is 'mailSmtpHost'
domains\domain\authentication\username String [0|1] The username for the authentication
domains\domain\authentication\password String [0|1] The password for the authentication
domains\domain\headers Complex [0|1] The list of email headers entries
domains\domain\headers\property@name String [1] The name of the email header
domains\domain\headers\property String [1] The value of the email header
domains\domain\overwrites Complex [0|1] Contains the email addresses of the enforced recipients
domains\domain\overwrites\mailToEmail String [0|1] Contains the enforced TO address
domains\domain\overwrites\mailCcEmail String [0|1] Contains the enforced CC address
domains\domain\overwrites\mailBccEmail String [0|1] Contains the enforced BCC address
domains\domain\overwrites\mailBccEmail String [0|1] Contains the enforced BCC address
domains\domain\hooks Complex [0|1] Contains the configuration for the application hooks
domains\domain\hooks\onSuccess@enable Boolean [0|1] Is the hook for a sucscessfully send email enabled?
domains\domain\hooks\onFailure@enable Boolean [0|1] Is the hook for an undeliverd email enabled?
domains\domain\hooks\onNotSend@enable Boolean [0|1] Is the hook for an unsent email enabled?

Component Configuration Example 1

This is a minimal domain configuration - here we use a SMTP server on localhost:6025 using SMTP authenication. Since we defined a default domain all mails will use the same configuration. 

  <CommonsEmailService>
    <defaultDomain>it20one.at</defaultDomain>
    <domains>
      <domain>
        <domainName>it20one.at</domainName>
        <mailSmtpHost>localhost</mailSmtpHost>
        <mailSmtpPort>6025</mailSmtpPort>
        <authentication>
          <type>smtpauth</type>
          <username>demo</username>
          <password>demo</password>
        </authentication>
      </domain>
    </domains>
  </CommonsEmailService>

Component Configuration Example 2

This is a full blown example. We define a domain 'test' using the SMTP server on localhost:6025 using SMTP auhtentication. We also define the 'from' and 'replyTo' since it can be overwritten by the application. Furthermore all mail recipients are overwritten to ensure that the emails are delivered to a test account. 

  <CommonsEmailService>
    <defaultDomain>test</defaultDomain>
    <domains>
      <domain>
        <domainName>test</domainName>
        <domainMatch>test</domainMatch>
        <mailSmtpHost>localhost</mailSmtpHost>
        <mailSmtpPort>6025</mailSmtpPort>
        <mailFromEmail>demo@it20one.at</mailFromEmail>
        <mailFromName>E-Billing Test</mailFromName>
        <mailReplyToEmail>demo@it20one.at</mailReplyToEmail>
        <mailReplyToName>E-Billing Test</mailReplyToName>
        <mailBounceAddress>error@it20one.at</mailBounceAddress>
        <mailDebug>false</mailDebug>
        <mailDump>true</mailDump>
        <mailDoNotSend>false</mailDoNotSend>
        <authentication>
          <type>smtpauth</type>
          <username>demo</username>
          <password>demo</password>
        </authentication>
        <headers>
          <property name="X-Mailer">Sendmail</property>
          <property name="X-Priority">1</property>
          <property name="Disposition-Notification-To">demo@it20one.at</property>
        </headers>
        <overwrites>
          <mailToEmail>demo@it20one.at</mailToEmail>
          <mailCcEmail>demo@it20one.at</mailCcEmail>
          <mailBccEmail>archive@it20one.at</mailBccEmail>
        </overwrites>
      </domain>
    </domains>
  </CommonsEmailService>