Chapter 1 - The MAILTOOL Command



                              E-Mail Tool (MAILTOOL)

Type choices, press Enter.


To Address . . . . . . . . . . . ______________________________________
+ for more values

To Name . . . . . . . . . . . . ______________________________________
From Address . . . . . . . . . . ______________________________________
From Name . . . . . . . . . . . ______________________________________
CC: Address . . . . . . . . . . ______________________________________
+ for more values

Name of CC recipient . . . . . . *NONE_________________________________
BCC: Address . . . . . . . . . . ______________________________________
+ for more values

Name of BCC recipient . . . . . *NONE_________________________________
Reply To Address . . . . . . . .  ______________________________________ Reply To Name . . . . . . . . . ______________________________________ Subject . . . . . . . . . . . . ______________________________________
 Message Text . . . . . . . . . .   *NONE_________________________________
Attachment . . . . . . . . . . . *NONE_________________________________
+ for more values

MDN Address . . . . . . . . . . *NONE_________________________________
MDN Name . . . . . . . . . . . . ______________________________________
Sender Address . . . . . . . . . *NONE_________________________________    
Sender Name . . . . . . . . . . ______________________________________ Message ID . . . . . . . . . . . *NONE Message ID Domain . . . . . . . *DFT   Save Email . . . . . . . . . . . *DFT *DFT, *YES, *NO Configuration File . . . . . . . *NONE Footer Stream File . . . . . . . ______________________________________ Attachment Name . . . . . . . . *ATT__________________________________
                + for more values

Send With Server Type . . . . . *IBMSMTP *MAILTOOL, *IBMSMTP...
Mail Router . . . . . . . . . . *NONE_________________________________
Perform MX Lookup . . . . . . . *YES *NO, *YES
Use SSL . . . . . . . . . . . . *NO *NO, *YES
Port . . . . . . . . . . . . . . 25 Number
SMTP Auth User . . . . . . . . . *NONE
SMTP Auth Password . . . . . . . *NONE
Use Mail Router . . . . . . . . *NO___ *NO, *YES, *ONLY
Bind to IP Address . . . . . . . *NONE
Timeout . . . . . . . . . . . . 30 Number
Coded Character Set Identifier 819 Number No Attachment Action . . . . . . *NONE *NONE, *ERR Body content type . . . . . . . 'text/plain'__________________________
 Mime header code page  . . . . .   819__         1-65535
Temporary Directory . . . . . . '/tmp'________________________________
Importance . . . . . . . . . . . *NORMAL___ *NORMAL, *HIGH, *LOW...
Priority . . . . . . . . . . . . *NONE *NORMAL, *URGENT...
Recipient Separator . . . . . . ',' Character value Close Connection . . . . . . . . *YES *YES, *NO
Debug . . . . . . . . . . . . . *NO_ *YES, *NO
Debug File Name . . . . . . . . 'mailtooldebug.txt'___________________
SMTP Debug File Name . . . . . . 'mailtoolsmtp.txt'____________________
Base64 Encode Subject . . . . . *NO *NO, *YES
Base64 Encode Message . . . . . *NO *NO, *YES


F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

The eMail Tool (MAILTOOL) command allows you to send emails from your AS/400 with a variety of options.

  • To Address - Enter the email address that you wish to send an email to. Up to 10 email addresses may be entered here. If you are using MAILTOOL Plus, you can also enter distribution list names preceeded with the * character.
  • To Name - Enter the name of the person or group you wish to send an email to.
  • From Address - Enter the email address of the person sending the email. With v3.11 and higher, the special value of *USER may be used. This will use the SMTP name defined on the directory entry for the user running the command for the from address.
  • From Name - Enter the name of the person that is sending the email.
  • CC: Address - Enter the email address that should be carbon copied (CCed) on this email. Up to 10 email addresses may be entered here. If you are using MAILTOOL Plus, you can also enter distribution list names preceeded with the * character.
  • Name of CC Recipient - Enter the name of the person or group being carbon copied on this email.
  • BCC: Address - Enter the email address that should be blind carbon copied (BCCed) on this email. Up to 10 email addresses may be entered here. If you are using MAILTOOL Plus, you can also enter distribution list names preceeded with the * character.
  • Name of BCC Recipient - Enter the name of the person or groiup being blind carbon copied on this email.
  • Reply to Address - Enter the email address to be used as a Reply To Address if different from the From address.
  • Reply to Name - Enter the name to be associated with the Reply To Address.
  • Subject - Enter the text that will be used as the subject line of the email.
  • Message Text - Enter the text that will be included as the message body of the email. The value \n used in the message text will instruct MAILTOOL to insert a new line. The special value of *ATT used for the message text will instruct MAILTOOL to include the attachment(s) specified as the body of the email. The characters \n will force a new line in this text.
  • Attachment - Enter the qualified path name of the attachment file that should be attached to this email. Up to 50 attachments may be specified.  A wildcard may be specified on this parameter to attach one or more files.  When using *ATT for the message body and a wildcard attachment in the first attachment parameter the results may be unpredictable as to which file it will use for the body.  It's best to supply a fully qualified name on the first parameter and any wildcards following.
Examples of specifying wildcards:                
  • /myfiles/*.pdf 
  • /myfiles/invoice*.pdf 
  • /myfiles/invoice* 
  • /myfiles/* 
  • Footer Stream File - Specify the full path and file name of a stream file containing data to be included as a footer in the email.  The special value of *NONE specifies that no footer will be included.
  • MDN Address - Enter an email address that should receive a delivery confirmation notice should the recipient of the email support this option.
  • MDN Name - Enter a name to be used for the MDN address.
  • Sender Address - Specifies the "sender" address to be used.  The values available are *NONE, *FROM, which will use the FROM address, or you can enter an email address.
  • Sender Name - Specifies the name to be used with the Sender email address.  This parameter will be ignored if *FROM is used for the SENDADDR parameter.
  • Message ID - Specify the message ID to use with this email.  *NONE will not use a message ID, *SYS will generate a system message ID, or you can enter a value to be used.
  • Message ID Domain - Specify the message ID domain to be used with this email.  *DFT will use the domain of the from address or you can enter a value.
  • Save Email - Specify if you want to save this email, even if there is no error.  The values are *DFT, which will use the default value saved in the MTPSAVE data area, *YES to save the email, or *NO to not save the email.  This is only valid when using MAILTOOL Plus.
  • Configuration File - Specify the full path and file name of a configuration file to use when sending this email.   *NONE will not use a configuration file and use the values on the command.  *DFT will use the default configuration file (which starts with /bvstools/mailtool/config/<userid>/defaults.json, and if that file doesn't exist  /bvstools/mailtool/config/defaults.json will be used).   If a configuration file is used, the parameters on the MAILTOOL command will be overridden with the values from the configuration file EXCEPT for the recipients (TO, CC and BCC) and Attachments or if the value doesn't exist in the configuration file or is blank.  See example below.
  • Send With Server Type - Enter the server that you would like to use to send the email. The valid values are:

    • *IBMSMTP which will use the standard IBM SMTP server to send the mail. 
    • *MAILTOOL  which will use MAILTOOL's new internal APIs to send the email.  This option requires a license for the MAILTOOL Plus Addon. 
    • *G4MSMAIL which will use the G4MSMAIL addon to the G4MS package to send the mail.  This option requires a license for the G4MSMAIL addon for the G4MS product as well as GETURI.

  • Mail Router - For use with the SENDWITH(*MAILTOOL) option. If you require the use of a mail router, enter the name or IP address of the mail router in this parameter.
  • Use Mail Router - For use with the SENDWITH(*MAILTOOL) option. Use *NO if you know that you do not require the use of a mail router and your AS/400 can communicate with the Internet. Use *YES if you wish to use a mail router as a backup for sending mail. If all other servers fail to send the mail, the value specified in the MAILRTR parameter will by used. Use the value *ONLY if you know you need to only use the mail router to send emails from your AS/400.
  • Perform MX Lookup - Specify if an MX lookup should be performed on the mail router specified.  This value can only be *NO if USERTR is*YES or *ONLY.
  • Use SSL -  Specify if the connection to the SMTP server should use SSL, TLS or no encryption..  If SSL is used, most often you will need to specify a different port as well.  This option is only valid when specifying SENDWITH(*MAILTOOL).  Specify *YES to use SSL, *TLS to use TLS, or *NO if no encryption is required.
  • Port - Specifies the port that will be used to connect.  The default value is 25.  If you are using SSL, this port most likely would need to be changed.  This option is only valid when specifying SENDWITH(*MAILTOOL).
  • SMTP Auth User  - If your SMTP server requires authentication, enter the user id associated with the account here.  If you are sending email with a GMail account and wish to use OAuth 2.0 authentication specify the value *G4G_XOAUTH2.  This will require G4G and GETURI are also installed on your system and that the GMail account in use has been set up.  If you are sending email with a Microsoft Outlook Cloud account and wish to use OAuth 2.0 authentication specify the value *G4MS_XOAUTH2.  This will require G4MS and GETURI are also installed on your system and that the Outlook account in use has been set up.
  • SMTP Auth Password - If your SMTP server requires authentication, enter the password associated with the account here.
  • Bind to IP Address - Use this to bind the communications from your iSeries to a specific IP address when using the SENDWITH(*MAILTOOL) option.
  • Timeout - Specify a timeout value when using MAILTOOL Plus!  This value is used to set a timeout value when connecting to the recipient's mail server or the mail router.
  • Coded Character Set Identifier - Specify the CCSID to use for EBCDIC to ASCII translations when using the SENDWITH(*MAILTOOL) option.
  • Attachment Name - Enter the name of the attachment file(s). This will change the name of the attachment as it appears in the email. If this is left as the default *ATT, the actual attachment file name will be used.
  • No Attachment Action - This parameter applies to when the user specifies a wildcard path in the attachment parameter.  If *NONE is specified the email will be sent even if no attachments are found.  If no attachments are found MAILTOOL will look for a file in the IFS named /bvstools/mailtool/noattdft.txt that will be attached by default. This is so you are able to set up your own message if no attachments are found.  The value *ERR will cause MAILTOOL to stop and report an error that no attachments were found.
  • Body Content Type - Enter the content type of the body of the message. The default is "text/plain" which indicates that the body of the message is plain text. If the body of the message is HTML, the value "text/html" should be used.
  • Mime Header Code Page - Enter the code page to use for the creation of the MIME header file.
  • Temporary Directory - Enter the IFS path of the temporary directory that will be used to create the MIME header files and debug files.
  • Importance - Enter a value to specify the importance of this email. On certain email clients this will mark the message with an importance icon representing the value. The value values are *NORMAL, *HIGH and *LOW.
  • Priority - Specifies the priority of the email.  The possible values are *NONE, *NORMAL, *URGENT, an *NONURGENT.
  • Recipent Separator - Enter a value to be used to seperate recipient addresses on the To:, CC:, and BCC: parameters. This defaults to a comma.
  • Close Connection - Specify *YES to close the connection when the email is sent.  Specify *NO to leave the connection open.  *NO is only valid when using MAILTOOL Plus, a mail router, and specifying USERTR(*ONLY).  Leaving the connection open should speed up delivery of emails as well as limit the number of logins that are performed to the mail router. 
  • Debug - Enter *YES to create a debug file that can be used to track down possible problems with the email command. If *YES is specified, a file named /tmp/mailtooldebug.txt will be created in the IFS.
  • Debug File Name - Enter the name of the file that will be created for debugging building of the MIME file.  The special value of /%id%/ will be replaced with the unique email ID if used in the name.
  • SMTP Debug File Name - Enter the name of the file that will be created for debugging the SMTP communications if the SENDWITH parameter is *MAILTOOL.  The special value of /%id%/ will be replaced with the unique email ID if used in the name.
  • Base 64 Encode Subject - Specify *YES to encode the subject.  This is helpful when non-ASCII characters are used in the subject.
  • Base 64 Encode Message - Specify *YES to encode the message body.  This is helpful when non-ASCII characters are used in the message.  Please note that any code page or CCSID used for data, stream files to load the message body, etc should be UTF-8 (1208) when using this option.


An example of sending an email using a configuration file is as follows:

MAILTOOL TOADDR(jeremyclarkson@topgear.com) 
SUBJECT('Please test the VW Golf R instead of a GTI.') 
MESSAGE('Dear, Jeremy. \n\n  I enjoyed your test of the VW GTI, but I am very interested in seeing a review of the VW Golf R as well.  With it''s all wheel drive system and more torque and HP I believe the Stig could put it around the track very fast. \n\n  Sincerley, Brad.') 
CONFIG('/bvstools/bvstone_mailtool.json')

This email will be sent using MAILTOOL Plus and authentication because the configuration file specified is set up with these proper values.  Only the recipient(s), subject, message and attachments will be used from the actual MAILTOOL command.

The configuration file is as follows:

{
"variables": [
{
"name":"from_email",
"default":"bvstone@gmail.com"
},
{
"name":"from_name",
"default":"Brad Stone"
},
{
"name":"subject",
"default":""
},
{
"name":"message",
"default":""
},
{
"name":"reply_to_email",
"default":" "
},
{
"name":"reply_to_name",
"default":" "
},
{
"name":"mdn_email",
"default":" "
},
{
"name":"mdn_name",
"default":" "
},
{
"name":"sender_email",
"default":" "
},
{
"name":"sender_name",
"default":" "
},
{
"name":"footer_stream_file",
"default":" "
},
{
"name":"message_id",
"default":" "
},
{
"name":"message_id_domain",
"default":" "
},
{
"name":"send_with_server_type",
"default":"*MAILTOOL"
},
{
"name":"mail_router",
"default":"smtp.gmail.com"
},
{
"name":"use_mail_router",
"default":"*ONLY"
},
{
"name":"perform_mx_lookup",
"default":"*NO"
},
{
"name":"use_ssl",
"default":"*YES"
},
{
"name":"smtp_port",
"default":"465"
},
{
"name":"smtp_auth_user",
"default":"bvstone@gmail.com"
},
{
"name":"smtp_auth_password",
"default":"password goes here"
},
{
"name":"bind_to_ip_address",
"default":" "
},
{
"name":"timeout",
"default":"30"
},
{
"name":"ccsid",
"default":"819"
},
{
"name":"no_attachment_action",
"default":" "
},
{
"name":"body_content_type",
"default":"text/plain"
},
{
"name":"mime_ccsid",
"default":"819"
},
{
"name":"temporary_directory",
"default":"/tmp"
},
{
"name":"importance",
"default":"normal"
},
{
"name":"priority",
"default":" "
},
{
"name":"recipient_separator",
"default":","
},
{
"name":"close_connection",
"default":"*YES"
},
{
"name":"debug",
"default":"*NO"
},
{
"name":"debug_file",
"default":"mailtooldebug_/%id%/.txt"
},
{
"name":"debug_smtp_file",
"default":"mailtoolsmtp_/%id%/.txt"
}
]
}





Comments