make-mime-part

Arguments: &key content-type encoding external-format headers attachmentp name text start end file subparts id description parameters charset

This function returns a mime-part-constructed object with properties as specified by the arguments. There are many examples using this function in MIME support in imap.htm.

Like many Lisp constructor functions, make-mime-part offers a lot of options and looks complicated but typically only a few of the many keyword arguments are actually necessary. make-mime-part supplies many defaults that are sufficient for the most common scenarios.

MIME parts have contents. The contents can be supplied in one of three ways: with the text argument, with the file argument, or with the subparts argument:

1. Using the text keyword argument: the text keyword argument specifies a string that will be used as the body of the new part. If one or both of the start and end keyword arguments are supplied, then the desired subsequence of the string will be used. The default content-type is "text/plain" when text is a string. See also the description of the external-format keyword argument.

   The text keyword argument can also be an (unsigned-byte 8) array. The subsequence of the array bounded by the start and end keyword arguments (specified) will be used. The default content-type is "application/octet-stream" when text is an (unsigned-byte 8) array.

2. Using the file keyword argument: the file keyword argument specifies a filename or an input stream that will be used to populate the body of new part. Note that the file/stream is not read until the part is rendered. If the argument is an input stream, it must be a stream that is capable of being read in an octet-oriented manner (e.g., it cannot be a string-input-stream). The default content-type will be deduced based on the specified filename or the filename associated with the input stream (if possible). If no specific content-type can be deduced, "application/octet-stream" will be used as the default. See also the description of the external-format keyword argument.
3. Using the subparts keyword argument: this only applies to multipart parts. The contents of a multipart part are simply other parts. The subparts argument should be a list of parts (as constructed by make-mime-part). The default content-type when subparts is specified is "multipart/mixed".

The start and end keyword arguments can be used to specify a subsequence of a text string to use. See the description of the text argument just above.

The remaining keyword arguments allow you to augment and override default settings for the new part:

• content-type is a string specifying the MIME content type of the part. Examples: "text/plain", "text/html", "multipart/mixed", "multipart/alternative", etc. If no content-type is supplied, a default is chosen based on the other arguments to the function. The descriptions of text/file/subparts above say how defaults are selected. If the content-type is text, make sure you supply the proper charset if necessary.
• The external-format keyword argument is only used if the content-type is a text type (i.e., a content type of the form text/<something> or message/rfc822. The default value is :utf-8. If the text of the part is being supplied from a file, make sure the external-format keyword argument corresponds to the external format of the file.
• encoding is a string specifying how the part contents should be encoded (after any external format processing). Valid choices are "7bit", "8bit", "base64" and "quoted-printable". The default encoding is selected according to the following rules:
  • If the :text keyword argument is supplied and is a string, then the string is converted to a usb8 array (using the external-format specified in the :external-format keyword argument, which defaults to :utf-8). The usb8 array is then scanned to see if there are any bytes with the high bit set. If there are, "base64" is selected as the encoding. Otherwise "7bit" is selected.
  • Otherwise, "base64" is selected.
• The attachmentp keyword argument controls the attachment disposition of the mime part. Generally, parts marked as "inline" are displayed (if possible) in the recipient's email client at their respective position within the messages. Parts marked as "attachment" are typically displayed as a link or button that the user must click on or otherwise manipulate in order to open, save, or view. Keep in mind that the attachment/inline disposition is only a suggestion and the behavior of email clients may vary with respect to the disposition. For content provided by file, the default disposition is "attachment". Otherwise, the default for non-text parts is "inline". The attachmentp keyword argument can be used to override the default. Note that text parts will never be marked "inline".
• name is a string specifying the name of an attachment. For attachments provided using the file keyword argument, the name defaults to the basename of the pathname associated with the file. To override the default, or to provide information when it cannot be automatically deduced, use this keyword argument.
• headers is an alist specifying additional headers that should be included with the part. This is most useful for specifying the standard email headers in the top level part (but see also send-letter for a simpler way to do this). The car of each entry should be a string naming the header. The cdr should be a string containing the contents of the header. For example: '(("Subject" . "This is a MIME-compliant message") ("Date" . "Mon, 9 Jan 2006 13:58:22 -0800")).
• id is a string specifying the id for this part. This data will be used to construct the Content-Id header of the part.
• description is a string specifying the description for this part. This data will be used to construct the Content-Description header of the part.
• The charset keyword argument is only used if the content-type is a text type (i.e., a content type of the form text/<something> or message/rfc822). The default charset is determined by the external-format keyword argument (which itself defaults to :utf-8), so in most cases, it should not be necessary to use this keyword argument. If specified, charset should be a string specifying a valid MIME charset.
• parameters is an alist specifying additional parameters that should be included in the Content-Type header for the part. The car of each entry should be a string naming the header. The cdr should be a string containing the contents of the header. For example: '(("format" . "flowed")).

See MIME support in imap.htm for more information. That section contains examples.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.