MIME-CONSTRUCT(1p)

📦
version 1.11 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

💖 MIME-CONSTRUCT(1p) 💖

okay bestie, gather round, because this is mime-construct from the User Contributed Perl Documentation section, and she is that girl. 💅

✨ NAME ✨

mime-construct — construct and optionally mail MIME messages 🦋

✨ SYNOPSIS ✨

mime-construct switch...

ngl, there is no cute tidy synopsis for this one. straight from the source: Sorry, it's hard to provide a meaningful synopsis. See the examples. 😭 the examples are the moment, fr fr.

✨ DESCRIPTION ✨

mime-construct constructs MIME messages, and by default it also mails them. 💌

It is entirely driven from the command line. It was designed to be used by other programs — or by people who act like programs. 👑 no GUI, no config file, just vibes and flags.

✨ OPTIONS ✨

🌸 Global Settings 🌸

  • --debug — turns debugging on. 🔍
  • --help — shows you the usage message and then dies. dramatic exit, we love to see it 💀
  • --output — don't mail the generated message, just print it to stdout instead. heads up tho: this loses --bcc info. 🙈
  • --subpart — generate a subpart that can be dropped into another MIME message, instead of being a top-level MIME message itself. This turns on --output and changes some internal semantics a bit. peek the examples for the full picture. ✨
  • --version — print the version and exit successfully, but only if this is the sole arg. Otherwise it prints the version and dies. 💀 okay queen

💌 Main Header 💌

These arguments add text to the top-level header of the message, or control who it gets sent to. 🫶

  • --bcc address — add address to the recipient list. It doesn't actually add anything to the header, obviously. And if you're not actually mailing the message (so: if you use --output or --subpart) then --bcc will have no effect at all. 💀
  • --cc address — add an address to the Cc: list.
  • --embedded-to — send the message to the recipients already listed in the header, in addition to the ones you gave with --to, --cc, and --bcc. This makes sense if you use the --header switch to add your own To: or Cc:. In that case you probably don't want --to or --cc, because they'd create brand new headers instead of adding to the ones already in the message. This switch passes the -t switch to sendmail (mime-construct does not try to parse the headers you provide), so it doesn't really do anything if you're not mailing the message. 🤷
  • --header str — add arbitrary text to the header. str can be literally anything you like, including multiple lines. You can create invalid messages this way. And if you include a blank line in str you'll really screw up the message. 😭
  • --multipart str — specifies the multipart content type and options. Default is multipart/mixed. Do not include a boundary setting, that's supplied by mime-construct. It's fine if you specify the --multipart type but the message turns out to be a single part — the type you supplied just gets ignored. 🎀
  • --prelude str — adds str to the multipart prelude text. If you specify --prelude multiple times, all the *str*s get concatenated. There isn't any default for this text. And honestly? adding an explanation of MIME to the start of a message is like explaining how to use a seat buckle to people riding in an airplane. 🛩️ It's fine if you specify --prelude but the message turns out to be a single part — your prelude just gets ignored.
  • --subject str — specify the subject for the message.
  • --to address — add an address to the To: list.

🌈 Per-part Header 🌈

These switches control the per-part headers. And plot twist: if the message turns out not to be multipart, they actually add data to the top level header. 🙈

Each of these applies only to the next part output. After each part is output, they reset to their default values. And it doesn't make sense to use them without a following part — so if you try it, mime-construct will sputter and die. 💀 periodt.

  • --attachment name — adds a Content-Disposition: attachment header, with the given name as the value of the filename attribute. It's just a convenience, since mime-construct is often used to send files as attachments. But listen: using --attachment name does not cause mime-construct to read any data from the file called name! It just uses that name in the header. The actual data that goes into this part comes from one of the regular part output switches (below ⬇️). You might prefer --file-attach, which does read from the named file. 🍓
  • --encoding type — specifies the type of encoding you want this part to use. You normally shouldn't use this switch tho. If you don't use it, mime-construct will choose an appropriate encoding for you. 🧚 The data you supply mustn't already be encoded — mime-construct will encode it according to the type you specify here. Valid encodings are 7bit, 8bit, binary, quoted-printable, and base64. It's easy to generate an illegal MIME message by specifying the encoding yourself. 😬
  • --part-header str — add arbitrary text to the per-part header. str can be anything you like, including multiple lines. You can create invalid messages this way. If you include a blank line in str you'll really screw up the message. 😭
  • --type type — specify the content type for this part. If you don't specify a --type, it defaults to text/plain. The type you supply can contain not only the type proper but also options — the whole thing just gets plopped onto the end of Content-Type: and stuck into the header. 🎀 You might prefer --file-auto or --file-attach, which set the --type automatically based on a file's name.

🦋 Part Output 🦋

These switches add data to the body of the message. You use one of these for each part of a multipart message (or just one of them if the message isn't going to be multipart).

  • --file path
  • --file-auto path
  • --file-attach path
  • --attach path
  • --string str
  • --body str

Use the contents of the file path, or the literal string str, as the body of this part. 💖

--file-auto causes the Content-Type to be set based on the file's name, if possible. ✨

--file-attach does that and sets the --attachment name as well. 🎀

Be sure to include the trailing newline on str, unless there really isn't supposed to be one. If you leave the trailing newline off, the part will have to be encoded in base64 (because quoted-printable has an artificial limitation which prevents it from being able to encode such a data stream). 😭

--attach is an alias for --file-attach, and --body is an alias for --string. 💅

  • --subpart-file path
  • --subpart-string str

Use either the contents of path or str itself as the body of this part, but treat it as a subpart. This means the data contains both some headers and some text. It also means you can't use --type or --encoding for this part. 🙈 Normally the path or str will have been generated by a different invocation of mime-construct which was given the --subpart switch.

Arguments to switches which take a file name (like --file and --subpart-file) can have some magic ✨. If there is no file with the path supplied, a regular Perl open() is done on it. See EXAMPLES.

✨ EXAMPLES ✨

These examples assume that $nl contains a newline. The other variables used are, I hope, self-explanatory. 🫶

Send a simple message.

mime-construct --to "$recip" --subject 'hi there' --string "$body"

Send a message which is read from stdin.

fortune | mime-construct --to "$recip" --subject fortune --file -

Send a plain text part and attach a file, setting the file's content type and --attachment name automatically.

mime-construct --to "$recip" --subject "$file" \
    --string "Here's the file I told you about.$nl" \
    --file-attach "$file"

Most people think of attachments as multipart messages, but they don't have to be. This generates a zip of all the files in the current directory and sends them as an attachment, but as a single part message. 🔥

zip -q - * |
    mime-construct --to "$recip" --subject 'zipped directory' \
        --attachment dir.zip --type application/zip --file -

You can use the full expressiveness of Perl's open() when constructing file names. Eg, you can run processes — XXX bad examples, there's no file names:

mime-construct --to "$recip" --subject "$subject" \
 --string "Here are those two files you wanted.$nl" \
 --type application/x-gzip --attachment file1.gz --file 'gzip -c file1 |' \
 --type application/x-gzip --attachment file1.gz --file 'gzip -c file2 |'

or read from alternate file descriptors ("<&=4" to read from file descriptor 4) or whatever. See perlopentut for a tutorial. 🧚

Here's an example of using a separate invocation of mime-construct to create a subpart. This creates a message which has two parts at the top level. The first part is some text, the second part is a digest. The digest itself is a multipart message which contains a number of message/rfc822 parts.

msg_args=
for msg in $msg_list
do
    msg_args="$msg_args --type message/rfc822 --file $msg"
done

set fnord
for recip in $recip_list
do
    set "$@" --bcc $recip
done
shift

mime-construct --subpart --multipart multipart/digest $msg_args |
    mime-construct \
        --header "To: Digest recipients:;$nl" \
        --subject 'Foo digest' \
        "$@" \
        --file "$introduction" \
        --subpart-file -

Here is how to send an encrypted message (multipart/encrypted, as defined in RFC 1847). You use mime-construct "--subpart" to generate the real message you want to send (which can be kind of MIME message — non-text, multi-part, what have you), then encrypt that and use another mime-construct to construct and send the multipart/encrypted message which contains it. 🔐

enc_type=application/pgp-encrypted
enc_params="Version: 1$nl"

mime-construct --subpart --file body --file-auto image.jpg |
  gpg --encrypt --armor -r "$recip" |
  mime-construct --output \
    --to "$recip" \
    --subject "$subject" \
    --multipart "multipart/encrypted; protocol=\"$enc_type\"" \
    --type "$enc_type" \
    --string "$enc_params" \
    --type application/octet-stream \
    --file -

✨ BUGS ✨

The body of the message is always held in memory, so you can expect problems if you work with bodies which are large compared to the amount of memory you've got. 😭 girl, be careful.

✨ AVAILABILITY ✨

The code is licensed under the GNU GPL. Check http://www.argon.org/~roderick/ for updated versions. 🌈

✨ AUTHOR ✨

Roderick Schertler <roderick@argon.org> 👑

and that's the whole page, bestie!! this was perl v5.36.0, dated 2023-01-06, from the MIME-CONSTRUCT(1p) manual — mwah, iconic, no notes 💅💖✨

📦 where this page comes from