Guide: Deliver Content Rich Email Messages from your IBM i Server

Content Rich Email Messages from your IBM i Server

The Email module of CoolSpools allows you to send email directly from your IBM i server.

The command SNDCMNMSG can be used to send an email message, and the various CoolSpools commands used to convert IBM i spooled file reports or data to such formats as PDF and Excel all include parameters to send the converted document as an email attachment. In both cases there are a number of ways to enhance the message body, rather than just populating it with plain text. This guide provides a description of the different options available.

Entering text in the message body parameter

The command parameters allow you to enter message body text, and to specify whether that text should be handled as *TEXT, *HTML or *BOTH.

• *TEXT The message is sent as plain text
• *HTML The message is sent using HTML tags for rich formatting
• *BOTH Both plain text and HTML versions of the message are sent – the recipient’s mail client will decide which to display

So long as you are comfortable with standard HTML syntax, you can use the *HTML option to apply rich formatting to your message body, as in the example below:

SNDCMNMSG TO([email protected]) SUBJECT(‘This is a test email’) MSG(‘<h1>Header text</h1><p>Paragraph of text with some words in <b>bold</b>, <u>underlined</u> or <em>italicised</em>.</p><ul><li>Using the appropriate HTML tags</li><li>you can create bullet points</li></ul><table><tr><td style=”border:1px solid blue;”>or</td><td style=”border:1px solid blue;”>a</td><td style=”border:1px solid blue;”>table</td></tr></table>’ *HTML)

There are two potential drawbacks to this approach:

• If this command is added to CL program source, then the message text is static, and will be identical every time the CL program is called
• As the content and complexity of the message body increases, the command string in the CL program will become more difficult to maintain

These are issues that you can overcome by using some of the alternative methods that follow.

Using a CL variable in the message body parameter

One way of accommodating variation in the message text is to use a CL variable as the message body parameter value. This allows you to build up the message content within a CL program variable before running the CoolSpools command.

0000.01           /* Send email message confirming batch completion */
0001.00              PGM        PARM(&BATCHNO)
0002.00              DCL        VAR(&BATCHNO) TYPE(*CHAR) LEN(10)
0003.00              DCL        VAR(&MSGTXT) TYPE(*CHAR) LEN(1024)
0004.00              CHGVAR     VAR(&MSGTXT) VALUE(‘<h1>Batch number’ *BCAT +
0005.00                           &BATCHNO *TCAT ‘</h1><p>Batch processing +
0005.01                           is complete.  Please advise your <a +
0005.02                           href=”mailto:[email protected]”>Support +
0005.03                           Team</a> in the event of any issues.</p>’)
0006.00              SNDCMNMSG  TO(([email protected])) SUBJECT(‘Batch +
0007.00                           Completed’) MSG(&MSGTXT *HTML)
0008.00              ENDPGM

Using CoolSpools variables in the message body parameter

When sending an email using a conversion command (e.g. CVTSPLXLS or CVTSPLPDF) CoolSpools provides a mechanism to embed variable data in your message text. CoolSpools variables use the syntax <:VARIABLENAME:> and are substituted with the relevant value at runtime. Note that CoolSpools variables are not available with the SNDCMNMSG command.

There are three types of CoolSpools variables.

• Standard variables These contain system or job level data, such as the current date and time or runtime user

CVTSPLPDF FROMFILE(QPRINT) TOSTMF(report.pdf) EMAIL(*YES) EMAILOPT(*NO ‘Report as PDF’) EMAILTO(([email protected])) EMAILMSG(‘<h1>Report sent by <:CURUSERNAME:></h1><p>This report was sent at <:CURTIME:> on <:CURDATE:></p>’ *HTML)

• Option variables These are populated at runtime with CL variable data by using the OPTIONS() parameter

CVTSPLPDF FROMFILE(QPRINT) TOSTMF(report.pdf) EMAIL(*YES) EMAILOPT(*NO ‘Report as PDF’) EMAILTO(([email protected])) EMAILMSG(‘<p>This report was sent on behalf of <:SENDER:></p>’ *HTML) OPTIONS((<<:SENDER:> &RPTSND))

• Spooled file variables These variables are populated with content from within the spooled file being converted (by specifying the position of the data on the page, or a key string to locate the data)

CVTSPLPDF FROMFILE(QPRINT) TOSTMF(report.pdf) EMAIL(*YES) EMAILOPT(*NO ‘Report as PDF’) EMAILTO(([email protected])) EMAILMSG(‘<p>See attached the report for region <:REGION:></p>’ *HTML) EXITPGM(*VAR) EXITPGMPRM(*POS) EXITPGMPOS((1 3 15 5 REGION))

Any combination of the above CoolSpools variable types is supported. Please see the Spool Convertor User Guide for a further detail, including a full list of the standard variables available.

Storing message body text in a file on your IFS

When the required message body becomes large and complex, you may find it easier to maintain it as a text file on your IFS. This is more easily maintainable than entering text and HTML tags directly into the CoolSpools command parameter and allows you to easily preview the message content in a web browser.

The required parameter settings vary slightly between the SNDCMNMSG command and the conversion commands, but in both cases the location of a file on the IFS is provided in place of message body text, indicated by use of the special value *STMF, as shown:

SNDCMNMSG TO(([email protected])) SUBJECT(‘Test message’) MSG(*STMF *HTML) MSGSTMF(‘/messages/broadcast.htm’)

CVTSPLPDF FROMFILE(QPRINT) TOSTMF(report.pdf) EMAIL(*YES) EMAILOPT(*NO ‘Report as PDF’) EMAILTO(([email protected])) EMAILMSG(‘/messages/broadcast.htm’ *HTML *STMF)

Embedding images in your email message – IBM i Server

Including images in an email message is problematic for several reasons. Some email clients are intolerant of embedded images and will block them. If you use the HTML tag <img src=”image.gif”> to include an image, then the image is rendered by the recipient’s email client, so the location of the image file specified as src=”” must be accessible to the email recipient. If the image is stored on a local server within your network, then it is unlikely to display outside of your organisation.

CoolSpools allows you to embed inline images using a cid reference. This embeds a binary copy of the image data within the message that is delivered, allowing it to be rendered by the recipient without having to retrieve the image from an external location. The image is assigned a cid identifier (some email clients expect this to be a unique value) and is referred to by this identifier within the <img> tag as shown:

SNDCMNMSG TO(([email protected])) SUBJECT(‘Test message’) MSG(‘<p>Some text, followed by an inline image.</p><img src=”cid:uniqueid”>’ *HTML) ATTACH((‘/messages/image.jpg’ *CID *IMAGE *STMF uniqueid *UTF8))

Sending a message with multiple attachments – IBM i Server

When using the CoolSpools conversion commands, the result of the result can be delivered as an email attachment, but what if you want to convert and deliver multiple reports together? What if you want to attach a file that was created outside of CoolSpools? You can run multiple conversion commands to generate files on the IFS, and then use the SNDCMNMSG command to attach all of the files to a single email by using parameter ATTACH(). Using this parameter you can also specify whether each file should be delivered as an attachment (*ATTACH) or embedded (*EMBED) within the message body – the *EMBED option is not supported by all not all file types or by all mail clients.

SNDCMNMSG TO(([email protected])) SUBJECT(‘Test message with several attachments’) MSG(‘<p>This email contains several attachments.</p>’ *HTML) ATTACH((‘/reports/sales01.pdf’ *ATTACH *PDF) (‘/reports/sales02.xlsx’ *ATTACH *XLSX)(‘/messages/standard_footer.txt’ *EMBED *TEXT))