How to Create a MIME Message
The following procedure describes the general steps you take to create a MIME message.
1. Create an empty MIME object using pub.mime:createMimeData. You do not need to pass any input parameters to this service.
This service returns an empty MIME object named mimeData.
2. Add application-specific message headers with pub.mime:addMimeHeader. If your message requires application-specific (for example, “X- type” fields) or transport-specific message headers (for example, “To” and “From” header fields), use addMimeHeader to specify them. This service takes as input a document called mimeHeader, whose fields and values specify message header field names and values.
For example, this mimeHeader document...
Name | Values |
To | "xprint mEstimating" <EXPEst@exprint.com> |
From | "Purch01@GSX.com" <Purch01@GSX.com> |
X-Doctype | RFQ |
X-Severity | 5 |
...would produce the following message header fields:
Note that you do not need to explicitly set the following message headers:
Message-ID
MIME-Version
These headers are automatically generated by the service that produces the finished MIME message. If you explicitly set these fields in mimeHeader, they will be overwritten when the MIME message is generated.
You may set message headers before or after adding content (performing the next step 3, below). Either order is permitted, as long as you set them before you generate the finished MIME message.
Tip:
Instead of using addMimeHeader to add message headers, you may alternatively pass a mimeHeader document to createMimeData when you create the MIME object.
Besides a mimeHeader document, you must pass to addMimeHeader the mimeData object produced in the previous step 1.
The addMimeHeader service does not return an output value. It simply updates the mimeData object that you pass to it.
3. Add one or more body parts with the pub.mime:addBodyPart service. This service adds a single body part (both header fields and content) to the MIME object. To add multiple body parts, execute addBodyPart once for each part that you want to add. In the finished message, body parts appear in the order in which you add them—the first body part you add will be the first body part in the message.
Besides the mimeData object that you produced in step 1, addBodyPart takes three other parameters: content, contenttype, and encoding.
content is an InputStream containing the message content (the payload). Before invoking
addBodyPart, your solution must acquire or generate this content and place it in the pipeline as an InputStream.
The way in which you acquire the content of your message depends on your particular solution. For example, you might acquire it from a file or from a back-end system or manufacture it with a custom-built service. Regardless of how you acquire your content, keep the following points in mind:
Your content must exist as an InputStream in the pipeline. If it exists in some other form—for example, a String or a byte[]—you must convert it to an InputStream before adding it to the MIME object.
The InputStream should contain only the body of the message (the payload). Do not put header fields in the InputStream. To specify header fields, use the
contenttype,
encoding,
description, and
mimeHeader input parameters.
Note:
If your InputStream already contains header fields, you can set the
isEnvStream parameter to “true” to tell
addBodyPart to pull the header fields out of the InputStream before adding it to the MIME object. For additional information about using the
isEnvStream parameter, see
pub.mime:addBodyPart.
Do not encode the content before adding it to the MIME object—simply add it in its original form. If you want to encode the content for transport, set the
encoding parameter (see below).
contenttype is a String specifying the value of the entity’s Content-Type header field. Besides type and subtype, be sure to include any parameters that the header field requires as shown in the following example:
text/plain;charset=UTF8
Be aware that when you create a single-part message, the value you specify in contenttype is assigned to the Content-Type header for the entire MIME message. In this case, contenttype will override any value you may have previously set in mimeHeader (using the addMimeHeader service, for example.)
When you create a multipart message, the value you specify in contenttype is assigned to the Content-Type header for the body part. The Content-Type header for the entire MIME message is automatically set to multipart/mixed (or to multipart/subType if the subType parameter was specified when the MIME object was created.)
encoding is a String specifying the value of the entity’s Content-Transfer-Encoding header field. This field also specifies the scheme in which you want the entity’s content encoded. If you set
encoding to “base64,” for example, the
getEnvelopeStream service will base64-encode the data in
content when it generates the finished MIME message.
encoding must be one of the following values:
Value | Description |
7bit | Specifies that content is 7-bit, line-oriented text that needs no encoding. Use this value when content contains lines of 7-bit, US-ASCII text (no octets with decimal values greater than 127; no NULs). |
8bit | Specifies that content is 8-bit, line-oriented text that needs no encoding. Use this value when content contains lines of 8-bit text (octets with decimal values greater than 127; no NULs). Note:
This encoding value is not recommended for messages that will be transported via SMTP over the Internet, because intervening servers that cannot accommodate 8-bit text may alter your content. To safely transport 8-bit text, use quoted-printable encoding instead. |
binary | Specifies that content contains binary information that needs no encoding. Use this value when content contains an arbitrary sequence of octets (binary data). Note:
This encoding value is not recommended for messages that will be transported via SMTP over the Internet, because intervening servers that cannot accommodate binary data may alter your content. To safely transport binary data, use base64 encoding instead. |
quoted-printable | Specifies that content contains 7- or 8-bit, line-oriented text that you want to encode using the quoted printable encoding scheme. |
base64 | Specifies that content contains an arbitrary sequence of octets (binary data) that you want to encode using the base64 encoding scheme. |
uuencode | Specifies that content contains an arbitrary sequence of octets that you want to encode using the uuencode encoding scheme. |
Be aware that when you create a single-part message the value you specify in encoding is assigned to the Content-Transfer-Encoding header for the entire MIME message. This value will override any value you may have previously set in mimeHeader (using the addMimeHeader service, for example).
When you create a multipart message, the value you specify in encoding is assigned to the Content-Transfer-Encoding header for the 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, this header defaults to 7bit encoding. (7bit, 8bit, and binary are the only encoding values valid for multipart messages.)
Note:
Besides the
content,
contenttype, and
encoding, parameters described above, the
addBodyPart service has a few other optional parameters you can use. For information about these parameters, see
pub.mime:addBodyPart.
The addBodyPart service does not return an output value. It simply updates the mimeData object that you pass to it.
4. Generate the finished MIME message with the pub.mime:getEnvelopeStream service. After you finish populating the MIME object, invoke getEnvelopeStream to generate a MIME message. This service takes the populated mimeData object and produces an InputStream called envStream, containing the finished MIME message.
When getEnvelopeStream generates a MIME message, it does the following:
Generates the Message-ID, MIME-Version, Content-Type, and Content-Transfer-Encoding message headers and inserts them at the top of the message.
Sets the Content-Type header to “multipart,” generates a boundary string, and inserts it between body parts if
mimeData contains multiple body parts.
Note:
If mimeData contains a single body part, getEnvelopeStream will, by default, create an ordinary, single-part message. Some solutions, however, want a “multipart” message even if the message contains only a single body part. If your solution requires this structure, you can use the createMultipart parameter to tell getEnvelopeStream to generate a multipart message regardless of the number of body parts it finds in mimeData.
Encodes the content for each body part according to its
encoding value.