1MAKEMIME(1)                 Double Precision, Inc.                 MAKEMIME(1)
2
3
4

NAME

6       makemime - Create MIME-formatted messages
7

SYNOPSIS

9       makemime [options...]
10
11       makemime [@filename]
12

DESCRIPTION

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
22       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
27       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
31       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
35       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
44       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
52   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
63       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
74       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
82       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
88       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
97       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
105       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
116   Creating a single MIME section
117       makemime {-c "type"} [-e "encoding"] [-o outputfile] [-C "charset"]
118                [-N "name"] [-a "header: value"...] {filename}
119
120       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
126       The -C option sets the MIME charset attribute for text/plain content.
127       The -N option sets the name attribute for Content-Type:.
128
129       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
133       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
140       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
144       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
148       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
155       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
159       Note
160       The -c option must occur listed first, the remaining options must
161       follow the -c option.
162
163   Creating a multipart MIME collection
164       makemime {-m "multipart/type"} [-e "encoding"] [-o outputfile]
165                [-a "header: value"...] {filename}
166
167       The -m option is identical to the -c option, except for three
168       differences.
169
170       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
178       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
182   Creating a multipart MIME section
183       makemime {-j file1"} [-o outputfile] {file2}
184
185       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
192       file1 and/or file2 may be "@&n" which reads from file descriptor #n.
193       The outputfile may also specify a file descriptor.
194
195       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
205   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
213       1. Create a MIME collection that has a text/plain and a text/html MIME
214       section.
215
216       2. Create a MIME collection consisting of the MIME section generated in
217       step one, plus additional MIME sections containing other attachments.
218
219       For example:
220
221           # Take two files containing the text and the html version of a message, and
222           # add MIME headers to them.
223
224           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
227           # Combine the result into a multipart/alternative collection
228
229           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
233           # Add MIME headers to an image attachment.
234
235           makemime -c "image/gif" -a "Content-Disposition: attachment" \
236                                   -o tmp2.gif attachment.gif
237
238           # Create the final multipart/mixed collection
239
240           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
244       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
248   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
256       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
262       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
272           makemime -j \(                                           \
273                          -m "multipart/alternative"                \
274                          -a "Content-Disposition: inline" tmp1.txt \
275                        \) -o tmp.ma2                               \
276                        tmp1.html
277
278       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
282           -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
294       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
298           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
325       An equivalent argument file would be:
326
327           -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

SEE ALSO

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

REFERENCES

369        1. RFC 2045
370           http://www.rfc-editor.org/rfc/rfc2045.txt
371
372        2. RFC 2046
373           http://www.rfc-editor.org/rfc/rfc2046.txt
374
375        3. RFC 2047
376           http://www.rfc-editor.org/rfc/rfc2047.txt
377
378        4. RFC 2048
379           http://www.rfc-editor.org/rfc/rfc2048.txt
380
381        5. maildrop(1)
382           maildrop.html
383
384        6. maildropfilter(5)
385           maildropfilter.html
386
387        7. reformail(1)
388           reformail.html
389
390        8. reformime(1)
391           reformime.html
392
393        9. courier(8)
394           courier.html
395
396
397
398Double Precision, Inc.            04/22/2007                       MAKEMIME(1)
Impressum