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  . . . . . . . . . .   ______________________________________  

 Return Address . . . . . . . . .   *NONE_____________________________________         

 Return Name  . . . . . . . . . .  .            

 Message ID . . . . . . . . . . .  .   *NONE_____________________________________

 Message ID Domain  . . . . . . .   *DFT   

 List Unsubscribe Value . . . . .   *NONE 

 List Unsubscribe Post Value  . .   *NONE 

 User Defined Header:               

  Header ID  . . . . . . . . . .    ______________________________________________

  Header Value . . . . . . . . .    ______________________________________________

 Save Email . . . . . . . . . . .   *DFT          *DFT, *YES, *NO  

 Bad Address Action . . . . . . .   *DFT          *DFT, *WARN, *FAIL  

 Configuration File . . . . . . .  .   *NONE

 Footer Stream File . . . . . . .   ______________________________________  

 Attachment Name  . . . . . . . .   *ATT__________________________________

                + for more values

 Send With Server Type  . . . . .   *IBMSMTP      *MAILTOOL, *IBMSMTP...

 Mail Router  . . . . . . . . . .   *NONE_________________________________

 Mail Router Stream File  . . . .   *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 

 Redirect Email . . . . . . . . .   *DFT          *DFT, *YES, *NO

 Redirect Recipient . . . . . . .   *DFT  

 Redirect Config File . . . . . .   *DFT    

 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.

• 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.

• Return Address - Specifies the "return" address to be used.  The values available are *NONE, *FROM, which will use the FROM address, or you can enter an email address.

• Return Name - Specifies the name to be used with the Return email address.  This parameter will be ignored if *FROM is used for the RTNADDR 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.

• List Unsubscribe Value  - Specify the value to use on the List-Unsubscribe header.

• List Unsubscribe Post Value - Specify the value to use on the List-Unsubscribe-Post header.

• User Defined Header - Specify up to 50 user defined headers and values to be used in the email.

• 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.

• Bad Address Action - Specify *DFT to use the default value specified in the MLTBADAA data area.  *WARN will only issue a warning for a bad email or invalid or empty distribution list, and *FAIL will stop processing when an invalid email address or invalid or empty distribution list is encountered.

• 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.  The special value of *STMF can also be used.  In this case you will need to provide the fully qualified path and filename to a mail router file in the proper format.

• Mail Router Stream File - When MAILRTR(*STMF) is used, enter the fully qualified path and filename to a mail router file in the proper format. 

  • *NONE will not use a router file and use the values on the command.  *DFT will use the default router file (which starts with /bvstools/mailtool/config/<userid>/routers.json, and if that file doesn't exist  /bvstools/mailtool/config/routers.json will be used).  

• 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.

• Redirect Email - Specify *DFT to use the MLTREDIR value, *YES to redirect this email, or *NO to not redirect this email.

• Redirect Config - Specify *DFT to use the MLTREDIR value or specify the fully qualified path to a configuration file to use if redirecting is turned on either at the system level or command level.

• Redirect Recipient - Specify *DFT to use the MLTREDIR value or specify a single email address or MAILTOOL Distribution List entry (ie *TESTING) to use if redirecting is turned on at the system or command level.

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": "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": " "

  }

 ]

}