apache > cocoon

- Home

# Sendmail Action

## Description

The Sendmail action is an action which makes the capability of sending an email message available to the sitemap. This includes attaching binary files which come either from another Cocoon pipeline or from HTML file uploads. The Sendmail action make the primary methods of the Java Mail API available to the sitemap.

The Sendmail action is an alternative to the Sendmail logicsheet.

## Usage

Before the Sendmail action can be used, it must be activated - either in Cocoon's main sitemap, or in a subsitemap which is used for your application. Include the following `map:action` element as child respectively grandchild of the `map:components` -> `map:actions` elements.

    <map:components>
      <map:actions>
         <map:action name="sendmail" logger="sitemap.action.sendmail"
                      src="org.apache.cocoon.acting.Sendmail"/>
      </map:actions>
    </map:components>

## Example Code

This example uses a simple HTML form which provides entry fields for `subject`, `cc`, `uploaded_file1` and the email `body`.

    <form action="/cocoon/mail/send-a-mail"
          method="POST"
         enctype="multipart/form-data">
      <input type="text" name="subject" size="56" />
      <input type="text" name="cc" size="56" />
      <input type="file" name="uploaded_file1" size="56" />
      <textarea name="body" rows="5" cols="72">
      </textarea>
    </form>

Please keep in mind that it is important to use `enctype="multipart/form-data"` if you want to upload files which should be attached to an email message.

The posted HTTP request data is processed by this sitemap fragment.

    <map:match pattern="mail/*">
      <map:act type="sendmail">
        <!-- To override defaults specified in cocoon.xconf:
        <map:parameter name="smtp-host" value="localhost"/>
        <map:parameter name="smtp-user" value="john"/>
        <map:parameter name="smtp-password" value="john"/>
        -->
        <map:parameter name="from" value="cocoon@localhost"/>
        <map:parameter name="to" value="mailinglist@somewhere.com"/>
        <map:parameter name="subject" value="{request-param:subject}"/>
        <map:parameter name="body" value="{request-param:body}"/>
        <map:parameter name="cc" value="{request-param:cc}"/>
        <map:parameter name="bcc" value="censor@somewhere.com"/>
        <map:parameter name="attachments"
                       value="uploaded_file1 context://welcome.xml"/>
        <map:generate src="mail/{status}.xml"/>
        <map:serialize type="xml"/>
      </map:act>
    </map:match>

The input modules are used to supply some of the input parameters for the Sendmail action. In this example, apart from the `uploaded_file1` request parameter, a second file is attached to the email message, using the Cocoon protocol notation (the file `welcome.xml` from the Cocoon context directory). The result of sending the email message is passed back into the sitemap through the `status` parameter and is used to provide the user with a feedback. (The transformation is left as an exercise to the reader).

Please consider the security implications if you let a user specify an email address in an input form. A malicious user might abuse this to send SPAM emails. So, this example is probably only useful in an intranet application, where users can mostly be considered well behaved.

## Input/Output Parameter Reference

The following is the list of parameters which can be passed from the sitemap into the Sendmail action.

Name: | Required? | Description:
--- | --- | ---
smtp-host | no | The IP address or the name of the host, which should deliver the email message. Better known as the mail transfer agent or short MTA.
smtp-user | no | User name
smtp-password | no | Password
to | yes | Sets the destination/to address of the email message. This can be a list of comma separated email addresses.
cc | no | Sets the recipients of a carbon copy of this email. This can be a list of comma separated email addresses.
bcc | no | Sets the recipients of a black carbon copy of the email. This can be a list of comma separated email addresses.
from | yes | Sets the from address of the message.
subject | no | Sets the subject line of the message.
body | no | Sets the body text of the message. This parameter is ignored if the `src` parameter is specified.
src | no | A url specifying the source of the text body of the email. If `src` is specified, the `body` parameter is ignored.
srcMimeType | no | The optional mime type of the source of the text body of the email if you specified `src`.
charset | no | Sets the character set for encoding the message. This tag has only an effect if no attachments are send.
attachment | no | Sets the attachment for this email. This is a blank separated list. If an argument contains a ":", it is assumed that a Cocoon internal protocol is specified (ex: `context://welcome.xml`). This means that the attachment comes from a Cocoon pipeline (internally an `org.apache.excalibur.source.Source` object). If the argument does not contain a colon, the argument names a request parameter which is a file upload through a HTML form (internally an `org.apache.cocoon.components.request.multipart.FilePart` object).

The following is the list of parameters which are passed from Sendmail action back into the sitemap.

Name: | Description:
--- | ---
status | This parameter can take three values: `success`, `user-error` and `server-error`. `success` means that the email message has been successfully delivered to the mail transfer host. `user-error` means that there was a problem with at least one of the specified email addresses (to, cc, bcc or from). `server-error` means that there was some problem delivering the message to the mail transfer host. In effect, this parameter can be used to inform the user about the outcome of sending the email message.
message | This parameter contain some explanatory text if the message couldn't be delivered. It is unset if the email message had been successfully sent.

## Additional Hint

Cocoon provides the capability to automatically parse a file upload out of an incoming HTTP request. Depending on the setting of the parameter `autosave-uploads` (default is `false`) in Cocoon's `web.xml` file, the file upload is either stored in memory (`false`) for further processing or stuffed into Cocoons upload directory (`true`).

In theory, it should be equal whether the file upload data comes from memory of from file. In my particular setup (Linux, Tomcat 4.0.4, Mozilla 1.3 and JDK 1.4.1_02) I was unable to get the file uploading working with `autosave-upload=false`. Somehow the attached binary data was distorted (a GIF file does not appear to be a GIF any more).

With `autosave-upload=true` it worked flawlessly, even attaching multiple files.

## Probable solution to SendMail not working

If you have setup your SendMail action in Cocoon 2.1.8 or 2.1.9 or more recent and it doesn't work although the result of the action is success, the problem might lie

in the existence of the Geronimo files. Due to licensing problems it was not possible to include Sun's mail API jars, but without Cocoon wouldn't compile. Therefore, we included the Geronimo jars.

What you should do is:

- Download the JavaMail and JavaBeans Activation Framework (JAF) API's from Sun to work.
- Add them to WEB-INF/lib.
- Remove geronimo-spec-javamail-*.jar and geronimo-spec-activation-*.jar from WEB-INF/lib.

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).