Email Service User's Guide

Version 3.1.3

Last updated: February 27, 2006


Table of Contents

Overview

Installation and Configuration

Request Syntax

  • SEND
  • LIST SETTINGS
  • VERSION
  • HELP
  • Service Logging

    Email Error Code Reference

    Licenses and Acknowledgements


    Overview

    The Email service will send an email message to a list of recipients.


    Installation and Configuration

    1. Install Java 1.2 or later.

    2. Install STAF 3.0.0 or later by following the installation instructions in the STAF documentation.

    3. Install the Email V3.1.3 service:

    4. Configure the Email service:


    Request Syntax

    The Email service provides the following requests:

    SEND

    SEND send an email message to a list of recipients

    Syntax

    SEND TO <Address>... [FROM <user@company.com>]
         < MESSAGE <Message> | FILE <File> [MACHINE Machine] >
         [SUBJECT <subject>] [NOHEADER] [TEXTATTACHMENT <file>]...
         [BINARYATTACHMENT <file>]... [ATTACHMENTMACHINE <machine>]

    TO specifies an email address to which the email will be sent. You may specify multiple TO options. This option will resolve variables.

    FROM specifies an email address that the email will be sent from. If this option is not specified, the default from address will be STAFEmailService@<host name> where <host name> is replaced with the host name of the machine where the Email service that is sending the message is registered. This option will resolve variables.

    MESSAGE specifies the body of the email. This option will resolve variables.

    FILE specifies the file which contains the body of the email. This option will resolve variables.

    MACHINE is the machine where the FILE is located. If not specified, it assumes the file is on the machine submitting the EMAIL SEND request. This option will resolve variables.

    SUBJECT specifies subject of the email and is optional. This option will resolve variables.

    NOHEADER indicates that the "DO NOT RESPOND TO THE SERVICE MACHINE THAT GENERATED THIS NOTE" header should not be included at the beginning of the email body. If this option is not specified, the header will be included at the beginning of the email body

    TEXTATTACHMENT specifies a text file to attach to the email and is optional. You may specify multiple TEXTATTACHMENT options. This option will resolve variables.

    BINARYATTACHMENT specifies a binary file to attach to the email and is optional. You may specify multiple BINARYATTACHMENT options. This option will resolve variables.

    ATTACHMENTMACHINE is the machine where the attachments (if any) are located. If not specified, it assumes the files are on the machine submitting the EMAIL SEND request. This option will resolve variables.

    Security

    This request requires at least trust level 3.

    Results

    Upon successful return, the result buffer will be empty.

    Examples

    LIST SETTINGS

    LIST SETTINGS allows you to list the current operational settings for the Email service (such as mail server, port, and debug).

    Syntax

    LIST SETTINGS
    

    Security

    This request requires at least trust level 2.

    Results

    The result buffer for a LIST SETTINGS request will contain a marshalled <Map:STAF/Service/Email/Settings> representing the settings for the Email service. The map is defined as follows:

    Definition of map class STAF/Service/Email/Settings
    Description: This map class represents the settings for the Email service.
    Key Name Display Name Type Format / Value
    mailServer Mail Server <String>
    port Port <String>
    Notes:
    1. The "Mail Server" value is the mail server through which the email will be sent. It's value is specified via the MAILSERVER parameter when registering the Email service.
    2. The "Port" value is is the port through which the mail server will be accessed. It's value is specified via the PORT parameter when registering the Email service. The default is 25 if not specified.

    Examples

    VERSION

    VERSION displays the Email Service version.

    Syntax

    VERSION

    Security

    This request requires at least trust level 1.

    Results

    The result is the version number of the Email service.

    Examples

    HELP

    HELP displays the request options and how to use them.

    Syntax

    HELP

    Security

    This request requires at least trust level 1.

    Results

    The result buffer contains the Help messages for the request options for the Email service.

    Examples


    Service Logging

    The Email service maintains a machine log where it writes an entry when the following occurs:

    The logname for the Email service is the name under which the service is registered.

    Here is an example of what a Email service log on the local machine with machine nickname client1 could look like (shown via a request from the command line in the table format):

    C:\>STAF local LOG QUERY MACHINE client1 LOGNAME email
    Response
    --------
    Date-Time         Level Message
    ----------------- ----- --------------------------------------------------------
    20050611-16:05:36 Info  email service initialized, using mailserver na.relay.ib
                            m.com port 25
    20050611-16:05:38 Info  SEND TO [bdavid@us.ibm.com] FROM user SUBJECT This is a
                             test TEXTATTACHMENTS [c:/temp/rc0.txt, c:/temp/perf.tx
                            t] BINARYATTACHMENTS [c:/temp/staf1.gif]
    20050611-16:05:38 Info  220 d01av01.pok.ibm.com ESMTP Sendmail 8.12.11/8.12.11;
                             Sat, 11 Jun 2005 17:05:41 -0400
    20050611-16:05:38 Info  250 d01av01.pok.ibm.com Hello dave2268.austin.ibm.com [
                            9.53.53.168], pleased to meet you
    20050611-16:05:38 Error 553 5.5.4 user... Domain name required for sender addre
                            ss user
    20050611-16:05:51 Info  SEND TO [bdavid@us.ibm.com] FROM user@ibm.com SUBJECT T
                            his is a test TEXTATTACHMENTS [c:/temp/rc0.txt, c:/temp
                            /perf.txt] BINARYATTACHMENTS [c:/temp/staf1.gif]
    20050611-16:05:51 Info  220 d01av01.pok.ibm.com ESMTP Sendmail 8.12.11/8.12.11;
                             Sat, 11 Jun 2005 17:05:53 -0400
    20050611-16:05:51 Info  250 d01av01.pok.ibm.com Hello dave2268.austin.ibm.com [
                            9.53.53.168], pleased to meet you
    20050611-16:05:51 Info  250 2.1.0 user@ibm.com... Sender ok
    20050611-16:05:51 Info  250 2.1.5 bdavid@us.ibm.com... Recipient ok
    20050611-16:05:51 Info  354 Please start mail input.
    20050611-16:05:51 Info  250 Mail queued for delivery.
    


    Email Error Code Reference

    In addition to the common STAF return codes, the following Email return codes are defined:

    Table 1. Email Service Return Codes

    Error Code Meaning Comment
    4001 IO Exception An IO Exception occurred while sending the email.
    44XX
    45XX
    SMTP Errors The Email request generated an SMTP error. The SMTP error code is the last 3 digits of the error code. See section 4.2 in RFC 821 for an explanation of SMTP return codes (e.g. 450, 503, 553, etc).


    Licenses and Acknowledgements

    Commons Codec provides implementations of common encoders and decoders such as Base64, Hex, various phonetic encodings, and URLs.

    Acknowledgement

    This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

    License

    /*
     * The Apache Software License, Version 1.1
     *
     *
     * Copyright (c) 1999-2004 The Apache Software Foundation.  All rights 
     * reserved.
     *
     * Redistribution and use in source and binary forms, with or without
     * modification, are permitted provided that the following conditions
     * are met:
     *
     * 1. Redistributions of source code must retain the above copyright
     *    notice, this list of conditions and the following disclaimer. 
     *
     * 2. Redistributions in binary form must reproduce the above copyright
     *    notice, this list of conditions and the following disclaimer in
     *    the documentation and/or other materials provided with the
     *    distribution.
     *
     * 3. The end-user documentation included with the redistribution,
     *    if any, must include the following acknowledgment:  
     *       "This product includes software developed by the
     *        Apache Software Foundation (http://www.apache.org/)."
     *    Alternately, this acknowledgment may appear in the software itself,
     *    if and wherever such third-party acknowledgments normally appear.
     *
     * 4. The names "Xerces" and "Apache Software Foundation" must
     *    not be used to endorse or promote products derived from this
     *    software without prior written permission. For written 
     *    permission, please contact apache@apache.org.
     *
     * 5. Products derived from this software may not be called "Apache",
     *    nor may "Apache" appear in their name, without prior written
     *    permission of the Apache Software Foundation.
     *
     * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
     * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
     * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
     * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
     * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
     * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
     * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
     * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
     * SUCH DAMAGE.
     * ====================================================================
     *
     * This software consists of voluntary contributions made by many
     * individuals on behalf of the Apache Software Foundation and was
     * originally based on software copyright (c) 1999, International
     * Business Machines, Inc., http://www.ibm.com.  For more
     * information on the Apache Software Foundation, please see
     * <http://www.apache.org/>.
     */