4 mimedecode -- decode MIME message
9 mimedecode [ -h|--help ] [ -V|--version ] [ -cCDP ] [ -f charset ]
10 [ -H|--host=hostname ] [ -d header1[,header2,header3...] ]
11 [ -d \*[,-header1,-header2,-header3...] ]
12 [ -p header1[,header2,header3,...]:param1[,param2,param3,...] ]
13 [ -p \*[,-header1,-header2,-header3,...]:param1[,param2,param3,...] ]
14 [ -p header1[,header2,header3,...]:\*[,-param1,-param2,-param3,...] ]
15 [ -p \*[,-header1,-header2,-header3,...]:\*[,-param1,-param2,-param3,...] ]
16 [ -r header1[,header2,header3...] ] [ -r \*[,-header1,-header2,-header3...] ]
17 [ -R header1[,header2,header3,...]:param1[,param2,param3,...] ]
18 [ -R \*[,-header1,-header2,-header3,...]:param1[,param2,param3,...] ]
19 [ -R header1[,header2,header3,...]:\*[,-param1,-param2,-param3,...] ]
20 [ -R \*[,-header1,-header2,-header3,...]:\*[,-param1,-param2,-param3,...] ]
21 [ --set-header header:value ] [ --set-param header:param=value ]
22 [ -BbeIit mask ] [ --save-headers|body|message mask ] [ -O dest_dir ]
23 [ -o output_file ] [input_file [output_file] ]
28 Mail users, especially in non-English countries, often find that mail
29 messages arrived in different formats, with different content types, in
30 different encodings and charsets. Usually it is good because it allows to
31 use an appropriate format/encoding/whatever. Sometimes, though, some
32 unification is desirable. For example, one may want to put mail messages
33 into an archive, make HTML indices, run search indexer, etc. In such
34 situations converting messages to text in one character set and skipping
35 some binary attachments is much desirable.
37 Here is a solution - mimedecode!
39 This is a program to decode MIME messages. The program expects one input
40 file (either on command line or on stdin) which is treated as an RFC822
41 message, and decodes to stdout or an output file. If the file is not an
42 RFC822 message it is just copied to the output one-to-one. If the file is
43 a simple RFC822 message it is decoded as one part. If it is a MIME message
44 with multiple parts ("attachments") all non-multipart subparts are
45 decoded. Decoding can be controlled by the command-line options.
47 First, for every part the program removes headers and parameters listed
48 with -r and -R options. Then, Subject and Content-Disposition headers (and
49 all headers listed with -d and -p options) are examined. If any of those
50 exists, they are decoded according to RFC2047. Content-Disposition header
51 is not decoded (if it was not listed in option -d) - only its "filename"
52 parameter. Encoded header parameters violate the RFC, but widely deployed
53 anyway by ignorant coders who never even heard about RFCs. Correct
54 parameter encoding specified by RFC2231. This program decodes
55 RFC2231-encoded parameters, too.
57 Then the body of the message (or the current part) is decoded. Decoding
58 starts with looking at header Content-Transfer-Encoding. If the header
59 specifies non-8bit encoding (usually base64 or quoted-printable), the body
60 is converted to 8bit (can be prevented with -B). Then if its content type
61 is multipart (multipart/related or multipart/mixed, e.g) every part is
62 recursively decoded. If it is not multipart, mailcap database is consulted
63 to find a way to convert the body to plain text (can be prevented with
64 options -Bbei). (The author has no idea how mailcap can be configured on
65 OSes other than POSIX, please don't ask; users can consult an example at
66 https://phdru.name/Software/dotfiles/mailcap.html). The decoding process
67 uses the first copiousoutput filter it can find. If there are no filters
68 the body just passed as is.
70 Then Content-Type header is consulted for charset. If it is not equal to
71 the current locale charset and recoding is allowed (see options -Cc) the
72 body text is recoded. Finally message headers and the body are flushed to
75 Please be reminded that in the following options asterisk is a shell
76 metacharacter and should be escaped or quoted. Either write -d \*,-h1,-h2
77 or -d '\*,-h1,-h2' or such.
84 Print brief usage help and exit.
88 Print version and exit.
92 Recode different character sets in message bodies to the current
93 default charset; this is the default.
97 Do not recode character sets in message bodies.
101 Force this charset to be used for recoding instead of charset from
104 -H hostname, --host=hostname
106 Use this hostname in X-MIME-Autoconverted headers instead of the
109 -d header1[,header2,header3...]
111 Add the header(s) to a list of headers to decode; initially the
112 list contains headers "From", "To", "Cc", "Reply-To",
113 "Mail-Followup-To" and "Subject".
115 -d \*[,-header1,-header2,-header3...]
117 This variant completely changes headers decoding. First, the list
118 of headers to decode is cleared (as with -D). Then all the headers
119 are decoded except the given list of exceptions (headers listed
120 with '-'). In this mode it would be meaningless to give more than
121 one -d options but the program doesn't enforce the limitation.
125 Clear the list of headers to decode (make it empty).
127 -p header1[,header2,header3,...]:param1[,param2,param3,...]
129 Add the parameter(s) to a list of headers parameters to decode;
130 the parameter(s) will be decoded only for the given header(s).
131 Initially the list contains header "Content-Type", parameter
132 "name"; and header "Content-Disposition", parameter "filename".
134 -p \*[,-header1,-header2,-header3,...]:param1[,param2,param3,...]
136 Add the parameter(s) to a list of headers parameters to decode;
137 the parameter(s) will be decoded for all headers except the given
140 -p header1[,header2,header3,...]:\*[,-param1,-param2,-param3,...]
142 Decode all parameters except listed for the given list of headers.
144 -p \*[,-header1,-header2,-header3,...]:\*[,-param1,-param2,-param3,...]
146 Decode all parameters except listed for all headers (except
151 Clear the list of headers parameters to decode (make it empty).
153 -r header1[,header2,header3...]
155 Add the header(s) to a list of headers to remove completely;
156 initially the list is empty.
158 -r \*[,-header1,-header2,-header3...]
160 Remove all headers except listed.
162 -R header1[,header2,header3,...]:param1[,param2,param3,...]
164 Add the parameter(s) to a list of headers parameters to remove;
165 the parameter(s) will be removed only for the given header(s).
166 Initially the list is empty.
168 -R \*[,-header1,-header2,-header3,...]:param1[,param2,param3,...]
170 -R header1[,header2,header3,...]:\*[,-param1,-param2,-param3,...]
172 -R \*[,-header1,-header2,-header3,...]:\*[,-param1,-param2,-param3,...]
174 Remove listed parameters (or all parameters except listed) from
175 these headers (or from all headers except listed).
177 --set-header header:value
179 The program sets or changes value for the header to the given
180 value (only at the top-level message).
182 --set-param header:param=value
184 The program sets or changes value for the header's parameter to
185 the given value (only at the top-level message). The header must
190 Append mask to the list of binary content types that will be not
191 content-transfer-decoded (will be left as base64 or such).
195 Append mask to the list of binary content types; if the message to
196 decode has a part of this type the program
197 content-transfer-decodes (base64 or whatever to 8bit binary) it
198 and outputs the decoded part as is, without any further
203 Append mask to the list of error content types; if the message to
204 decode has a part of this type the program fails with ValueError.
208 Append mask to the list of content types to completely ignore.
209 There will be no output - no headers, no body, no warning. For a
210 multipart part the entire subtree is removed.
214 Append mask to the list of content types to ignore; if the message
215 to decode has a part of this type the program outputs headers but
216 skips the body. Instead a line "Message body of type %s skipped."
221 Append mask to the list of content types to convert to text; if
222 the message to decode has a part of this type the program consults
223 mailcap database, find the first copiousoutput filter and, if any
224 filter is found, converts the part.
232 Append mask to lists of content types to save to files;
233 --save-headers saves only decoded headers of the message (or the
234 current subpart); --save-body saves only decoded body;
235 --save-message saves the entire message or subpart (headers +
240 Set destination directory for the output files; if the directory
241 doesn't exist it will be created. Default is the current
246 Save output to the file related to the destination directory from
247 option -O. Also useful in case of redirected stdin:
249 mimedecode -o output_file < input_file
250 cat input_file | mimedecode -o output_file
252 The 5 list options (-Bbeit) require more explanation. They allow a user to
253 control body decoding with great flexibility. Think about said mail
254 archive; for example, its maintainer wants to put there only texts,
255 convert PDF/Postscript to text, pass HTML and images decoding base64 to
256 html but leaving images encoded, and ignore everything else. This is how
259 mimedecode -t application/pdf -t application/postscript -t text/plain -b
260 text/html -B 'image/\*' -i '\*/\*'
262 When the program decodes a message (non-MIME or a non-multipart subpart of
263 a MIME message), it consults Content-Type header. The content type is
264 searched in all 5 lists, in order "text-binary-ignore-error". If found,
265 appropriate action is performed. If not found, the program searches the
266 same lists for "type/\*" mask (the type of "text/html" is just "text"). If
267 found, appropriate action is performed. If not found, the program searches
268 the same lists for "\*/\*" mask. If found, appropriate action is performed.
269 If not found, the program uses the default action, which is to decode
270 everything to text (if mailcap specifies a filter). This algorithm allows
271 more specific content types to override less specific: -b image/\* will be
272 processed earlier than -B \*/\*.
274 Options -e/-I/-i can also work with multipart subparts of a MIME message.
275 In case of -I/-i the entire subtree of that multipart is removed; with -i
276 it's replaced with ignore warning.
278 Initially all 5 lists are empty, so without any additional parameters the
279 program always uses the default decoding (as -t \*/\*).
281 The 3 save options (--save-headers/body/message) are similar. They make
282 the program to save every non-multipart subpart (only headers, or body, or
283 the entire subpart: headers + body) that corresponds to the given mask to
284 a file. Before saving the message (or the subpart) is decoded according to
285 all other options and is placed to the output stream as usual. Filename
286 for the file is created using "filename" parameter from the
287 Content-Disposition header, or "name" parameter from the Content-Type
288 header if one of those exist; a serial counter is prepended to the
289 filename to avoid collisions; if there are no name/filename parameters, or
290 the name/filename parameters contain forbidden characters (null, slash,
291 backslash) the filename is just the serial counter.
293 If the file doesn't have any extensions (no dots in the value of the
294 name/filename parameters, or the name is just the counter) the program
295 tries to guess an extension by looking up the content type in mime.types
296 files including .mime.types file in the user's home directory (if it
297 exists). If the file has an extension the program doesn't try to verify
298 that it corresponds to the content type.
300 The file is saved in the directory set with -O (default is the current
301 directory). The save options are proceeded before -e options so the user
302 can save the message that causes an error.
313 Define current locale settings. Used to determine current default charset
314 (if your Python is properly installed and configured).
319 The program may produce incorrect MIME message. The purpose of the program
320 is to decode whatever it is possible to decode, not to produce absolutely
321 correct MIME output. The incorrect parts are obvious - decoded
322 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
323 than that output is correct MIME message. The program does not try to
324 guess whether the headers are correct. For example, if a message header
325 states that charset is iso8859-1, but the body (HTML, for example) is
326 actually in utf-8 the program will recode the message with the wrong
332 Oleg Broytman <phd@phdru.name>
337 Copyright (C) 2001-2023 PhiloSoft Design.
347 This program is distributed in the hope that it will be useful, but
348 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
349 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
355 mimedecode home page: https://phdru.name/Software/Python/#mimedecode