MIME services

Use MIME services to create MIME messages and extract information from MIME messages.

addBodyPart

Adds a body part (header fields and content) to a specified MIME object.

Input parameters for addBodyPart

  • mimeData: Document - MIME object to which you want to add a body part. (This IData object is produced by createMimeData).

  • content: java.io.InputStream or Object - Content that you want to add to the MIME object. content can be an InputStream or another MIME object. Use an InputStream to add an ordinary payload. Use a MIME object to add a payload that is itself a MIME message.

  • isEnvStream:String - Flag that specifies whether content is to be treated as a MIME entity.

Important: This parameter is only used if content is an InputStream.
Set this parameter to one of the following values:
  • yes to treat content as a MIME entity. addBodyPart will strip out the header fields from the top of content and add them to mimeData as part headers. The remaining data will be treated as the payload.
    Note: addBodyPart assumes that all data up to the first blank line represents the entity's header fields.- `no` to treat content as an ordinary payload.
  • no to treat content as an ordinary payload.

  • mimeHeader: Document - Specifies the part headers that you want to add with this body part. Key names represent the names of the header fields. The values of the keys represent the values of the header fields. For example, if you wanted to add the following header fields:

    • X-Doctype: RFQ

    • X-Severity: 10

    You would set mimeHeader as follows:

    key Value
    X-Doctype RFQ
    X-Severity 10

    Be aware that the following MIME headers are automatically inserted by getEnvelopeStream when it generates the MIME message:

    • Message-ID

    • MIME-Version

    Additionally, you use the content, encoding, and description parameters to set the following fields:

    • Content-Type

    • Content-Transfer-Encoding

    • Content-Description

    If you set these header fields in mimeHeader and you create a single-part message, the values in contenttype, encoding, and description, if specified, will override those in mimeHeader. See usage notes.

  • contenttype: String Optional - The value of the Content-Type header for this body part. For single-part messages, this value overrides the Content-Type value in mimeHeader, if one is present. Defaults to text/plain. See usage notes.

  • encoding: String Optional - Specifies how the body part is to be encoded for transport and sets the value of the Content-Transfer-Encoding header. For single-part messages, this value overrides the Content-Transfer-Encoding value in mimeHeader, if one is present. Defaults to 7bit. See usage notes.

Note: This parameter determines how the payload is to be encoded for transport. When you add a payload to mimeData, it should be in its original format. The getEnvelopeStream service will perform the encoding (as specified by encoding) when it generates the final MIME message.
Set to:
  • `7bit` to specify that content is 7-bit, line-oriented text that needs no encoding. This is the default.
  • `8bit` to specify that content is 8-bit, line-oriented text that needs no encoding.
Note: This encoding value is not recommended for messages that will be transported via SMTP over the Internet, because the data can be altered by intervening mail servers that can't accommodate 8-bit text. To safely transport 8-bit text, use quoted-printable encoding instead.
  • `binary` to specify that content contains binary information that needs no encoding.
Note: This encoding value is not recommended for messages that will be transported via SMTP over the Internet, because the data can be altered by intervening mail servers that can't accommodate binary data. To safely transport binary data, use base64 encoding instead.
  • quoted-printable` to specify that content contains 7 or 8-bit, line-oriented text that you want to encode using the quoted-printable encoding sheme.
  • `base64` to specify that content contains an arbitrary sequence of octets that you want to encode using the base64 encoding scheme.
  • `uuencode` to specify that content contains an arbitrary sequence of octets that you want to encode using the uuencode encoding scheme.

  • description: String - Specifies the value of the Content-Description header for this body part.

  • multipart: String - Flag that determines how addBodyPart behaves if mimeData already contains one or more body parts. By default, addBodyPart simply appends a new body part to mimeData if it already contains a payload. (This allows you to construct multi-part messages.) However, you can override this behavior if you want to either replace the existing payload with the new body part or throw an exception under these circumstances (see replace parameter, below). Set to:

    • yes to append a new body part to mimeData. This is the default.

    • no to replace the existing payload with the new body part. (Depending on the value of replace, this setting may cause addBodyPart to throw an exception.)

  • replace: String - Flag that specifies whether addBodyPart replaces the existing payload or throws an exception when it receives a mimeData that already contains a payload. This parameter is only used when multipart is set to no. Set to:

    • yes to replace the existing payload with the new body part. This is the default.

    • no to throw an exception.

Output parameters for addBodyPart

  • mimeData: Document - MIME object to which the body part was added.

Usage notes for addBodyPart

This service operates on the MIME object (mimeData) produced by createMimeData.

The way in which the contenttype and encoding parameters are applied depends on whether the finished message is single-part or multipart.

For single-part messages:

  • contenttype specifies the Content-Type for the entire MIME message. It overrides any value assigned to the Content-Type header in mimeHeader. If Content-Type is not specified in contenttype or mimeHeader, the value of the Content-Type header defaults to text/plain.

  • encoding specifies the Content-Transfer-Encoding for the entire MIME message. It overrides any value assigned to the Content-Transfer-Encoding header in mimeHeader. If Content-Transfer-Encoding is not specified in encoding or mimeHeader, the value of the Content-Transfer-Encoding header defaults to 7bit.

For multipart messages:

  • contenttype specifies the Content-Type for an individual body part. The Content-Type for the entire MIME message is automatically set to multipart/mixed, or to multipart/subType if a subtype was specified when the MIME object was created. See createMimeData.

  • encoding specifies the Content-Transfer-Encoding for an individual body part. The Content-Transfer-Encoding header in mimeHeader, if present, specifies the encoding for the entire MIME message. If Content-Transfer-Encoding is not specified in mimeHeader, or if the specified value is not valid for a multipart message, the value of the Content-Transfer-Encoding header defaults to 7bit. (7bit, 8bit, and binary are the only encoding values valid for multipart messages.)

addMimeHeader

Adds one or more header fields to a specified MIME object.

Input parameters for addMimeHeader

  • mimeData: Document - MIME object to which you want the header fields added. (This IData object is produced by createMimeData).

  • mimeHeader: Document - Header fields that you want to add to the MIME object. Key names represent the names of the header fields. The values of the keys represent the values of the header fields. For example, to add the following header fields:

    • X-Doctype: RFQ

    • X-Severity: 10

    You would set mimeHeader as follows:

    key Value
    X-Doctype RFQ
    X-Severity 10

    Be aware that the following MIME headers are automatically inserted by getEnvelopeStream when it generates the MIME message:

    • Message-ID

    • MIME-Version

    If you set these values in mimeHeader, getEnvelopeStream will overwrite them at run time.

Output parameters for addMimeHeader

  • mimeData: Document - MIME object to which the header fields were added.

Usage notes for addMimeHeader

This service operates on the MIME object (mimeData) produced by createMimeData.

If you add MIME headers before you add multiple body parts, the header fields will be added to each of the body parts. If you do not want this behavior, either drop mimeHeader from the pipeline immediately after you execute addMimeHeader, or invoke addMimeHeader after you've added all body parts to the MIME object.

Be aware that the contenttype and encoding parameters used by the addBodyPart service will override any Content-Type or Content-Transfer-Encoding settings in mimeData. Moreover, in certain cases, the getEnvelopeStream will override these settings when it generates a multipart message. For information about how the Content-Type or Content-Transfer-Encoding headers are derived at run time, see the Usage Notes under addBodyPart.

createMimeData

Creates a MIME object. If no input parameter is passed to this service, the service creates an empty MIME object. Otherwise, the service creates a MIME object containing the elements (header fields and content) from the MIME message in input. If you are building a MIME message, you use this service to create an empty MIME object. You populate the empty MIME object with header fields and content, and then pass it to getEnvelopeStream, which produces the finished MIME message. If you are extracting data from a MIME message, you use this service to parse the original MIME message into a MIME object so that you can extract its header fields and content using other services.

Input parameters for createMimeData

  • input: java.io.InputStream Optional - MIME entity you want to parse. If input is not provided, createMimeData creates an empty MIME object.

  • mimeHeader: Document Optional - Specifies header fields that you want to add to the MIME object. Key names represent the names of the header fields. The values of the keys represent the values of the header fields.

Note: This parameter is ignored when input is passed to this service.
For example, if you wanted to add the following header fields:
  • Doctype: RFQ
  • Severity: 10
You would set mimeHeader as follows:
X-Doctype
RFQ
X-Severity
10
Be aware that the following MIME headers are automatically inserted by getEnvelopeStream when it generates the MIME message:
  • Message-ID
  • MIME-Version
If you set these values in mimeHeader, getEnvelopeStream will overwrite them at run time.

  • subType: String - String that specifies the subtype portion of the Content Type header, when the message is a multipart message and you want something other than the default value of mixed. For example, if you want the Content Type header to be multipart/related in the resulting message, set subType to related. subType is ignored if the resulting message is not a multipart message.

  • decodeHeaders: String - Specifies how the MIME header is to be decoded. Set to:

    • " "(empty String) to decode headers based on the value of the global watt property watt.server.mime.decodeHeaders. This is the default.

    • NONE to specify that the MIME header or body part headers do not need decoding.

    • ONLY_MIME_HEADER to decode the MIME header only.

    • ONLY_BODY_PART_HEADERS to decode the body part headers only.

    • BOTH to decode the MIME header and the body part headers.

Output parameters for createMimeData

  • mimeData: Document - MIME object. If input was passed to createMimeData, mimeData will contain the parsed MIME message. If input was not passed to createMimeData, mimeData will be empty.

  • encrypted: String Conditional - Indicates whether input was an encrypted message. This parameter is not present when the service creates a new, empty MIME object. A value of:

    • true indicates that the message is encrypted (the original message stream is in stream).

    • false indicates that the message is not encrypted.

  • signed: String Conditional - Flag whose value indicates whether input was a signed message. This parameter is not present when the service creates a new, empty MIME object. A value of:

    • true indicates that the message is signed (the original message stream is in stream).

    • false indicates that the message is not signed.

  • certsOnly: String Conditional - Flag whose value indicates whether input contained only digital certificates. This parameter is not present when the service creates a new, empty MIME object. A value of:

    • true indicates that the message contains only certificates.

    • false indicates that the message contains a regular payload.

  • stream: java.io.InputStream Conditional - InputStream containing the original MIME message from input. This parameter is present only when input is an S/MIME message.

Usage notes for createMimeData

All of the other MIME services operate on the mimeData IData object produced by this service. They do not operate directly on MIME message streams.

Important: You can examine the contents of mimeData during testing and debugging. However, because the internal structure of mimeData is subject to change without notice, do not explicitly set or map data to/from these elements in your service. To manipulate or access the contents of mimeData, use only the MIME services that is provided.

getBodyPartContent

Retrieves the content (payload) from the specified MIME object. You use this service for both single-part and multi-part messages. To retrieve content from a multi-part message, you set the index (to select the part by index number) or contentID (to select the part by contentID value) parameter to specify the body part whose content you want to retrieve. To get the content from a single-part message, you omit the index and contentID parameters or set index to 0.

Input parameters for getBodyPartContent

  • mimeData: Document - MIME object whose content you want to retrieve. (This IData object is produced by createMimeData).

  • index: String - Index number of the body part whose content you want to retrieve (if you want to retrieve the content from a specific body part). The first body part is index number zero.

Note: If contentID is specified, index is ignored.
  • contentID: String - Value of the Content-ID header field of the body part whose content you want to retrieve (if you want to retrieve the payload from a specific body part).

Output parameters for getBodyPartContent

  • content: IData - The payload of the specified body part.

  • encrypted: String - Flag whose value indicates whether content is an encrypted MIME message. A value of:

    • true indicates that content is an encrypted message.

    • false indicates that content is not an encrypted message.

  • signed: String - Flag indicating whether content is a signed MIME message. A value of:

    • true indicates that content is a signed MIME message.

    • false indicates that content is not a signed MIME message.

  • certsOnly String - Flag whose value indicates whether content is a certs-only MIME message. A value of:

    • true indicates that content is a certs-only message.

    • false indicates that content is not a certs-only message.

Usage notes for getBodyPartContent

This service operates on the MIME object (mimeData) produced by createMimeData.

If you omit index or contentID when retrieving content from a multi-part message, getBodyPartContent returns the payload from the first body part. If you use index or contentID to select a body part that does not exist in mimeData, content will be null.

getBodyPartHeader

Returns the list of header fields for the specified body part.

Input parameters for getBodyPartHeader

  • mimeData:Document - MIME object whose message headers you want to retrieve. (This IData object is produced by createMimeData).
  • index: String - Index number of the body part whose header fields you want to retrieve. The first body part is index zero.
Note: If contentID is specified, index is ignored.

  • contentID: String - Value of the Content-ID header field of the body part whose header fields you want to retrieve.

  • decodeHeaders: String Conditional - Flag whose value indicates whether to decode encoded headers in the MIME object. Set to:

    • true to indicate that the headers should be decoded.

    • false to indicate that the headers should not be decoded. This is the default.

Output parameters for getBodyPartHeader

  • mimeHeader: Document - IData object containing the message headers. Key names represent the names of the header fields. The value of a key represents the value of that header field. For example, if the original message contained the following message header fields:

    • Content-Type: text/xml
    • X-Doctype: RFQ
    • X-Severity: 0
Key Value
Content-Type `text/xml`
X-Doctype `RFQ`
X-Severity `0`

Usage notes for getBodyPartHeader

This service operates on the MIME object (mimeData) produced by createMimeData.

If you omit index or contentID, getBodyPartHeader returns the message headers from the first body part. If you use index or contentID to select a body part that does not exist in mimeData, content will be null.

getContentType

Returns the value of the Content-Type message header from the specified MIME object.

Input parameters for getContentType

  • mimeData: Document - MIME object whose Content-Type you want to discover (This IData object is produced by createMimeData).

Output parameters for getContentType

  • contentType: String - Value of the MIME object's Content-Type header field. Note that this service returns only the media type and subtype portion of this header field's value. It does not return any parameters the value may include. For example, if the message's Content-Type header were:

    • Content-Type: text/plain;charset=UTF8

    contentType would contain:

    • text/plain

Usage notes for getContentType

This service operates on the MIME object (mimeData) produced by createMimeData.

getEnvelopeStream

Generates an InputStream representation of a MIME message from a specified MIME object.

Input parameters for getEnvelopeStream

  • mimeData: Document - MIME object from which you want to generate the MIME message(This IData object is produced by createMimeData).
  • index: String - Index number of the body part for which you want to generate the MIME message (if you want to generate the message from a specific body part). The first body part is index number zero.
  • contentID: String - Value of the Content-ID header field of the body part from which you want to generate the MIME message (if you want to generate the message from a specific body part).
Note: If index is specified, contentID is ignored.

  • returnMimeMessage: String. Specifies whether the MIME message is returned as a javax.mail.internet.MimeMessage object when any of the body parts in the message exceed the large data threshold. Set to: - yes to return the MIME message in the mimeMessage output parameter as a MimeMessage when the large data threshold is exceeded. This is the default. - no to return the MIME message as an InputStream in the envStream output parameter when the large data threshold is exceeded.

  • suppressHeaders: String List - Names of header fields that are to be omitted from message. You can use this option to exclude header fields that getEnvelopeStream generates by default, such as Content-Type and content-encoding.

  • createMultipart: String - Specifies whether a multipart message is to be created, even if mimeData contains only one body part. Set to:

    • yes to create a multipart message (Content-Type message header is set to "multipart/mixed").

    • no to create a message based on the number of body parts in mimeData. This is the default.

      If the message contains only one body part, Content-Type is set according to the contenttype setting specified when that body part was added to mimeData.

      If the message contains multiple body parts, Content-Type is automatically set to "multipart/mixed."

Output parameters for getEnvelopeStream

  • envStream: java.io.InputStream - The MIME message as an InputStream.

  • mimeMessage: javax.mail.internet.MimeMessage. Conditional. This service returns a mimeMessage instead of an envStream if any of the body parts have data mimeMessage greater than the specified threshold.

Usage notes for getEnvelopeStream

This service operates on the MIME object (mimeData) produced by createMimeData.

If you omit index or contentID, getEnvelopeStream generates the MIME message from the entire contents of the mimeData. If you use index or contentID to select a body part that does not exist in mimeData, content will be null.

getEnvelopeStream automatically inserts the MIME-Version and Message-ID message headers into the MIME message it puts into envStream.

getMimeHeader

Returns the list of message headers from a specified MIME object.

Input parameters for getMimeHeader

  • mimeData: Document - MIME object whose message headers you want to retrieve (This IData object is produced by createMimeData).

Output parameters for getMimeHeader

  • mimeHeader: Document Conditional - An IData object containing the message headers. Key names represent the names of the header fields. The value of a key represents the value of the header fields. For example, if the original message contained the following message header fields:

     Message-ID: <002e01c0f150$6f33010a@sgx.com>
                            From: "Purch01@GSX.com" <Purch01@GSX.com>To:
                            <EXPEst@exprint.com>
                            MIME-Version: 1.0
                            Content-Type: text/xml
                            X-Doctype: RFQ
                            X-Severity: 0

    getMimeHeader would return the following:

    Key Value
    Message-ID <002e01c0f150$6f33010a@sgx.com>
    From "Purch01@GSX.com" <Purch01@GSX.com>
    To <EXPEst@exprint.com>
    MIME-Version 1.0
    Content-Type text/xml
    X-Doctype RFQ
    X-Severity 0

Usage notes for getMimeHeader

This service operates on the MIME object (mimeData) produced by createMimeData.

getNumParts

Returns the number of body parts in the specified MIME object.

Input parameters for getNumParts

  • mimeData: Document - MIME object whose parts you want to count (This IData object is produced by createMimeData).

Output parameters for getNumParts

  • numParts: String - The number of body parts in the MIME object.

Usage notes for getNumParts

This service operates on the MIME object (mimeData) produced by createMimeData.

getPrimaryContentType

Returns the top-level portion of a MIME object's Content-Type value.

Input parameters for getPrimaryContentType

  • mimeData: Document - MIME object whose Content-Type you want to discover (This IData object is produced by createMimeData).

Output parameters for getPrimaryContentType

  • primContentType: String - Message's top-level Content-Type. For example, if the message's Content-Type header were:

    • Content-Type: multipart/mixed

    primContentType would contain:

    • multipart

for getPrimaryContentType

This service operates on the MIME object (mimeData) produced by createMimeData.

getSubContentType

Returns the sub-type portion of a MIME object's Content-Type value.

Input parameters for getSubContentType

  • mimeData: Document - MIME object whose sub-type you want to discover (This IData object is produced by createMimeData).

Output parameters for getSubContentType

  • subContentType: String - Message's sub-type. For example, if the message's Content-Type header were:

    • Content-Type: multipart/mixed

    primContentType would contain:

    • mixed

Usage notes for getSubContentType

This service operates on the MIME object (mimeData) produced by createMimeData.

mergeHeaderAndBody

Concatenates the contents of the header and body mapped to the input.

You can use this service to reassemble the message into its original form so that it can be used as input to the createMimeData service (or any other service that requires the entire http response as an InputStream).

Input parameters for mergeHeaderAndBody

  • headerLines: Document - IData object containing the message headers (The message headers are returned in the lines document inside the header output parameter).

  • body: Document - IData object containing the body of the message. This document must contain the body of the message in one of the following keys:

    • bytes: byte[ ] Optional - Body of the message.

    • stream: java.io.InputStream Optional - The body of the message.

Output parameters for mergeHeaderAndBody

  • stream: java.io.InputStream - InputStream containing the reassembled tap message.

Usage notes for mergeHeaderAndBody

Use this service to merge the Headers and Body to get the original MIME message.

releaseBodyPartReferenceInTSpace

This service enables you to free up space in the Tspace by releasing body parts stored in it by the pub.mime:addBodyPart service. You need to provide a reference to the body part to be released.

Input parameters for releaseBodyPartReferenceInTSpace

mimeData: Document. MIME object whose reference you want to release from the Tspace. (This IData object is produced by pub.mime:createMimeData.)

index: String. Index number of the body part whose content you want to release (if you want to release the content from a specific body part). The first body part is index number zero. Note: If contentID is specified, index is ignored.

contentID: String. Value of the Content-ID header field of the body part that you want to release (if you want to release the payload from a specific body part).

Output parameters for releaseBodyPartReferenceInTSpace

releasedReferenceInTSpace: Boolean. Returns true if the reference was released and false if not.

Usage notes for releaseBodyPartReferenceInTSpace

Before invoking this service, ensure that the body part has a reference in the Tspace.