Create and Send MIME E-mail (QtmsCreateSendEmail) API


  Required Parameter Group:


  Omissable Parameter Group:


  Service Program Name: QTCP/QTMSCRTSNM

  Default Public Authority: *USE

  Threadsafe: Conditional; see Usage Notes

The Create and Send MIME E-mail (QtmsCreateSendEmail) API is used to create and send a Multipurpose Internet Mail Extensions (MIME) e-mail document through the Mail Server Framework (MSF). This API can also sign and encrypt the MIME document using Secure MIME (S/MIME). This API requires that the user of the job be in the System Distribution Directory (SDD) and have an SMTP name and SMTP domain assigned in the alias table. When this API is called, a reverse lookup for the e-mail address of the current user profile will be done. This will be what is what will be used as the originator. There are no setup or install prerequisites for sending unsigned and unencrypted e-mail. Signed and encrypted S/MIME documents require the following to be installed:

  1. 5761-SS1 option 33: Portable Application Solutions Environment (PASE) must be installed.

  2. 5761-SS1 option 34: Digital Certificate Manager (DCM) must be installed.

  3. 5733-SC1 option 1: OpenSSL must be installed.

  4. 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.


Authorities and Locks

Authority to /tmp
QMSF must have at least *X data authority to /tmp.
The current user profile must have *RWX data authority.

Authority to user certificate store directory
The current user must have *RWX authority to their user certificate store directory and *X authority to every directory in the path.

Authority to file attachments
The current user profile must have *X data authority to every directory in the path name, and *R data authority to the file itself.

Locks on file attachments
All attachments will be opened in O_SHARE_RDONLY. To avoid any sharing conflicts, all attachment file names should not have any open file handles for writing, while this API is running.


Required Parameter Group

Recipient array
INPUT; CHAR(*)

This array contains the recipients of the e-mail document.

Number of recipients
INPUT; BINARY(4)

The number of recipients passed in for the recipient array. The number of recipients must be greater than zero. This parameter is passed by value.

Format name of recipient array
INPUT; CHAR(*)

This format describes each recipient in the recipient array. The following format name is supported:

RCPT0100
This is the format for describing a recipient.
Note
INPUT; CHAR(*)

This structure describes the note and associated information about how to encode or secure the note.

Format name of note
INPUT; CHAR(*)

This is the format of the note. The following format names are supported:

NOTE0100
Simple note uses UTF-8 for the charset and base64 as needed for the transfer encoding.
NOTE0200
Note format that allows a selectable charset and transfer encoding.
NOTE0300
Note format that allows selectable transfer encoding and a user-defined charset.

See Note Formats for a description of these formats.


Omissible Parameter Group

Attachment array
INPUT; CHAR(*)

This array describes the attachments of the e-mail document. If this parameter is null, it is assumed that there are no attachments.

Number of attachments
INPUT; BINARY(4)

The number of attachments passed in for the recipient array. This parameter must be greater than zero if the attachment array is not null. This parameter is passed by value.

Format name of attachment
INPUT; CHAR(*)

This is the format of the attachments in the attachment array. If the attachment array parameter is null, this parameter must also be set to null; otherwise, this parameter cannot be null. Some of the following formats will inherit information from the note structure. The transfer encoding part of the attachments only applies to text content-types; binary content-types are always base64. The following format names are supported:

ATCH0000
Describes a note with no attachments.
ATCH0100
Describes a simple attachment where text files use the charset and text transfer encoding of the note.
ATCH0110
Describes a simple attachment where text files use the charset and text transfer encoding of the note, and supports a user-defined content-type.
ATCH0200
This format for attachments allows a selectable charset and text transfer encoding.
ATCH0210
This format for attachments allows a selectable charset and text transfer encoding and supports a user-defined content-type.
ATCH0300
This format allows selectable transfer encoding, a user-defined charset, and a user-defined MIME content type.

See Attachment Formats for a description of these formats.


Error Code
I/O; CHAR(*)

This is the structure in which error information is returned. If null is passed for this parameter, the API will assume that the bytes provided are zero and an exception will be raised instead of returned via the structure. For the format of the structure, see Error code parameter.


Recipient Formats

For detailed descriptions of the table fields, see Recipient Field Descriptions.


RCPT0100 Format



Recipient Field Descriptions

Input CCSID. This field specifies the input coded character set identifier (CCSID) of the text passed in to the structure. The following values are supported:

Length of recipient address. This field contains the length of the recipient address string. This is the length in bytes not characters.

Offset to recipient address. This field contains the offset from the start of the structure to the beginning of the recipient address.

Recipient address. This is the actual e-mail address that this recipient is at. It must be in mailbox@email_domain format. Any e-mail address passed as a parameter must be an address that is currently supported by the IBM® i SMTP server. This field is not null terminated.

Recipient type. This field specifies the type of recipient and what MIME header the recipient should be listed in. The following values are supported:



Note Formats

For detailed descriptions of the table fields, see Note Field Descriptions.


NOTE0100 Format



NOTE0200 Format



NOTE0300 Format



Note Field Descriptions

Charset CCSID. This field specifies the CCSID for the user-defined charset of the note. The note will be output and encoded, if necessary, in this CCSID, and the MIME will be tagged with the Note charset name. There are restrictions on how certain charsets are encoded. See the note transfer encoding field for details of those restrictions. This field is only valid for NOTE0300. For other formats the CCSID is selected for you based on your input. The following values are supported:

Header transfer encoding. This is the transfer encoding to use in the MIME header. A MIME header can either be 7-bit ASCII or a MIME Encoded Word. MIME Encoded Words can have 2 types of encoding: quoted printable and base64. All options for this field determine if encoding is necessary before using quoted printable or base64. All charsets that require base64 will use base64 regardless of the value of the field. The valid values for this field are:

Input CCSID. This field specifies the input CCSID of the text passed in to the structure. The following values are supported:

Length of note. This field contains the length of the note. If this field is set to zero, there will not be anything added in the main MIME boundary. This is the length in bytes not characters.

Length of note charset name. This field contains the length of the user-defined charset name for the attachment. This must be not be zero. This is the length in bytes not characters.

Length of password. This field contains the length of the password. If the note security level is set to 1,2 or 3, this field cannot be zero. If the note security level is set to 0, this field must be 0. This is the length in bytes not characters.

Length of subject. This field contains the length of the subject. If this field is set to zero, the subject field will not be inserted into the MIME document. This is the length in bytes not characters.

Maximum length of a text line. This field describes how long a text line can be for text transfer encodings of 7 bit or 8 bit. This field must be 0 if encoded via quoted printable or base64. Those encodings require that the text line never be greater than 76 characters. The default of 76 is assumed by NOTE0100. This field must be zero or greater. Zero is interpreted as the default, which is 76.

Note. This field is the actual string for the note, main part, of the e-mail. This field is not null terminated.

Note charset. This field represents commonly used character sets. NOTE0100 assumes that this is UTF-8. NOTE0300 does not use this field and uses Note Charset Name and Charset CCSID instead. The charset is the character set of the note in the output MIME document. Unicode UTF-8 is recommended to ensure that the generated MIME document can be rendered by the receiving POP Client. The valid values for this field are:

Note charset name. This field represents the charset name that this API should put in the MIME source for the note. This is only used for NOTE0300, where the charset is user defined. This charset should represent a valid IANA name, and the Charset CCSID should match that IANA name. See usage notes for a list of CCSIDs and their IANA mappings. This field is not null terminated. This field must be able to be converted from the Input CCSID to what the MIME standard requires. See Usage Notes.

Note content type. This field represents the content type of the note. The note is always a text content type. The valid values for this field are:

Note security level. This field represents the security type of the note. If this field is set to 0 the password field is not required. If this field is set to 1,2, or 3 the password field is required. The valid values for this field are:

Note transfer encoding. This field represents the transfer encoding to be used by the note. For NOTE0100, this is base64 when needed. Base64 is recommended over quoted printable. The valid values for this field are:

Offset to note. This field contains the offset from the start of the structure to the beginning of the note string. An offset of zero means that there will not be anything added in the main MIME boundary.

Offset to note charset name. This field contains the offset from the start of the structure to the beginning of the user-defined charset. This field must not be zero.

Offset to subject. This field contains the offset from the start of the structure to the beginning of the subject string. If this field is set to zero, the subject field will not be inserted into the MIME document.

Offset to password. This field contains the offset from the start of the structure to the beginning of the password string. If the note security level is set to 1,2,or 3 this field cannot be zero. If the note security level is set to 0, this field must be zero.

Password. This field contains the password of the private key. This field is only valid if the Note security level is 1, 2 or 3. The password is for the private key that is in the certificate store for the current user. This field is not null terminated. The valid characters for the password are: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.,:!?-+=#%@*^~_

Subject. This field is the actual string for the subject of the e-mail. This field is not null terminated.

Use note charset for headers. This field is for using the note charset as the mime header charset. For NOTE0100, this field defaults to UTF-8. Most e-mail clients support UTF-8 MIME headers, which is why this is the default behavior. Some e-mail clients support more charsets for the note than they do for the header, which is why this field exists. UTF-16,UTF-32, and any EBCDIC charset will probably not be supported by the receiving e-mail client. The valid values for this field are:



Attachment Formats

For detailed descriptions of the table fields, see Attachment Field Descriptions.


ATCH0100 Format



ATCH0110 Format



ATCH0200 Format



ATCH0210 Format



ATCH0300 Format



Attachment Field Descriptions

Attachment charset. This field represents commonly used character sets. This field only applies if the content type is marked as text. For ATCH0100 format, this field is the same as the note. ATCH0300 does not use this field and uses Attachment Charset Name and Attachment charset CCSID instead. The valid values for this field are the same as the note charset. See Note charset for the valid values. The attachment charset must have a supported conversion from the Input CCSID to whatever is required by the MIME standard. See Usage Notes.

Attachment Charset CCSID. This field specifies the CCSID of the user-defined charset for the attachment. The attachment will be output and encoded if necessary in this CCSID, and the MIME will be tagged with the attachment charset name. There are restrictions on how certain charsets are encoded. See the note transfer encoding field for details of those restrictions. This field is only valid for ATCH0300. The following values are supported:

Attachment content type. This field represents the content type of the attachment. The following are text content types: text/plain, text/html, text/xml. The rest are considered to be binary. The valid values for this field are:

Attachment content type name. This field represents the content type name that this API should put in the MIME source. Whether it is binary or text is determined by the Attachment File Type field. This is only used where the content type is user defined. This field is not null terminated. This field requires that the data within have a supported conversion from the Input CCSID to whatever the MIME standard requires.

Attachment file type. This field represents whether a user-defined content type is binary or text. This is used whenever the content type is user defined. Valid values for this field are:

Attachment text transfer encoding. This field represents the transfer encoding to be used by the attachment. For ATCH0100, this is base64 when needed for text content and base64 for binary content. Base64 is recommended over quoted printable for text. The valid values for text content types are the same as they are for the note. See Note transfer encoding for valid values.

File name. This field is an absolute Integrated File System path name to the file to be attached. The content type determines how the file is to be opened: binary or text. The charset is only used for text files. Text files will be converted from the tagged CCSID of the file to the output charset. Binary files will never be converted and will always be encoded with base64 regardless of the text transfer encoding. The attachment name will be the file name without the path. The attachment name will be output in the MIME header charset, and with the header transfer encoding defined in the note parameter. This field is not null terminated.

Input CCSID. This field specifies the input CCSID (coded character set ID) of the text passed in to the structure. The following values are supported:

Length of attachment charset name. This field contains the length of the user-defined charset of the attachment. This must not be zero. This is the length in bytes not characters.

Length of attachment content type name. This field contains the length of the user-defined content name of the attachment. This must not be zero. This is the length in bytes not characters.

Length of file name. This field contains the length of the Integrated File System file name. This must not be zero. This is the length in bytes not characters.

Offset to attachment charset name. This field contains the offset from the start of the structure to the beginning of the user-defined charset. This must not be zero.

Offset to attachment content type name. This field contains the offset from the start of the structure to the beginning of the user-defined content name of the attachment. This must not be zero.

Offset to file name. This field contains the offset from the start of the structure to the beginning of the file name string. This field must not be zero.

Usage Notes

  1. This API can only be safely called from the initial thread.

  2. This API will allow any supported CCSID for input and any supported charset for output, if that conversion is supported by the system, and that CCSID has a conversion to unicode. It is up to the caller to make sure the data passed has code points in both CCSIDs, and that the data is valid for that CCSID. If code points are missing the output MIME document may not be ledgable.

  3. E-mail addresses, content-types, charsets, and other MIME headers do not support MIME word encoding so they must be in ISO-8859-1 or be able to be converted to ISO-8859-1. MIME headers such as the subject and filename do support MIME word encoding, however not all e-mail clients can render a MIME word for those two keywords.

  4. IBM charsets are not listed because they are generally unsupported by e-mail clients. IBM CCSIDs generally have an associated charset where XXXX is the CCSID and ibmXXX is the charset. For example, CCSID 500 is ibm500. All IBM EBCDIC CCSIDs must be transferred by using base64.

  5. Unicode is recommended as a charset for sending characters that are not within 7-bit USASCII. utf-8 is the best choice for Unicode because most modern e-mail clients support that charset.

  6. Base 64 is the recommened encoding scheme for data that is not within 7-bit USASCII.

  7. Base 64 is the recommended encoding scheme for UTF-8 mime headers. This is because most e-mail clients do not support multi-byte quoted printable encodings.

  8. utf-16 and utf-32 are supported by a limited number of e-mail clients. Most e-mail clients do not auto-detect the endianess of utf-16 and utf-32 so only the big endian and little endian versions of utf-16 and utf-32 should be used in e-mail. utf-16 and utf-32 must be transferred by using base64. Although some e-mail clients support utf-16 and utf-32 for the note section of the e-mail, that does not mean that those clients also support utf-16 and utf-32 for the MIME headers, and for attachments. Due to the lack of support for utf-16 and utf-32, it is strongly recommended that utf-8 be used if you need a Unicode charset.

  9. The following table contains a list of common IANA charsets and their corresponding CCSID.

Error Messages

The following messages may be sent from this function:




API introduced: V6R1

[ Back to top | Office APIs | APIs by category ]