Send SMTP E-mail Message (SNDSMTPEMM)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Send SMTP E-mail Message (SNDSMTPEMM) command 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.
Restrictions:
- Your current user profile must be enrolled in the e-mail directory that is set by the CHGSMTPA command and the DIRTYPE keyword. For a setting of *SDD for the DIRTYPE keyword your user profile must be enrolled in the System Distribution Directory(SDD) and your user profile must also have an smtp name defined via the WRKNAMSMTP command. For a setting of *SMTP or *SMTPMSF your user profile must be enrolled via ADDUSRSMTP
- 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.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| RCP | Recipient | Values (up to 20 repetitions): Element list | Required, Positional 1 |
 Element 1: E-mail address |
Character value | ||
| Element 2: Type | *PRI, *CC, *BCC | ||
| 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 |
Optional |
| 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 | ||
| CHARSET | Character set | Element list | Optional |
| Element 1: Character set name | Character value, *UTF8, *BIG5, *EUCKR, *EUCJP, *GB2312, *ISO2022JP, '*ISO8859_1', '*ISO8859_2', '*ISO8859_4', '*ISO8859_5', '*ISO8859_6', '*ISO8859_7', '*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 | ||
| CONTENT | Content type | *PLAIN, *HTML, *XML | Optional |
| SMIME | S/MIME | *NONE, *SIGN, *ENCRYPT, *BOTH | Optional |
| PASSWORD | Password | Character value | Optional |
| Top |
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.
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 carbon copy recipient, will not be on either TO or CC in the MIME document.
| Top |
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.
| Top |
Note (NOTE)
Specifies the main body to use in this e-mail. The NOTE keyword cannot be blank when there are no attachments.
- *NONE
- Specifies the body to be blank.
- character-value
- Specifies the value that will be the body in the first MIME boundary. Up to 400 characters can be specified.
| Top |
Attachment (ATTACH)
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
- 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 is either *PLAIN, *HTML or *XML.
| Top |
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 email. 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.
| Top |
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
| Top |
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.
| Top |
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.
| Top |
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 email 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 email 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 transferredin 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 email 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 email 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 email to mailbox1@domain. The subject is "some subject. The body is "some note". There were one attachment, which is an image file in tiff format and 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.
| Top |
Error messages
*ESCAPE Messages
- TCP506F
- User &1 not in local SMTP mailbox directory.
- 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 File Authority Error
- TCP530D
- Password characters invalid.
- TCP530F
- Email Address Invalid.
- TCP5310
- User &1 not enrolled 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 on 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 not in the user certificate store for user &1.
- TCP5317
- Recipient certificate not in the user certificate store for user &1.
- TCP5318
- Password for User Certificate Store Invalid.
- TCP9999
- Internal system error in program &1.
| Top |