SNDSMTPEMM Command Instructions

Resolving The Problem

This document is the README for the new SNDSMTPEMM command.

SNDSMTPEMM - CL Command for Sending E-mail

SNDSMTPEMM allows you to create and send a Multipurpose Internet Mail Extensions (MIME) e-mail message through the IBM i SMTP Server. The sending address cannot be specified as an anti-spam precaution. The sending address will be looked up in the appropriate directory currently in use based on the current user profile.

Software Requirements

Apply SI51161 in v6r1 (could be superseded by more recent PTF)
Apply SI51160 in v7r1 (could be superseded by more recent PTF)

Restrictions

o	Before using SNDSMTPEMM, the current user profile must be added into the system directory using WRKDIRE. Your user profile must also have an SMTP user ID and SMTP Domain defined using the WRKNAMSMTP command (route will not be accepted).
o	Signed and encrypted S/MIME documents require the following to be installed: -- IBM i Option 33 (IBM PASE - Portable Application Solutions Environment) must be installed. -- IBM i Option 34 (Digital Certificate Manager - DCM) must be installed. -- IBM Portable Utilities for i Option 1 (OpenSSL) must be installed.

The user certificate store for the current user profile must also be set up before the use of S/MIME. All originator certificates should be imported as a server/client certificate. All recipient certificates should be imported as a certificate authority. Both originator and recipient certificate labels must be the associated E-mail address in lowercase.

Parameters

Keyword	Description	Choices	Notes
RCP	Recipient Values (up to 20 recipients): Element list Element 1: E-mail address Character value Element 2: Type *PRI, *CC, *BCC		Required, Positional 1
SUBJECT	Subject	Character value	Required, Positional 2
NOTE	Note	Character value, *NONE	Optional
ATTACH	Attachment Single values: *NONE Other values (up to 10 repetitions): Element list Element 1: File name Character value Element 2: Content type Character value, *OCTET, *PLAIN, *HTML, *XML, *RTF, *OGG, *PDF, *VISIO, *ZIP, *POST, *L123, *FREE, *WORD, *WORDPRO, *POWERPT, *EXCEL, *AC3, *MP3, *WAV, *GIF, *JPEG, *PNG, *MPEG, *MSG, *BMP Element 3: Type *BIN, *TXT		Optional
CHARSET	Character set Element list Element 1: Character set name Character value, *UTF8, *BIG5, *EUCKR, *EUCJP, *GB2312, *ISO2022JP, '*ISO8859_1', '*ISO8859_2', '*ISO8859_4', '*ISO8859_6', '*ISO8859_7', '*ISO8859_8', '*ISO8859_8', '*ISO8859_8', '*ISO8859_9', '*ISO8859_15', *MACINTOSH, *UTF16BE, *UTF32BE, '*WINDOWS_1250', '*WINDOWS_1251', '*WINDOWS_1252', '*WINDOWS_1253', '*WINDOWS_1254', '*WINDOWS_1255', '*WINDOWS_1256', '*WINDOWS_1257', '*WINDOWS_1258' Element 2: Character set CCSID 1-65533, *DFT		Optional
CONTENT	Content type	*PLAIN, *HTML, *XML	Optional
SMIME	S/MIME	*NONE, *SIGN, *ENCRYPT, *BOTH	Optional
PASSWORD	Password	Character value	Optional

Recipient (RCP)
Specifies the recipient to receive this e-mail. You may specify up to 20 recipients.

Element 1: e-mail address
Specifies the e-mail address to send to. The format of an e-mail address is mailbox@domain. The mailbox can be any character that can be converted to ISO-8859-1, but if there are unprintable characters the mailbox must be encapsulated with double quotation marks. The domain must be upper or lower case latin characters, period, dash, or underscore. Up to 200 characters may be specified.

Element 2: type

*PRI
Indicates this is a primary recipient, will be put in the TO field in the MIME document.

*CC
Indicates this is a carbon copy recipient, will be put in the CC field in the MIME document.

*BCC
Indicates this is a primary recipient, will not be on either TO or CC in the MIME document.

Subject (SUBJECT)
Specifies the subject to use in this e-mail.

character-value
Specifies the value that will appear in the created MIME document under the subject heading. Up to 60 characters can be specified.

Note (NOTE)
Specifies the main body to use in this e-mail. The NOTE keyword cannot be blank when there are no attachments.
character-value
Specifies the value that will be the body in the first MIME boundary. Up to 400 characters can be specified.

Attachment (ATTACHMENT)
Specifies the attachments to send with this e-mail message. An attachment is an Integrated File System (IFS) file to be attached to this e-mail message. In order to attach a file the Internet Assigned Numbers Authority (IANA) registered MIME content type must be provided, as well as the desired transfer method. You may have up to ten attachments.

Element 1: File Name
Specifies the absolute path of the Integrated File System (IFS) file name to attach to the document. Up to 200 characters can be specified.

Element 2: Content Type
Specifies the MIME content-type for this file. Any value up to 50 characters can be specified. For compatibility with the receiving e-mail client any supplied value should be defined by the Internet Assigned Numbers Authority (IANA) and supported by the desired e-mail client. If there is doubt on the MIME type or support of the receiving client send with *OCTET in *BIN mode.

*OCTET

application/octet-stream

*PLAIN
text/plain

*HTML
text/xml

*RTF
application/rtf

*OGG
application/ogg

*PDF
application/pdf

*VISIO
application/visio

*ZIP
application/zip

*POST
application/postscript

*L123
application/vnd.lotus-1-2-3

*FREE
application/vnd.lotus-freelance

*WORDPRO
application/vnd.lotus-wordpro

*WORD
msword

*POWERPT
vnd.ms-powerpoint

*EXCEL
vnd.ms-excel

*AC3
audio/ac3

*MP3
audio/mp3

*WAV
audio/wav

*GIF
image/gif

*BMP
image/bmp

*JPEG
image/jpeg

*PNG
image/png

*MPEG
image/mpeg

*MSG
message/rfc822

character-value
A valid IANA registered MIME type. Up to 60 characters can be specified.

Element 3: Type

*BIN
Indicates this file is binary. The file will be encoded with Base64.

*TXT
Indicates this file is text. The file will be not be encoded if all characters can be represented in 7 bits. If the file contains an 8 bit character Base64 will be used. Sending a file as text is only valid if the previous element was user supplied or are either *PLAIN, *HTML, *XML.

Character Set (CHARSET)
Specifes the MIME character set (charset) for all text in the e-mail message to be sent. The main body and all text file attachments will use this charset. All charsets must be defined by the Internet Assigned Numbers Authority (IANA). If a special value for the desired charset is missing, the user may enter the name of the charset and the corresponding CCSID that matches that charset. It is strongly recommended that UTF8 is used for sending NON-ASCII e-mail messages.

Element 1: Character set name
Specifies the charset name to be used for all text in the sent email. Charsets are defined by the Internet Assigned Numbers Authority. When selecting a charset the user should be aware if the receiving e-mail client supports that charset. The special values for this keyword have a list of charsets that are generally accepted by most e-mail clients. This will be added to the content-type field in the produced MIME document. UTF-8 is the recommended charset for sending of NON-ASCII e-mail.

*UTF8

utf-8

*BIG5
big5

*EUCKR
euc-kr

*EUCJP
euc-jp

*GB2312
gb2312

*ISO2022JP
iso-2022-jp

*ISO8859_1
iso-8859-1

*ISO8859_2
iso-8859-2

*ISO8859_4
iso-8859-4

*ISO8859_5
iso-8859-5

*ISO8859_6
iso-8859-6

*ISO8859_7
iso-8859-7

*ISO8859_8
iso-8859-8

*ISO8859_9
iso-8859-9

*ISO8859_15
iso-8859-15

*MACINTOSH
MACINTOSH

*UTF16BE
utf16be

*UTF32BE
utf32be

*WINDOWS_1252
windows-1252

*WINDOWS_1253
windows-1253

*WINDOWS_1254
windows-1254

*WINDOWS_1255
windows-1255

*WINDOWS_1256
windows-1256

*WINDOWS_1257
windows-1257

*WINDOWS_1258
windows-1258

character-value
A valid IANA registered MIME charset. Must provide a matching CCSID in the CHSETCCSID keyword. Up to 60 characters can be specified.

Element 2: Character set CCSID

Specifies the coded-character set identifier of the the user supplied charset for the outgoing e-mail. This value is ignored if using one of the provieded special values.

The CCSID of the charset must match the IANA charset provided or the e-mail will not be legible.

*DFT

ISO-8859-1 is used -- CCSID 00819.

1-65533
Specify the CCSID value to be used. Non-ASCII CCSIDs are not recommended, as the majority of e-mail clients only support ASCII.

Content Type (CONTENT)
Specifies the content-type of the main body provided by the NOTE keyword. The supported content-types for the body are plain text, html, or xml. Listed below are the Internet Assigned Numbers Authority (IANA) register MIME type that correspond with each special value.

*PLAIN

text/plain

*HTML
text/html

*XML
text/xml

S/MIME (SMIME)
Specifies the setting to use for Secure Multipurpose Internet Mail Extensions (S/MIME). This keyword sets the level of security for the e-mail: none, signed, encrypted, or signed/encrypted.

*NONE

S/MIME not used.

*SIGNED
The document will be signed using the user's certificate in the current user profile's user certificate store.

*ENCRYPT
The document will be encrypted using the user's certificate in the current user profile's user certificate store.

*BOTH
The document will be signed and encrypted using the user's certificate in the current user profile's user certificate store.

Password (PASSWORD)
Specifies the password that corresponds to the current user profile's certificate store. Up to 128 characters can be specified.
Valid characters are case sensitive and include all alpha-numeric characters (a-z, A-Z, and 0-9), and the following special characters:

PERIOD(.),

COMMA(,),
EXCLAMATION MARK(!),
NUMBER SIGN(#),
PERCENT SIGN(%),
ASTERISK(*),
PLUS SIGN(+),
HYPHEN(-),
SLASH(/),
COLON(:),
SEMICOLON(;),
EQUAL SIGN(=),
COMMERCIAL AT(@),
QUESTION MARK(?),
UNDERSCORE(_),
TILDE,
CIRCUMFLEX ACCENT.

Examples

Example 1: Send a Note to 2 Recipients
SNDSMTPEMM RCP((mailbox1@domain *PRI)
(mailbox2@domain2 *CC))
SUBJECT(some subject) NOTE(some note)

This command sends a simple text/plain e-mail to mailbox1@domain and carbon copied mailbox2@domain2. The subject is "some subject"; the note is "some note".

Example 2: Send a Note and 2 Attachments

SNDSMTPEMM RCP((mailbox1@domain *PRI))
SUBJECT(some subject) NOTE(some note)
ATTACH((/home/userid/textfile *PLAIN *TXT)
(/home/userid/binfile *ZIP *BIN))

This command sends a multipart e-mail to mailbox1@domain. The subject is "some subject. The body is "some note". There were two attachments one is a text file which will be transferred as UTF8 because the default charset was used and in 7 bit mime if possible other wise base64 will be used. The second file is a zip file it will be transferred in base64 and charsets are not used for binary files.

Example 3: Send a Note in a Different Charset Using S/MIME
SNDSMTPEMM RCP((mailbox1@domain *PRI))
SUBJECT(some subject) NOTE(some note)
CHARSET(ISO8859-1) SMIME(*BOTH)
PASSWORD(password)

This command sends a multipart e-mail to mailbox1@domain. The subject is "some subject. The body is "some note". The body will be in charset ISO8859-1 (Western) which is an ACSII charset rather than unicode. The email will be signed and encrypted. For this example the password for the user certificate store was "password".

Example 4: Send a Note with a User Defined Charset
SNDSMTPEMM RCP((mailbox1@domain *PRI))
SUBJECT(some subject) NOTE(some note)
CHARSET(IBM500 500)

This command sends a multipart e-mail to mailbox1@domain. The subject is "some subject. The body is "some note". The body will be in charset IBM500 which the corresponding CCSID is 500. IBM500 is an EBCDIC charset. The majority of e-mail clients do not render IBM500 or any EBCDIC charset so it is strongly recommended that when using a user supplied that you check to see if the destination e-mail client can render that charset.

Example 5: Send a Note and 1 Attachment with a User-Supplied MIME Type
SNDSMTPEMM RCP((mailbox1@domain *PRI))
SUBJECT(some subject) NOTE(some note)
ATTACH((/home/userid/image image/tiff *BIN))

This command sends a multipart e-mail to mailbox1@domain. The subject is "some subject. The body is "some note". There were two attachments one is an image file in tiff format which will be sent in binary. The user supplied MIME type needs to match the file type, needs to be defined by the IANA, and needs to be understood by the receiving client. If there is doubt on the MIME type or support of the receiving client send with *OCTET in *BIN mode.

Error messages

*ESCAPE Messages

TCP5305

Integrated File System File Not Found.

TCP5306

Error from Integrated File System API.

TCP5308

CCSID &1 not supported.

TCP5309

Error from Data Conversion API &5

TCP530A

Severe Processing Error

TCP530B

Error calling openssl with option &1

TCP530C

Integrated File System Authority Error

TCP530D

Password characters invalid

TCP530F

E-mail Address Invalid

TCP5310

User &1 not in System Distribution Directory

TCP5311

User &1 does not have a SMTP userid and SMTP domain.

TCP5312

Data Conversion failed when building the MIME Document.

TCP5313

A failure occurred when creating or sending the MIME Document.

TCP5314

Required product &2 option &1 not installed

TCP5315

User certificate store for user &1 not configured

TCP5316

Signer certificate &2 not in the user certificate store for user &1

TCP5317

Recipient certificate for &2 not in the user certificate store for user &1

TCP5318

Password for User Certificate Store Invalid.

TCP506F

User &1 not in local SMTP mailbox directory.

TCP9999

Internal system error in program &1.