User Tools

Site Tools


pub:imailapis

[ Up To iMail ]

iMail Command APIs

This section covers commands that are not accessible from the iMail menu, but rather from a command line. Ideally suited for programming, the commands may be embedded within any high level language such as RPG IV or CL.

Note that the commands mirror the menu options available from the menu group entitled Send Mail Commands.

General note: As of iDocs release 6.90, iMail supports blank, comma or semi-colon as address separators in the TO, CC and BC addresses fields for all API's listed below.

Examples below:
ken@informdecisions.com, anh@informdecisions.com
ken@informdecisions.com,anh@informdecisions.com
ken@informdecisions.com anh@informdecisions.com

ECVTDBF

This command will copy a data base file to the IFS. It was added to iMail version 6.85 on 1/22/16.

                                    
                          Convert Database File (ECVTDBF)                        
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 File name  . . . . . . . . . . .                 Name                          
   Library  . . . . . . . . . . .     *LIBL       Name, *LIBL                   
 Member name  . . . . . . . . . .   *FIRST        Character value               
 Conversion Type  . . . . . . . .   *TXT          *TXT, *SAVF, *DIF, *XLS, *CSV 
 IFS Directory  . . . . . . . . .                                               
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                         Bottom 
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    
 F24=More keys                                                                  
                                                                                                                                                               

The following describes the command qualifiers and their expected values:

  • File Name – Enter the file name in this command qualifier
  • Library – Enter the iSeries library where the file can be found.
  • Member Name – Enter the member name if know, or *FIRST for the first member found in this file.
  • Conversion Type – Select *TXT, *SAVF, *DIF, *XLS, *CSV.
  • IFS Directory - Enter the target directory on the IFS in single quotes, i.e. 'home/mydirectory'. This diectory/path must exist, or ECVTDBF will be aborted. This text is case sensitive.

Note: If selecting the *XLS format, the column text is determined by the iMail Configuration default value for XLS Col from column text (Y/C/B). The *SAVF format will only function if selecting an appropriate save file.

ECVTSPLF

This command is used primarily for converting a spool file to a specific format and subsequently saving the resulting format to a file within the IFS directory structure.

                      iMail Convert Spooled File (ECVTSPLF)                     
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Spool file name  . . . . . . . .                 Name                          
 Job name . . . . . . . . . . . .   *             Name, *                       
   User . . . . . . . . . . . . .                 Name                          
   Number . . . . . . . . . . . .                 000000-999999                 
 Spool file number  . . . . . . .   *LAST         1-9999, *LAST                 
 Converted spool types  . . . . .   *PDF          Character value, *FCFC...     
 IFS Directory  . . . . . . . . .   '/imail'                                    
                                                                                
                                                                                
                                                                                
 IFS Filename . . . . . . . . . .   *SYSTEM                                     
                                                                                
                                                                                
                                                                                
                                                                                

The screen shot above looks nearly identical to the command ESNDSPLF in that the same technique is used to select the last spool file within a job stream. Likewise, another spool file may be selected if explicitly identified.

The remaining two parameters, TYPE and DIR define the spool conversion type and the location of where the file should be placed. Additionally, when converting a spooled file to *PDF the orientation of the spooled file will conform to the orientation value stored in the data area, DSORIENT. This value may contain *PORTRAIT, *LANDSCAPE, or *SYSDFT. If the value contains *SYSDFT, then the resulting orientation will be derived from the orientation of the source spooled file.

ESNDDTAQ

This command will send data to keyed data queue. It's included in the IFDCLIENT module. See https://manual.informdecisions.com/doku.php?id=pub:ifdcinstructions

ESNDDBF

The command ESNDDBF allows a specific member from a database file to be attached to an email and subsequently converted to the desired format and sent as an email attachment.

Below is how the command appears when prompted:

                          Send Database File (ESNDDBF)                          
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 File name  . . . . . . . . . . . FILE           DBFILE     Name   
   Library  . . . . . . . . . . .                  QGPL     Name, *LIBL                                      
 Member name  . . . . . . . . . . MBR            DBMBR      Character value                                  
 Attachment Type  . . . . . . . . TYPE           *TXT       *TXT, *SAVF, *DIF, *XLS, *CSV                    
 From: eMail address  . . . . . . FROMADDR                                      
                                                                                
 To: eMail address  . . . . . . . TOADDR                                        
                                                                                
                           + for more values                                    
                                                                                
 CC: eMail address  . . . . . . . CCADDR                                        
                                                                                
                           + for more values                                    
                                                                                
 BCC: eMail address . . . . . . . BCCADDR                                       
                                                                                
                           + for more values                                    
                                                                                
 Subject  . . . . . . . . . . . . SUBJECT                                       
                                                                                
 Message text . . . . . . . . . . MSG                                           
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
  ...                                                                           
 Zip Attachment . . . . . . . . . ZIP            *NO                            

Within the command above in the prompt for type any one of the following formats may be entered from the table below.

Type Format Description
*CSV Comma Separated Value Record and field based text file delimited with commas
*DIF Data Interchange Format Record and field based text file delimited with tabs
*SAVF System i Save File Requires that the source file already be a save file
*TXT Text Fixed format text file with no field delimitation
*XLS Excel format Fully compatible Excel format *


* Prior to using *XLS to send a database in Excel format, the command IMAILIFS needs to first be issued to install the Java dependencies used to create the Excel file form the DB2 database. The syntax for the using the command is:

   IMAILIFS LIB([YourSourceLibrary])


NOTE: Outlook 365 doesn't allow an override of the From Address and if entered on the API it will result in a send failure.

Thresholds and Limitations:


  - Limited to emailing a single database file. (For multiples use command ESNDDBFS) 
  - Limited to 80 characters for the sender and recipient addresses
  - Limited to 300 direct recipients in the To address*
  - Limited to 300 direct recipients in the Cc address in addition to those in the To address*
  - Limited to 300 blind copy recipients in the Bc address*
  - Limited to 80 characters for the subject
  - Limited to 2048 characters for the message
  - Limited to converting the database file to the following types if the attribute is a 
    source physical file. CSV, DIF, TXT, XLS, XLSX
  - Limited to retaining the initial format if the database file to the following types if the attribute is a 
    source save file. 
    - CSV - The maximum length of a database record is 32766 characters
    - DIF - The maximum length of a database record is 32766 characters
    - XLS - Maximum columns 255, Maximum column width 256
    - TXT - Maximum columns 255, Maximum column width 256

Note: Your mail server can also limit the file size sent. Check with your Mail Server Administrator.
 
Release specific notes:

iMail 6.90 and above supports blank, comma or semi-colon as address separators in TO, CC and BC addresses.

iMail 6.98 includes data area DSCSVLEFT used to control the method used to convert a database to CSV.
DSCSVLEFT = 'Y': Uses the original approach of utilizing SQL to read the data: it will limit the number of fields in database to 256 columns.
DSCSVLEFT = 'N': Uses the CPYTOIMPF command to convert a database to CSV and will not limit the columns in the data file, but it can negatively impact the format of numeric fields for some customers who will be better served with the original SQL approach.

ESNDDBFS

Identical to the command ESNDDBF but allows multiple database files to be attached to an email and subsequently converted to the desired format and sent as an email attachment. (iMail 6.87, 11/15/2016)

Below is how the command appears when prompted:

                     Send Multiple Database Files (ESNDDBFS)                    
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Select database files:                                                         
   File name  . . . . . . . . . .                 Name                          
     LIBRARY  . . . . . . . . . .     *LIBL       Name, *LIBL                   
   Member name  . . . . . . . . .   *FIRST        Character value               
   Attachment Type  . . . . . . .   *XLS          *TXT, *SAVF, *DIF, *CSV, *XLS 
                + for more values                                               
 From: eMail address  . . . . . .                                               
                                                                                
 To: eMail address  . . . . . . .                                               
                                                                                
                + for more values                                               
                                                                                
 CC: eMail address  . . . . . . .                                               
                                                                                
                + for more values                                               
                                                                                
                                                                        More... 
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    
 F24=More keys                                                                  

With a + in the Select database files field:

  
                    Specify More Values for Parameter DBFILES                   
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Select database files:                                                         
   File name  . . . . . . . . . .                 Name                          
     LIBRARY  . . . . . . . . . .     *LIBL       Name, *LIBL                   
   Member name  . . . . . . . . .   *FIRST        Character value               
   Attachment Type  . . . . . . .   *XLS          *TXT, *SAVF, *DIF, *CSV, *XLS 
                                                                                
   File name  . . . . . . . . . .                 Name                          
     LIBRARY  . . . . . . . . . .     *LIBL       Name, *LIBL                   
   Member name  . . . . . . . . .   *FIRST        Character value               
   Attachment Type  . . . . . . .   *XLS          *TXT, *SAVF, *DIF, *CSV, *XLS 
                                                                                
   File name  . . . . . . . . . .                 Name                          
     LIBRARY  . . . . . . . . . .     *LIBL       Name, *LIBL                   
   Member name  . . . . . . . . .   *FIRST        Character value               
   Attachment Type  . . . . . . .   *XLS          *TXT, *SAVF, *DIF, *CSV, *XLS 
                                                                                
                                                                        More... 
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    
 F24=More keys                                                                  
  

ESNDFILURL / ERCVFILURL

iDocs provides a utility to send a file from the IBM i to other system (ESNDFILURL) and receive files from other system to the IBM i (ERCVFILURL) via secured HTTP methods. With these commands, iDocs can facilitate the exchange of data with other systems via web services and a trust store. Since the integration is highly customized for each application, and because it depends on the receiving system to issue a certificate which is able to document in general. please contact your customer service representative and IFD will assist in the necessary configuration. The sample interface screen is shown below. Sample steps and useful commands to create certificates for mutual authentication to a server and a cacerts file (a trust store which contains server and client-signed certificates) are described here. This is for example only and will not work for every interface.

Below is an example for ESNDFILURL:

                    Send IFS File to URL (HTTPS) (ESNDFILURL)                   
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 HTTPS URL  . . . . . . . . . . . > informdecisions.com                         
                                                                                
                                                                                
                                                                                
 IFS Sending File . . . . . . . . > file                                        
                                                                                
                                                                                
                                                                                
 Keystore File  . . . . . . . . .   '$USERDATA/JAVA400/EXT/.KEYSTORE'           
                                                                                
                                                                                
                                                                                
 Keystore Password  . . . . . . .   'inform'                                    
                                                                                
                                                                                
                                                              More...          
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 TrustStore File  . . . . . . . .   '$JAVA_HOME/LIB/SECURITY/CACERTS'           
                                                                                
                                                                                
                                                                                
 Truststore Password  . . . . . .   'changeit'                                  
 Private Key Entry Alias  . . . .   'agave'                                     
 Server Log File  . . . . . . . .   ESNDFILURL.LOG                              
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                         Bottom 
Below is an example for ERCVFILURL:
                   Receive File from URL (HTTPS) (ERCVFILURL)                   
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 HTTPS URL  . . . . . . . . . . .   '/idocs/receive'                            
                                                                                
                                                                                
                                                                                
 LISTEN PORT  . . . . . . . . . .   443           Character value               
 IFS Output Directory . . . . . .   '/home/receive'                             
                                                                                
                                                                                
                                                                                
 Prefix name of receiving file  .   'receive.'                                  
                                                                                
 Keystore File  . . . . . . . . .   '$USERDATA/JAVA400/EXT/.KEYSTORE'           
                                                                                
                                                                                
                                                                                
 Keystore Password  . . . . . . .   'inform'                                    
 TrustStore File  . . . . . . . .   '$JAVA_HOME/LIB/SECURITY/CACERTS'           
                                                                                
                                                                                
                                                                                
 Truststore Password  . . . . . .   'changeit'                                  

                                               

ESNDMAIL

This command can be used to send an email message, and optionally to attach one or more pre-existing files contained in the IFS directory structure. ESNDMAIL will used either RPG or Java – depending on the iMail configuration setting.

Prompting the command will display the following command parameters:

                      Send iMail with Attachments (ESNDMAIL)                     
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 To: eMail address  . . . . . . . > TOADDR                                      
                                                                                
                + for more values                                               
                                                                                
 Subject  . . . . . . . . . . . . > SUBJECT                                     
                                                                                
 Message text . . . . . . . . . . > MSG                                       
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                            
 From: eMail address  . . . . . .   FROMADDR                                    
                                                                                
                                                                                
                                                                        More... 
 F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel      
 F13=How to use this display        F24=More keys                               
                                                                                                                                                                
                                                                                
                                                                                

Page Down for Additional Parameters.

                     Send iMail with Attachments (ESNDMAIL)                     
                                                                                
 Type choices, press Enter.                                                     
                                                                                
                                                                                
                            Additional Parameters                               
                                                                                
 Attachment file  . . . . . . . . > 'ATTACH1'                                   
                                                                                
                                                                                
                                                                                
                + for more values > 'ATTACH2'                                  
                                                                                
                                                                                
                                                                                
                                                                                
                                                                         Bottom 
 F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel      
 F13=How to use this display        F24=More keys                               
                                                                                                                                                        
Below are the parameter descriptions:

  • TOADDR - Enter the recipients email address in this parameter.
  • SUBJECT – Enter the email subject in this parameter.
  • MSG – Enter the message body in this parameter value. The message text can contain a macro substitution variable that will be used to insert an email message. This message will be derived from a text file identified with a '&' located on the IFS iMail directory. i.e. MSG(’This text file verbiage will be inserted &MESSAGE.txt into the body’). In this example MESSAGE is a formatted text file on the imail directory of the IFS.
  • CCADDR - Enter the copied recipients email address in this parameter.
  • BCCADDR - Enter the blind copied recipients email address in this parameter. Note that blind copy recipients addresses are not visible to the recipients specified in the parameter TOADDR
  • FROMADDR - Enter the from email address.
  • ATTACH - Enter one or more IFS directory files.

Below is an example of this command with multiple IFS attachments:

   ESNDMAIL TOADDR(davis@informdecisions.com) SUBJECT('Sending 3 Word Documents')  
   MSG('Message text') ATTACH('/home/dyokana/wordDoc1.doc' '/home/dyokana 
   /wordDoc2.doc' '/home/dyokana/wordDoc3.doc') 

ESNDMAILJ

Added to version 6.90 on 3/21/18, this command is similar to ESNDMAIL, but will always use Javamail to send. It can be used to send an HTML email with the email message extracted from an HTML file in IFS, and optionally to attach one or more pre-existing files contained in the IFS directory structure. This command also uses an enhanced ifdjava.jar to read mail message from a file.

The example below used ECVTSPLF to convert a spool file to HTML into file /home/anguyen/samplehtm.htm, and ESNDMAILJ to email that file. Example command shown below:

                                                                             
ESNDMAILJ TOADDR(ANH@INFORMDECISIONS.COM) SUBJECT(ESNDMAILJ) MSG('/home/anguyen/samplehtm.htm')   

You can create other HTML files, put them on to the IFS and use the command ESNDMAILJ specifying the path of HTML file into mail message.

ESNDMSG

This command simply sends an email message without attachments.

                         iMail Send Message (ESNDMSG)                          
                                                                               
Type choices, press Enter.                                                     
                                                                               
From: eMail address  . . . . . . FROMADDR                                      
                                                                               
To: eMail address  . . . . . . . TOADDR                                        
                                                                               
                          + for more values                                    
                                                                               
CC: eMail address  . . . . . . . CCADDR                                        
                                                                               
                          + for more values                                    
                                                                               
BCC: eMail address . . . . . . . BCCADDR                                       
                                                                               
                          + for more values                                    
                                                                               
Subject  . . . . . . . . . . . . SUBJECT                                       
 Message text . . . . . . . . . . MSG                                           
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                

The parameter values above conform to the requirements of the previously described APIS.

ESNDSPLF

This command will send a spool file as an email attachment. The spool file attachment may be specified one of two ways.

The most straightforward way to address the spool file to be attached is to assume that the last spool file created with the job stream should be sent. In fact, this is the command default.

The second way to specify the spool file attachment would be to identify the unique spool file name, user name, job, and spool file number. Consequently, with this level of specification the exact spool file can be located and attached regardless of whether or not the spool file had been created in the same job stream. However, these values need to be known prior to calling the command. Though it can be done, an end user would certainly not be expected to provide this information. This second technique would be much better suited to a CL, or RPG program. Note: The iDocs release V6.89 (10/05/17) and above will automatically detect the spool file type: SCS, PCL, AFPDS (new) and convert it to PDF. The OS release requires V7R1 and above for this feature to work.

When the command is prompted the following qualifiers appear as shown in the figure below:

                        iMail Send Spool File (ESNDSPLF)                        
                                                                                
Type choices, press Enter.  
                                                   
Printer file name  . . . . . . . FILE         > X                              
Job name . . . . . . . . . . . . JOB            *                              
  User . . . . . . . . . . . . .                                               
  Number . . . . . . . . . . . .                                               
Spooled file number  . . . . . . SPLNBR         *LAST
To: eMail address  . . . . . . .
               + for more values                     

Subject  . . . . . . . . . . . . SUBJECT 

                                                                                    More. . .  
                                                                                
 Message text . . . . . . . . . . MSG                                           
                                                                          
 CC: eMail address  . . . . . . . CCADDR                                        
                                                                                
                           + for more values                                    
                                                                                
 BCC: eMail address . . . . . . . BCCADDR                                       
                                                                                
                           + for more values 
                                                                                    More. . .                  
                            
 From: eMail address  . . . . . . FROMADDR                                      
                                                                                
 Attachment file  . . . . . . . . ATTACH                                        
                                                                                
                           + for more values                                    
                                                                                
 Attachment type  . . . . . . . . TYPE           *PDF        *FCFC.  *HTML,  *PCL,  *PDF   
 Retain attachment in IFS . . . .
 
 Overwrite attachment in IFS  . .                N           Y, N  
 Retain .msg file in /tmp . . . .                N           Y, N
 
                                                                                    More. . . 
                                    
                                                                                               
 Name of output file  . . . . . .
 

                            Additional Parameters 
                                 
 Zip Attachment . . . . . . . . . *NO             *NO, *YES, Y, N
 Read Receipt . . . . . . . . . . *NO             *NO, *YES, Y, N  
 Delivery Receipt . . . . . . . . *NO             *NO, *YES, Y, N  

                                                                                    Bottom

The following describes the command qualifiers and their expected values:

  • FILE – Enter the spool file name in this command qualifier
  • JOB – Here either the asterisk default needs to be accepted in order to capture the last spool file created within the job stream or the actual job name, user and job number needs to be explicitly defined.
  • SPLNBR – When capturing the last spool file in a job stream, accept the default value of *LAST, otherwise replace the default value with the specific spool file number associated with the job defined above.
  • TOADDR – The recipient’s address must appear in this parameter.
  • SUBJECT - Though not required, the subject may be placed here.
  • MSG – Here enter the body of the message text. A carriage return <CR> tag can be used anywhere in the text to break the text to the following line. The message text can contain a macro substitution variable that will be used to insert an email message. This message will be derived from a text file identified with a '&' located on the IFS iMail directory. i.e. MSG('This text file verbiage will be inserted &MESSAGE.txt into the body'). In this example MESSAGE is a formatted text file on the imail directory of the IFS.
  • CCADDR – Any copied addresses must appear in this parameter.
  • BCCADDR - Any blind copy addresses must appear here. Note that blind copy recipients addresses are not visible to the recipients specified in the parameter TOADDR
  • FROMADDR – This parameter requires the senders email address. If ommitted, then the default from address from the iMail configuration will be used.
  • ATTACH – This qualifier specifies a PC file from the IFS directory to be attached.
  • TYPE – Enter the type of attachment here as either or F4 Prompt displays a list for you to choose from:
    • *FCFC
    • *HTML
    • *PCL
    • *PDF
    • *PRTCTL
    • *RTF
    • *TXT
    • *XLS
    • *XLSX
    • *TIF
  • OUTPUTNAME - (Added 6.90 12/15/17) The parameter overrides the iMail attachment name. If this parameter is blank, then the default name is used. User can use the following values:
    • *SPLFNAME, *SPLNAME, *SPLNAM for spool file name
    • *SPLFNUM4, *SPLNUM4, *SPLFNBR4, *SPLNBR4, *SPLF#4, *SPL#4 for spool file number with 4 characters length.
    • *SPLFNUM, *SPLNUM, *SPLFNBR, *SPLNBR, *SPLF#, *SPL# for spool file number with 7 characters length.
    • *JOBNAME, *JOBNAM for spool job name
    • *JOBUSER, *JOBUSR for job user name
    • *JOBNUMBER, *JOBNBR, *JOBNUM, *JOB# for job number (6 characters)
    • *FORMTYPE, *FRMTYP, *FORMTYP for form type
    • *USERDATA, *USRDTA, *USERDAT for user data
    • *DATE for sending date in format YYMMDD
    • *TIME for sending time in format hhmmss
  • ZIP - The parameter controls whether or not the attachment is compressed and attached as a ZIP file. If the values is set to *YES, then the single spooled file is compressed and attached.
  • RCPREAD - This option deteremines if a read email receipt is sent back to the email senders' address.
  • RCPDLVR - This option deteremines if a deliveried email receipt is sent back to the email senders' however the ability to do so is based on the email client and settings of the recipients' email client.

ESNDSPLFS

This command is a nearly identical to ESNDSPLF except that it may be used to send multiple spooled file email attachements instead of one. This command however has not be extended to enable the multiple attachments to be compressed into a zipped file.

Below is the first portion of the command illustrating the optional multiple spooled files.

                       iMail Send Spool Files (ESNDSPLFS)                       
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Send Spooled Files:              CMDSPL                                        
   Spooled file name  . . . . . .                                               
   Job name . . . . . . . . . . .                *                              
     User . . . . . . . . . . . .                                               
     Number . . . . . . . . . . .                                               
   Spooled file number  . . . . .                *LAST                          
                           + for more values                                    
 To iMail address . . . . . . . . TOADDR                                        
                                                                                
                           + for more values                                    
                                                                                
 Subject  . . . . . . . . . . . . SUBJECT                                       
                                                                                

As is the convention for specifying a list, entering a plus sign in the prompt for more values enables more spooled files to be entered.

pub/imailapis.txt · Last modified: 2022/06/25 17:02 by 127.0.0.1