Email Service User's Guide

Version 3.3.9

Last updated: June 20, 2015


Table of Contents

Overview

Installation and Configuration

Request Syntax

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

    Using Telnet to Debug Mail Server Problems

    Email Error Code Reference

    Licenses and Acknowledgements


    Overview

    The Email service will send an email message to a list of recipients. Multiple attachments (both text and binary) are supported, and you may specify whether the message body content type is text/plain or text/html.

    Note: The Email service supports the basic Internet email transmission protocol, SMTP (Simple Mail Transfer Protocol) which supports only 7-bit ASCII characters. So, non-ASCII text (e.g. non-English characters) cannot be correctly represented in the message body or in the subject of an email sent via the Email service.


    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.3.9 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> | CC <Address> | BCC <Address> >...
         [FROM <user@company.com>] [CONTENTTYPE <contenttype>]
         < MESSAGE <Message> | FILE <File> [MACHINE Machine] >
         [SUBJECT <subject>] [NOHEADER] [TEXTATTACHMENT <file>]...
         [BINARYATTACHMENT <file>]... [ATTACHMENTMACHINE <machine>]
         [RESOLVEMESSAGE | NORESOLVEMESSAGE]
         [AUTHUSER <User> AUTHPASSWORD <Password>]

    TO specifies an email address to which the email will be sent. You may specify multiple TO options. This option will resolve variables. You can specify any number or combination of the TO, CC, and BCC options, but you must specify at least one of these options.

    CC specifies an email address to which the email will be carbon copied. You may specify multiple CC options. This option will resolve variables. You can specify any number or combination of the TO, CC, and BCC options, but you must specify at least one of these options.

    BCC specifies an email address to which the email will be blind carbon copied. You may specify multiple BCC options. This option will resolve variables. You can specify any number or combination of the TO, CC, and BCC options, but you must specify at least one of these options.

    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.

    CONTENTTYPE specifies the content type to be used for the message body. The valid values are "text/plain" and "text/html". This parameter is optional. The default will be to use the current operational setting (either the value set during the Email service registration, or via the SET request).

    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.

    RESOLVEMESSAGE | NORESOLVEMESSAGE specifies whether to resolve the MESSAGE option for STAF variables. If neither option is specified, the setting specified in the service parameters will be used.

    AUTHUSER specifies the user name which will be used to authenticate with the SMTP server via the Auth Login SMTP command. You should only specify this option if your SMTP server requires authentication. If you specify this option when using an SMTP server that does not allow authentication, you will see an error message such as AUTH mechanism LOGIN not available. If you specify the AUTHUSER option, you must also specify the AUTHPASSWORD option. This option will resolve variables.

    AUTHPASSWORD specifies the password which will be used to authenticate with the SMTP server via the Auth Login SMTP command. You should only specify this option if your SMTP server requires authentication. If you specify this option when using an SMTP server that does not allow authentication, you will see an error message such as AUTH mechanism LOGIN not available. If you specify the AUTHPASSWORD option, you must also specify the AUTHUSER option. This option will handle private data. This option will resolve variables.

    Security

    This request requires at least trust level 3.

    Notes

    Note that mailservers have a 990-character limit on each line contained within an email message. If an email message is sent that contains lines longer than 990-characters, those lines will be subdivided by additional line ending characters, which can cause corruption in the email message, particularly for HTML content. To prevent this from occurring, add your own line-ending characters at appropriate locations within the email message to ensure that no lines are longer than 990 characters.

    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, socket timeout, backup mail servers, content type, and whether to resolve the MESSAGE option for STAF variables).

    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>
    socketTimeout Socket Timeout <String>
    backupMailServers Backup Mail Servers <List> of <String>
    contentType Content Type <String>
    resolveMessage Resolve Message <String> Enabled | Disabled
    Notes:
    1. The "Mail Server" value is the mail server through which the email will be sent. Its value is specified via the MAILSERVER parameter when registering the Email service or via the SET request.
    2. The "Port" value is is the port through which the mail server will be accessed. Its value is specified via the PORT parameter when registering the Email service or via the SET request. The default is 25 if not specified.
    3. The "Socket Timeout" value is the timeout specified for the socket used to communicate with a mail server on a SEND request. Its value is specified via the SOCKETTIMEOUT parameter when registering the Email service or via the SET request. The default is 60000 milliseconds if not specified. Its value is displayed in milliseconds.
    4. The "Backup Mail Servers" value is a list of the backup mail servers which may be used when a problem occurs with the primary mail server. Its value is specified via the BACKUPMAILSERVERS parameter when registering the Email service or via the SET request.
    5. The "Content Type" value is the current message body content type. Its value is specified via the CONTENTTYPE parameter when registering the Email service or via the SET request. The valid values are "text/plain" and "text/html". This parameter can be overridden on a per request basis by specifying CONTENTTYPE as an option for the SEND request.
    6. The "Resolve Message" value indicates the setting for whether to resolve the MESSAGE option for STAF variables that was set during service configuration or via the SET request. Note that this value can be overridden on a per request basis by specifying RESOLVEMESSAGE/NORESOLVEMESSAGE as an option for the SEND request.

    Examples

    SET

    SET sets the current Email Service operational settings (overriding any previous settings, including service configuration settings).

    Syntax

    SET  [MAILSERVER <mailserver>]
         [PORT <mailport>]
         [SOCKETTIMEOUT <Number>[s|m|h|d|w]]
         [BACKUPMAILSERVERS <Space-separated list of backup mailservers>]
         [CONTENTTYPE <contenttype>]
         [RESOLVEMESSAGE | NORESOLVEMESSAGE]
    
    See "Installation and Configuration" for descriptions of these operational settings.

    Security

    This request requires at least trust level 5.

    Results

    Upon successful return, the result buffer will be empty.

    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 (where the registered name of the Email service is "Email") could look like (shown via a request from the command line in the table format):

    C:\>STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME Email
    Response
    --------
    Date-Time         Level Message
    ----------------- ----- --------------------------------------------------------
    20071108-16:26:06 Info  email service initialized, using mailserver na.relay.ib
                            m.com port 25 backupmailservers []
    20071108-16:26:32 Info  [tcp://staf2f.austin.ibm.com@6500:122] SEND TO [user1@
                            us.ibm.com] FROM user2 SUBJECT This is a test CONTENTTYP
                            E text/plain TEXTATTACHMENTS [c:/temp/rc0.txt, c:/temp/
                            perf.txt] BINARYATTACHMENTS [c:/temp/stats1.gif] ATTACH
                            MENTMACHINE staf3a.austin.ibm.com
    20071108-16:26:32 Info  [tcp://staf2f.austin.ibm.com@6500:122] 220 d03xxxx.boul
                            der.ibm.com ESMTP Sendmail 8.12.11.20060308/8.12.11; Th
                            u, 8 Nov 2007 15:26:24 -0700
    20071108-16:26:33 Info  [tcp://staf2f.austin.ibm.com@6500:122] 250 d03av04.boul
                            der.ibm.com Hello user1.austin.ibm.com [9.99.99.153], p
                            leased to meet you
    20071108-16:26:33 Error [tcp://staf2f.austin.ibm.com@6500:122] 553 5.5.4 user2.
                            .. Domain name required for sender address user
    20071108-16:26:58 Info  [tcp://staf2f.austin.ibm.com@6500:135] SEND TO [bdavid@
                            us.ibm.com] FROM user2@ibm.com SUBJECT This is a test CO
                            NTENTTYPE text/plain TEXTATTACHMENTS [c:/temp/rc0.txt,
                            c:/temp/perf.txt] BINARYATTACHMENTS [c:/temp/stats1.gif
                            ] ATTACHMENTMACHINE staf3a.austin.ibm.com
    20071108-16:26:58 Info  [tcp://staf2f.austin.ibm.com@6500:135] 220 d03xxxx.boul
                            der.ibm.com ESMTP Sendmail 8.12.11.20060308/8.12.11; Th
                            u, 8 Nov 2007 15:26:50 -0700
    20071108-16:26:59 Info  [tcp://staf2f.austin.ibm.com@6500:135] 250 d03xxxx.boul
                            der.ibm.com Hello user1.austin.ibm.com [9.99.99.153], p
                            leased to meet you
    20071108-16:26:59 Info  [tcp://staf2f.austin.ibm.com@6500:135] 250 2.1.0 user2@
                            ibm.com... Sender ok
    20071108-16:26:59 Info  [tcp://staf2f.austin.ibm.com@6500:135] 250 2.1.5 user1@
                            us.ibm.com... Recipient ok
    20071108-16:27:02 Info  [tcp://staf2f.austin.ibm.com@6500:135] 250 Mail queued
                            for delivery.
    


    Using Telnet to Debug Mail Server Problems

    If you are having problems getting your mail server to send emails via the STAF Email service, you can try submitting the same email request via telnet. It should fail in the same way the STAF Email service fails. If so then you will need to investigate why your mail server is unable to send the email. Here are the steps to send the email via telnet (these commands are essentially what the STAF Email service is sending):


    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/>.
     */