rContents overview

To enable you to seamlessly integrate directmail into your applications, directmail includes several APIs (program interfaces) and commands that you can use to create and send emails using simple IBM i commands and passed parameters.

The individual steps to create and send e-mails automatically are described in detail here.

OPNEMLAPI - Open E-Mail (menu selection 9)

The first API is used to open an e-mail process. You start the creation of an e-mail with the command OPNEMLAPI.

0251 - Open E-Mail

The names of the parameters are shown below in brackets. E.g. Recipient (RECEIVER).

Mailbox (MAILBOX)

Here you specify in which mailbox the e-mail process is to be opened

Sender (SENDER)

Enter the sender name and e-mail address of the sender of the e-mail.

Under certain circumstances, this information is checked by the SMTP server. The address must then be available on the SMTP server. Otherwise an error message may be displayed: "550-Requested action not taken: mailbox unavailable", or another error message from the SMTP server indicating an error (WRKEML, choice 25 for the unsent e-mail).

The format for the sender is:

SENDER(Max Mouse 'max.maus@acmegmbh.de')

Valid values are:

Sender name and Sender e-mail address

*MAILBOX The information is taken from the mailbox specified in the MAILBOX parameter box defined in the parameter MAILBOX.

Recipient (RECEIVER)

Max. 80 digits

Enter here recipient name and e-mail address of the recipient of the e-mail. The format for the recipient is:

RECEIVER((*TO Gustav Giraffe 'gustav.giraffe@acmegmbh.de') (*CC name 'email...'))

*TO specifies the recipient(s) who should receive the original email,

*CC specifies the recipient(s) who should receive a copy of the email,

*BCC specifies the recipient(s) who should receive the email in "blind copy", i.e. that all other recipients do not know about this copy.

0252 - Open e-mail 2nd page

Subject (SUBJECT)

This is the subject of the e-mail.

Max. Length: 256 characters.

Message body (TEXT) - Content of the body text of the e-mail

• List of up to 300 fields of 78 characters each
  • each field appears in the e-mail on a separate line
  • however, if a line ends with a plus sign ("+"), then the following line is appended

Examples

TEXT('xxx'' 'yyy+' 'zzz') results in:
xxx
yyyzzz

Priority (PTY)

Specifies the priority with which the e-mail should be sent

Valid values are:

*HIGH The e-mail will be sent with high priority

*NORMAL The e-mail is sent with normal priority

*LOW The e-mail is sent with low priority

Send priority (SNDPTY)

Specifies the send priority with which the e-mail should be sent. Depending on how the email was created, a send priority is assigned aurtomatically and thus will be sent faster by default..

Valid values are:

1-9 - Allowed send priorities

4 Interactively created e-mails get this priority (default)

5 API e-mails get this priority (default)

7 AutoMail emails get this priority (default)

Read confirmation (CONFIRM)

If the recipient's e-mail program supports this function, you can receive an information when the recipient opens the e-mail.

Valid values are:

*YES The recipient will be asked for a confirmation of receipt

*NO No acknowledgement of receipt is requested

Compress attachments (COMPRESS)

Attachments can be compressed. This is controlled by this parameter.

Valid values for this parameter:

*NO E-mail attachments are not encrypted

*YES E-mail attachments are encrypted

Encrypt e-mail (ENCRYPT)

Use this setting to specify whether the e-mail should be encrypted. Encryption can only be set to *YES if a DM400CRY license is available.

Valid values for this parameter:

*NO E-mails are not encrypted

*YES E-mails will be encrypted

*POSSIBLE Encryption is possible and is set individually for each mail process vidual mail process

*MAILBOX The encryption setting of the mailbox is used

*SYSVAL The encryption setting in the directmail configuration is used

Sign e-mail (SIGN)

directmail also supports the digital signature of e-mails to ensure their authenticity. Signing can only be set to *YES if a DM400CRY license is present.

Valid values for this parameter:

*NO E-mails are not signed

*YES E-mails are digitally signed.

*MAILBOX The signature setting of the mailbox is used

*SYSVAL The signature setting in the directmail configuration is used

IFS Copy Name (IFSBACKUP)

With which name the e-mail should be stored in IFS after sending.

0313 - Open e-mail 3rd page

IFS Copy Path (IFSPATH)

In which directory a copy of the e-mail should be stored in the IFS after sending.

CCSID of the parameter (PARMCCSID)

This value specifies in which CCSID the parameters are passed to the command.

Valid values for this parameter:

Number CCSID table

*CURRENT CCSID of the current job (default value)

*Job CCSID of the current job (default value)

The parameters for email addresses, names, subject and text are then automatically translated into the CCSID of the server jobs.

CCSID of the email (MAILCCSID)

This value specifies the CCSID in which the parameters are passed to the email.

Valid values for this parameter:

Number to use CCSID table

*SERVER Use CCSID of the server

*Job CCSID of the current job (default value)

The parameters for e-mail addresses, names, subject and text are then automatically translated into the CCSID of the server jobs.

WRTEMLAPI - Attach objects to e-mail (menu selection 10)

Any number of attachments can be added to an e-mail once it has been opened using the WRTEMLAPI command. These attachments can be PC documents from the integrated file system of the IBM i, spool files, or IBM i objects such as programs, files and libraries.

Here is a list of all parameters for the WRTEMLAPI command and their possible use depending on the selected object type:

Attach PC documents (TYPE *IFS)

PC documents are also accessible for the IBM i via the integrated file system (IFS). Therefore directmail uses this function to access PC files.

0253 - Attach PC documents 1.page

Object type (TYPE) - Specify what type of object you want to attach, in this case *IFS.

Alias filename (ALIAS)- With which name the file should be attached to the e-mail. *ORIG stands for the original name of the file.

Compress data (COMPRESS) - Here you specify whether the file should be packed before sending. The file can then be unpacked by the recipient using a standard program such as PKUNZIP, WINZIP, etc. directmail supports GZIP format as the packing format.

Valid values are:

*YES The file will be packed before attaching to the email
*NO The file will not be packed before attaching it to the e-mail

Smart Card Signature (SIGN) - Specifying when the attachment should be signed.

Valid values are:

*NO Attachment should not be signed.
*IMMED Attachment is to be signed immediately upon creation.
*DELAYED Attachment is to be signed immediately before sending (interesting in case of staggered sending) Interesting, because then the attachment is not signed at 7:00 a.m. when it is created, but at 10:00 p.m. when it is but at 10:00 p.m. when it is sent).

Delete object (DLT) - Here you specify whether the file should be deleted after attaching.

Valid values are:

*YES The file will be deleted after it is attached to the e-mail
*NO The file will not be deleted

Attach text to e-mail (ADDTOTXT)- Here you specify whether the file is to be sent as an attachment, or as text. If files are available in HTML format or HTML is specified as conversion format, these files can be used as alternative text. E-mail programs that support HTML as alternative text will then display the HTML document instead of the text. For this purpose, the parameter *ADDTOTXT(*ALT) must be specified in the WRTEMLAPI command.

Valid values are:

*YES The content of the object is to be used as text.
*NO The content of the object should be used as an attachment.
*ALT The content of the object should be used as alternative text. With some e- Mail programs this content is then displayed instead of the e-mail text, e.g. to display Underlining etc.

IFS object (OBJ) - Enter here the name and directory of the IFS object you want to attach

The WRTEMLAPI command can also be used to append multiple files with one call. For this purpose a generic search can be specified here. e.g.'test.pdf', 'test*.pdf', 'article4711.' or '/path/'. Furthermore, subdirectories can also be searched if the SUBDIR parameter is set to *YES.

Search subdirectories (SUBDIR) - Subdirectories should also be searched.

Valid values are:

*YES Subdirectories will be searched as well.
*NO Subdirectories are not searched.

^{0320 - Attach PC documents 2nd page}
Search and replace (SCNRPL) -This allows to search the contents of the attachment and replace it with values.

Search for -Search string
Replace with -Substitute string
Multiple occurrences - Here you specify whether the search string occurs more than once on the page.

Valid values are:

*NO Search string can occur only once (default)
*YES Search string can occur multiple times

Data stream file CCSID (STMFCCSID) - Valid values are:

*STMF (Default)
Number - 1 - 32767

Parameter CCSID (PARAMCCSID) - Valid values are:

*JOB (Default)
Number - 1 - 32767

Append spool file (TYPE *SPLF)

Programmatically you can attach spool files to emails using WRTEMLAPI.

0254 - Attach spool file *SPLF 1st page

Object type (TYPE) - Specify what type of object you want to attach, in this case *SPLF.

Alias filename (ALIAS) - With which name the file should be attached to the e-mail. *ORIG stands for the original name of the file.

Compress data (COMPRESS) - Here you specify whether the file should be packed before sending. The file can then be unpacked by the recipient using a standard program such as PKUNZIP, WINZIP, etc. directmail supports GZIP format as the packing format.

Valid values are:

*YES The file will be packed before attaching to the email
*NO The file will not be packed before attaching to the email

Smart Card Signature (SIGN) - Specify when the attachment should be signed.

Valid values are:

*NO Attachment should not be signed.
*IMMED Attachment is to be signed immediately upon creation.
*DELAYED Attachment is to be signed immediately before sending (interesting in the case of staggered Interesting, because then the attachment is not signed at 7:00 a.m. when it is created, but at 10:00 p.m. when it is but at 22:00 hrs when it is sent).

Delete object (DLT)- Here you specify whether the file should be deleted after attaching.

Valid values are:

*YES The file will be deleted after attaching it to the e-mail
*NO The file will not be deleted

Attach text to e-mail (ADDTOTXT) - Here you specify whether the file should be sent as an attachment, or as text. If there are files in HTML format or if HTML is specified as conversion format, these files can be used as alternative text. E-mail programs that support HTML as alternative text will then display the HTML document instead of the text. For this purpose, the parameter *ADDTOTXT(*ALT) must be specified in the WRTEMLAPI command.

Valid values are:

*YES The content of the object is to be used as text.
*NO The content of the object is to be used as an attachment.
*ALT The content of the object should be used as alternative text. With some e- Mail programs this content is then displayed instead of the e-mail text, e.g. to show underlining etc. Underlining etc.

Spool file (FILE) - Name of the spool file to be attached.

Job name, user, number (JOB) - The job information of the spool file (can be displayed via the IBM i command WRKSPLF).

Spool file number (SPLNBR) - The running spool number of the job

Output format (FORMAT) - Here you specify the format in which the spool file should be attached to the email.

Valid values are:

*TXT The spool file will be converted to ASCII text and attached.
*CSV The spool file will be converted to semicolon separated text and attached and appended.
*HTML The spool file is converted to HTML document and attached and appended.
*PDF The spool file will be converted to PDF format (readable with Acro bat Reader) and attached.
*EPDF Adobe's PDF file format, but in the enhanced version of di rectmail PDF. This format allows e.g. form overlays, i.e. you can put behind jPG or TIF file behind the spool and thus achieve the impression of a completely printed form.
*ORIG The recipient of the e-mail also works with directmail and can receive the spool file in IBM i format.
*TIFF The spool file is converted to a TIFF graphic and attached
*GUMBO The spool file is to be converted by SPLAMATIC to be converted and appended by Gumbo.
*RAW Only the pure data stream is copied to a PC file (necessary for PCL or AFP).
*PCL PCL is used for page description.
*HPT The spool file will be converted to an HPT document and attached.

Spool-A-Matic format (GUMBOFMT) - Selection of the GUMBO format.

Manufacturer, type and model (MFRTYPMDL) - Specify for which printer model the conversion should be made.

^{0399 - Attach spool file *SPLF 2.page}
Data station customization object (WSCST), library - When converting via Host-Print-Transform, you can insert a data station adjustment object here, which will be used when converting the printer data stream.

Page range from-to (PAGERANGE) - Here you can select from which page and up to which page the spool file should be appended.

Valid values are:

Page number 0 - 999999
*LAST Append to last page number
*END Append to last page number

Use text only (TEXTONLY) - Here you control that for spool files only the plain text is used without graphics and other elements.

Green bars (GREENBAR) - for HTML format - Specify whether the lines in HTML format should be separated by white/green bars (gives the effect like printing on tabular paper).

Page table (PAGETABLE) - For multi-page documents, a page table is placed at the beginning of the document in HTML format for better navigation

In addition, the following parameters are available when attaching a spool file:

Paper size (PAGESIZE) - Specifies the default value for the paper size when converting spool files to PDF format. The valid values can be displayed by pressing F4.

Landscape (ROTATION) - Specifies whether the form should be written in landscape format. This parameter is available only for the *EPDF format.

Valid values are:

*SPLF The value for the page rotation of the spool file is used
*YES The form is used in landscape format
*NO The form is not used in landscape format
*AUTO The form is automatically rotated so that the margins are not exceeded are exceeded.

CPI (CPI) - Here you can specify a font width in CPI (characters per inch) different from the spool file.

Valid values are:

Number A valid CPI specification (e.g. 5,8,10,12,15,16,7...)
0 The CPI value of the spool file will be used.

LPI (LPI) - Here you can specify a font height in LPI (lines per inch) different from the spool file.

Valid values are:

Number A valid LPI specification (e.g. 5,8,10,12,15,16,7...)
0 The LPI value of the spool file will be used.

PDF Font (FONT) - Specify here the font to be used when converting to PDF. Valid here is currently *COURIER

Codepage CCSID (CCSID) - For Unicode conversion the CCSID controls the correct display of the characters in the PDF format.

Create PDF/A - Here you can set the compatibility with PDF/A standards.

Valid values are:

*NO - No PDF/A format will be converted
*V1A2005 - Sets the PDF/A compatibility level to PDF/A-1a:2005. Tagged PDF mode will be automatically enabled
*V1B2005 - Sets the PDF/A compatibility level to PDF/A-1a:2005

0400 - Attach spool file *SPLF 3rd page

Text Origin Coordinates (PDFAREA)

X axis mm - Allows you to move the original spool file text to the right by the specified millimeters, or to the left if the input is negative (e.g. -10).

Scale X - Here you specify the scaling factor with which the original spool text is to be scaled.

Valid values are:

Number - A percentage of the original size (e.g. 90 = 90%, 120 = 120%)
*NO - Do not scale
*YES/*FIT - Scale to page size - avoids moving spool text beyond the page margin

Y axis mm - Allows you to move the original spool text down by the specified millimeters, or up if negative (e.g. -10).

Scale Y - Here you specify the scaling factor with which the original spool text is to be scaled.

Valid values are:

Number - A percentage of the original size (e.g. 90 = 90%, 120 = 120%)
*NO - Do not scale
*YES/*FIT - Scale to page size - avoids moving spool text beyond the page margin

Form first page (OVERLAY) - Enter here the name of the form to be added to the PDF file. This file must be located in the FORMS directory of DirectMail400. This parameter is possible only when using the *EPDF format.

Form Position (MARGINS) - Enter here the margins with which the graphic is to be aligned on the first page as desired.

Form Following Pages (OVERLAY2) - Enter here the form for the following pages.

Valid values are:

*FIRSTPAGE Follow-up pages as the first page
*NONE no form

Form Position (MARGINS2) - Enter the margins here to align the graphic as desired on the continuation pages.

0401 - Attach spool file *SPLF 4th page

PDF Security Settings (PDFSEC) - Here you specify the settings for encrypted sent PDF files. The parameters are described in detail under the CRTSECPDF command.

CSV Column Separation (CSVTAB) - Here you control the column separation.

Valid values are:

1-200 number of columns
*NONE no column separation
*AUTO Automatic column separation is performed

Display CSV blank rows (CSVSPCLIN) - This controls the display of blank lines.

Valid values are:

*YES Blank lines are not deleted
*NO Blank lines are deleted

Display CSV format error (CSVNOFIT) - This controls the display in case of format errors.

Valid values are:

*YES All rows will be displayed
*NO Rows that do not fit into the CSV schema will be deleted

0402 - Attach spool file *SPLF 5th page

Display CSV header lines (CSVHEAD) - This controls the display of header lines.

Valid values are:

*YES Header lines are displayed
*NO Lines detected as header lines are deleted

Note: Best results with CSVSPCLIN=*NO and CSVNOFIT=*NO

0393 - Append spool file *SPLF 6th page

CSV Separator (CSVSEPCHR) - Input of the field separator for the email to be output.

Valid values are:

Character value Input of the separator character
*SYSVAL The system value is used

Attach backup file (Savefile) (TYPE *SAVF)

With directmail you can also send IBM i objects saved in savefiles automatically via WRTEMLAPI.

0257 - Attach savefile

Object type (TYPE)

Here you specify to which object type the attachment belongs. In this case *SAVF.

Alias file name (ALIAS)

With which name the backup file should be attached to the e-mail. *ORIG stands for the original name of the file.

Compress data (COMPRESS)

Here you specify whether the file should be packed before sending. The file can then be unpacked by the recipient using a standard program such as PKUNZIP, WINZIP, etc. directmail supports the GZIP format as the packing format.

Valid values are:

*YES The file will be packed before attaching to the email

*NO The file will not be packed before attaching it to the e-mail

Smart Card Signature (SIGN)

Specify when the attachment should be signed.

Valid values are:

*NO Attachment should not be signed.

*IMMED Attachment is to be signed immediately upon creation.

*DELAYED Attachment is to be signed immediately before it is sent (interesting in case of staggered Interesting, because then the attachment is not signed at 7:00 a.m. when it is created, but at but at 22:00 hrs when it is sent).

Delete object (DLT)

Here you specify whether the backup file should be deleted after attachments.

Valid values are:

*YES The backup file will be deleted after attachments to the email.

*NO The backup file will not be deleted.

Backup file (SAVF)

Enter the name of the backup file here.

Library

Enter the name of the library for the backup file.

Attach IBM i database file (TYPE *FILE)

With directmail you can also attach IBM i database files either as attachments to e-mails to be sent or in the text of the e-mail.

0258 - Attach database file

Object type (TYPE)

Is in this case *FILE.

Alias file name (ALIAS)

With which name the file should be attached to the e-mail. *ORIG stands for the original name of the file.

Compress data (COMPRESS)

Here you specify whether the file should be packed before sending. The file can then be unpacked by the recipient using a standard program such as PKUNZIP, WINZIP, etc. directmail supports the GZIP format as the packing format.

Valid values are:

*YES The file will be packed before attaching to the email

*NO The file will not be packed before attaching it to the e-mail

Smart Card Signature (SIGN)

Specify when the attachment should be signed.

Valid values are:

*NO Attachment should not be signed.

*IMMED Attachment is to be signed immediately upon creation.

*DELAYED Attachment is to be signed immediately before it is sent (interesting in case of staggered Interesting, because then the attachment is not signed at 7:00 a.m. when it is created, but at 10:00 p.m. when it is but at 22:00 hrs when it is sent).

Delete object (DLT)

Here you specify whether the file should be deleted after attaching.

Valid values are:

*YES The spool file will be deleted after attaching to the email

*NO The spool file will not be deleted (default)

Attach to e-mail text (ADDTOTXT)

Here you specify whether the file should be sent as an attachment, or as text.

Valid values are:

*YES The content of the object should be used as text.

*NO The content of the object should be used as text (default).

*ALT The content of the object should be used as alternative text. With some e- Mail programs this content is then displayed instead of the e-mail text, e.g. to show underlining etc. Underlining etc.

File/Library (DBFILE)

Enter the name and library of the IBM i database file you want to attach.

Part file (DBMBR)

Enter here the name of the part file you want to attach.

Valid values are:

*FIRST The first part file in the database file will be appended.

Name The part file matching the specified names will be appended.

Output format (DBOUTFMT)

The file to be appended can be converted to different file formats.

Valid values are:

*TXT The file will be converted to TXT format. This file format can be be read by almost all editors.

*CSV The file is converted to the CSV format. This Format separates the fields by semicolons and can be used very well e.g. for the further processing by a Spreadsheet program like Microsoft Excel.

*HTML The file is converted to HTML format.

*DBASE3 The file will be converted to DBASE3 format.

Add field description (DBFLDDSC)

This controls whether the field names should be included in the output.

Valid values are:

*YES The field descriptions will be added

*NO The field descriptions will not be added (Default)

CLSEMLAPI -Close E-Mail (Menu selection 11)

To close and send an e-mail use the CLSEMLAPI command.

0259 - Close and send e-mail

Send e-mail (SEND) - Completes the e-mail process and sends the e-mail - either immediately or at the time specified in the SCDDATE and SCDTIME parameters.

Valid values are:

*EDIT calls the editor for individual completion of the e-mail after it has been completed
*YES sends the e-mail
*NO deletes the e-mail. It is not saved and not sent - necessary if there was an error before
*HOLD saves the e-mail in the Outbox folder of the mailbox specified at opening and sets it to the Hld (Stopped) status

Time for sending (SCDTIME) - time of sending

Date for sending (SCDDATE) - date of sending

Determine mail status via exit program

As of version 5.60, PTF 14, it is possible to determine the status of e-mails via exit program and to take measures depending on the situation.

The creation and configuration of such an exit program is described on the page Mailstatus Feedback - Exitprogramm.

SNDOBJEML command - Send an object by e-mail

As an alternative to the batch and spool APIs, which have a lot of options, there is a simplified form of e-mailing IFS objects (PC files such as PDF) that already exist. Here no conversion takes place

The description of the SNDOBJEML command can be found on the page CL-Befehle von directspool/directmail.