1MAKEMIME(1) Double Precision, Inc. MAKEMIME(1)
2
6 makemime - Create MIME-formatted messages
7
9 makemime [options...]
10 makemime [@filename]
12
14 makemime creates MIME-formatted messages of arbitrary complexity.
15 makemime reads one or more individual files, MIME-encodes them, adds
16 basic MIME headers, and adds any additional headers specified bye
17 command line options. The result is saved to another file or standard
18 output. Complex MIME-formatted messages are created by piping together
19 multiple instances of makemime. Advanced options direct makemime to
20 fork() itself, and handle the details of setting up all the pipelines.
21 In most cases, options for makemime come directly from the command
23 line. @filename reads the options from a file. "@&n" reads options from
24 a pipe on file descriptor #n. "@-" is a shortcut for "@&0", which reads
25 options from standard input.
26 When options are read from a file or a pipe, each option must be on a
28 line by itself. If an option requires an argument, the argument must
29 follow on the next line.
30 For readability, leading whitespace is deleted when options are read
32 from a file or a pipe. Empty lines are also ignored, as well as lines
33 that begin with the '#' character.
34 Options and their arguments may contain characters that are special
36 characters to the shell, such as '(' and ')'. These characters must be
37 backslashed when specified on the command line, to avoid their special
38 meaning to the shell. These characters MUST NOT be backslashed when
39 options are read from a file or a pipe. Similarly, the contents of most
40 headers nearly always include spaces. Therefore they must be quoted
41 when specified on the command line. Header contents MUST NOT be quoted
42 when options come from a file or a pipe.
43 makemime reads the content to be formatted as a MIME message from some
45 other file. The files can also be a pipe. It is possible to supply both
46 the options and a file from the same pipe, by terminating the options
47 list with a line containing the single character "-". The remainder of
48 the pipe will be available to be used as an input file (which must be
49 explicitly specified by one of the options). Of course, only one input
50 file can come from a single pipe.
51 MIME overview
53 A MIME-formatted message contains one or several MIME sections. MIME
54 headers specify how multiple MIME sections are to be interpreted as a
55 whole (whether they are attached together; whether they are alternative
56 representations of the same content; or something even more esoteric).
57 This manual page gives a very brief, terse, overview of basic MIME
58 concepts. The description is biased towards describing the
59 functionality of the makemime utility. See RFC 2045[1], RFC 2046[2],
60 RFC 2047[3], RFC 2048[4], and RFC 2049[4] for a formal definition of
61 MIME-formatted messages.
62 Each file in a MIME message is encoded as a single MIME section. A MIME
64 section consists of at least one header line, "Content-Type:". The
65 "Content-Type:" header gives the type of the data ontained in the file.
66 Other header lines may also be present. Their relative order does not
67 matter. MIME headers are followed by a blank line, then the contents of
68 the file, encoded appropriately. All MIME sections generated by
69 makemime will always contain another header,
70 "Content-Transfer-Encoding:". This header gives the encoding method
71 used for the file; it is an optional header, but makemime always
72 creates it.
73 The MIME encoding method defaults to "7bit" if this header is absent.
75 7bit encoding is only suitable for plain text messages in the US-ASCII
76 character set. The "8bit" encoding method is used by plain text
77 messages in other character sets that use octets with the high bit set.
78 An alternative to 8bit encoding is "quoted-printable". The "base64"
79 encoding method is used for files containing binary data (anything
80 other than plain text).
81 MIME sections that contain text messages have their "Content-Type:"
83 header set to "text/plain"; or "text/html" for HTML messages. There are
84 also several other, rare, content types that can be used. MIME sections
85 that contain other kinds of data will use some other, appropriate
86 "Content-Type:" header, such as "image/gif", or "audio/x-wav".
87 MIME sections that contain textual content may also use the base64
89 encoding method, they are not required to use 7bit, 8bit, or
90 quoted-printable. "text/pdf" sections, that contain PDF files,
91 typically contain binary data and must use the base64 encoding.
92 Consequently, MIME sections that typically contain binary data, such as
93 image/gif and audio/x-wav, are free to use encodings other than base64,
94 as long as all the data can be represented by printable characters
95 (but, in practice, that never happens).
96 MIME sections may also contain other, optional, headers such as
98 "Content-Disposition:", "Content-ID:", and "Content-Name:". Consult the
99 appropriate RFCs for the specific usage of these headers. These headers
100 can be added by makemime by using the -a option, as described below.
101 These headers play no part in creating the overall structure of a
102 MIME-encoded message, and makemime does not care much about these
103 headers. It simply includes them, and their content, upon request.
104 Multiple files are formatted as a single message MIME message in two
106 steps: first, by creating a MIME section for each file; and then
107 creating a single MIME section that contains other MIME sections. A
108 "multipart/mixed" MIME section contains a collection of MIME sections
109 that represent different objects, attached together. A
110 "multipart/alternative" MIME section contains a collection of MIME
111 sections which are alternative representations of the same object, such
112 as an HTML and a plain text version of the same message. Other
113 "multipart" MIME sections also exist, and their usage is defined by
114 their respective RFCs.
115 Creating a single MIME section
117 makemime {-c "type"} [-e "encoding"] [-o outputfile] [-C "charset"]
118 [-N "name"] [-a "header: value"...] {filename}
119 The -c option reads filename, encodes it appropriately, adds the
121 "Content-Type: type" and "Content-Transfer-Encoding:" MIME headers,
122 then writes the result to standard output. type can be any valid MIME
123 type, except for multipart. Setting filename to "-" reads from standard
124 input. Setting filename to "&n" reads from file descriptor #n.
125 The -C option sets the MIME charset attribute for text/plain content.
127 The -N option sets the name attribute for Content-Type:.
128 encoding argument should be specified. It's more efficient to do so.
130 encoding must be one of the following: 7bit, 8bit, quoted-printable, or
131 base64.
132 If encoding is not specified, makemime reads the filename twice - once
134 to figure out the best encoding method, and the second time to encode
135 filename. If filename is a pipe makemime creates a temporary file,
136 which is not very efficient if filename is large. However letting
137 makemime pick the encoding method is more convenient if filename is
138 relatively small.
139 Another possibility is to omit encoding and set type to auto. This
141 combination sets "Content-Type:" to either text/plain, or
142 application/octet-stream, based on the selected encoding.
143 By default the encoded MIME section is written to standard output. The
145 -o option writes the MIME section to outputfile. outputfile may be
146 "&n", which writes the MIME section to a pipe on file descriptor #n.
147 makemime does not generate any other headers. Particularly, the
149 "Mime-Version:" header is required for MIME-formatted E-mail messages.
150 Additional headers are specified by the -a option, which may be used
151 multiple times to insert multiple headers. makemime doesn't do
152 anything with them except to insert the headers into the generated MIME
153 section.
154 Note that "Mime-Version:" is only required for the top level MIME
156 section. This header is not required for individual MIME sections that
157 are later combined into a multipart MIME collection.
158 Note
160 The -c option must occur listed first, the remaining options must
161 follow the -c option.
162 Creating a multipart MIME collection
164 makemime {-m "multipart/type"} [-e "encoding"] [-o outputfile]
165 [-a "header: value"...] {filename}
166 The -m option is identical to the -c option, except for three
168 differences.
169 type must be either "multipart/mixed", "multipart/alternative", or some
171 other MIME multipart content type. Additionally, "encoding" can only be
172 "7bit" or "8bit", and will default to "8bit" if not specified. Finally,
173 filename must be a MIME-formatted section, NOT a regular file. Usually
174 filename is created by a previous invocation of makemime (it can also
175 be a pipe, like the -c option), but it can be created via any other
176 means.
177 The -m option creates an initial multipart MIME collection, that
179 contains only one MIME section, taken from filename. The collection is
180 written to standard output, or the pipe or to outputfile.
181 Creating a multipart MIME section
183 makemime {-j file1"} [-o outputfile] {file2}
184 This option adds a MIME section to an existing MIME collection. file1
186 must be a MIME collection that was previously created by the -m option.
187 file2 must be a MIME section that was previously created by the -c
188 option. The -j options adds the MIME section in file2 to the MIME
189 collection in file1. The result is written to standard output or to
190 outputfile.
191 file1 and/or file2 may be "@&n" which reads from file descriptor #n.
193 The outputfile may also specify a file descriptor.
194 file1 and file2 should ideally be created by makemime as well. It's
196 also possible to use MIME-formatted files created by other software,
197 but with some degree of care. makemime is not intended to be a MIME
198 parser, but a MIME generator. However some amount of MIME parsing is
199 necessary to append a MIME section to an existing MIME collection.
200 makemime's parsing is sufficient for appending a new section to a MIME
201 collection, as long as the MIME headers in the MIME collections are
202 straightforward. Very convoluted MIME headers may confuse makemime, and
203 it may not be able to handle them.
204 Recursive MIME collections
206 MIME collection may contain other MIME collections as well as MIME
207 sections. The -m and the -j options may use a multipart MIME collection
208 in place of a MIME section automatically because a multipart MIME
209 collection is just a special type of a MIME section. The following
210 example encodes a text message that can be alternatively represented as
211 HTML or plain text, with some additional attachments:
212 1. Create a MIME collection that has a text/plain and a text/html MIME
214 section.
215 2. Create a MIME collection consisting of the MIME section generated in
217 step one, plus additional MIME sections containing other attachments.
218 For example:
220 # Take two files containing the text and the html version of a message, and
222 # add MIME headers to them.
223 makemime -c "text/plain; charset=iso-8859-1" -o tmp1.txt msg.txt
225 makemime -c "text/html; charset=iso-8859-1" -o tmp1.html msg.html
226 # Combine the result into a multipart/alternative collection
228 makemime -m "multipart/alternative" -a "Content-Disposition: inline" \
230 -o tmp.ma1 tmp1.txt
231 makemime -j tmp.ma1 -o tmp.ma2 tmp1.html
232 # Add MIME headers to an image attachment.
234 makemime -c "image/gif" -a "Content-Disposition: attachment" \
236 -o tmp2.gif attachment.gif
237 # Create the final multipart/mixed collection
239 makemime -m "multipart/mixed" -a "Mime-Version: 1.0" \
241 -o tmp.mm1 tmp.ma2
242 makemime -j tmp.mm1 -o output.msg tmp2.gif
243 output.msg now contains the complete MIME collection. Just add the
245 Subject:, From:, and To: headers (can also be done by additional -a
246 options, of course), and send it on its way.
247 Building complex MIME encodings
249 There are several different ways to build complete MIME encodings from
250 multiple MIME sections. One way is to use temporary files to create
251 MIME sections, then combine them together into a single MIME
252 collection. A slightly more complicated approach involves setting up
253 pipes between multiple makemime processes, in order to avoid using
254 temporary files.
255 This can be done manually, by hand. It is also possible to have
257 makemime do this automatically. makemime will set up these pipes and
258 run multiple instances of itself to create a single MIME collection,
259 with multiple attachments of complexity limited only by your system's
260 limit on the maximum number of open files and pipes.
261 Any file that's read by the -c, -m, and -j options ( -o specifies a
263 file to create, and doesn't count) may be replaced by a single argument
264 containing a left parenthesis, additional options, then a single
265 argument containing a right parenthesis. A single invocation of
266 makemime can only use one -c, -m, or -j option. However, another -c,
267 -m, or -j option may be specified inside the left and the right
268 parenthesis, and its output is used in place of the file it replaced.
269 In the previous example the third and the fourth invocation of makemime
270 can be replaced with the following command:
271 makemime -j \( \
273 -m "multipart/alternative" \
274 -a "Content-Disposition: inline" tmp1.txt \
275 \) -o tmp.ma2 \
276 tmp1.html
277 Note that the parenthesis must be backslashed, to avoid their special
279 meaning to the shell. An equivalent argument file would have the
280 following contents:
281 -j
283 (
284 -m
285 multipart/alternative
286 -a
287 Content-Disposition: inline
288 tmp1.txt
289 )
290 -o
291 tmp.ma2
292 tmp1.html
293 These constructs can be arbitrarily nested, and are limited by the
295 amount of available memory and resources. The entire sequence in the
296 previous section is equivalent to the following command:
297 makemime -j \
299 \( \
300 -m "multipart/mixed" \
301 -a "Mime-Version: 1.0" \
302 \( \
303 -j \
304 \( \
305 -m "multipart/alternative" \
306 -a "Content-Disposition: inline" \
307 \( \
308 -c "text/plain; charset=iso-8859-1" \
309 msg.txt \
310 \) \
311 \) \
312 \( \
313 -c "text/html; charset=iso-8859-1" \
314 msg.html \
315 \) \
316 \) \
317 \) \
318 -o output.msg \
319 \( \
320 -c "image/gif" \
321 -a "Content-Disposition: attachment" \
322 attachment.gif \
323 \)
324 An equivalent argument file would be:
326 -j
328 (
329 -m
330 multipart/mixed
331 -a
332 Mime-Version: 1.0
333 (
334 -j
335 (
336 -m
337 multipart/alternative
338 -a
339 Content-Disposition: inline
340 (
341 -c
342 text/plain; charset=iso-8859-1
343 msg.txt
344 )
345 )
346 (
347 -c
348 text/html; charset=iso-8859-1
349 msg.html
350 )
351 )
352 )
353 -o
354 output.msg
355 (
356 -c
357 image/gif
358 -a
359 Content-Disposition: attachment
360 attachment.gif
361 )
362
364 maildrop(1)[5], maildropfilter(5)[6], reformail(1)[7], reformime(1)[8],
365 egrep(1), grep(1), courier(8)[9], sendmail(8), RFC 2045[1], RFC
366 2046[2], RFC 2047[3], RFC 2048[4], RFC 2049[4].
367
369 1. RFC 2045
370 http://www.rfc-editor.org/rfc/rfc2045.txt
371 2. RFC 2046
373 http://www.rfc-editor.org/rfc/rfc2046.txt
374 3. RFC 2047
376 http://www.rfc-editor.org/rfc/rfc2047.txt
377 4. RFC 2048
379 http://www.rfc-editor.org/rfc/rfc2048.txt
380 5. maildrop(1)
382 maildrop.html
383 6. maildropfilter(5)
385 maildropfilter.html
386 7. reformail(1)
388 reformail.html
389 8. reformime(1)
391 reformime.html
392 9. courier(8)
394 courier.html
395Double Precision, Inc. 04/22/2007 MAKEMIME(1)