1 \declaremodule{standard
}{email.mime
}
2 \declaremodule{standard
}{email.mime.base
}
3 \declaremodule{standard
}{email.mime.nonmultipart
}
4 \declaremodule{standard
}{email.mime.multipart
}
5 \declaremodule{standard
}{email.mime.audio
}
6 \declaremodule{standard
}{email.mime.image
}
7 \declaremodule{standard
}{email.mime.message
}
8 \declaremodule{standard
}{email.mime.text
}
9 Ordinarily, you get a message object structure by passing a file or
10 some text to a parser, which parses the text and returns the root
11 message object. However you can also build a complete message
12 structure from scratch, or even individual
\class{Message
} objects by
13 hand. In fact, you can also take an existing structure and add new
14 \class{Message
} objects, move them around, etc. This makes a very
15 convenient interface for slicing-and-dicing MIME messages.
17 You can create a new object structure by creating
\class{Message
} instances,
18 adding attachments and all the appropriate headers manually. For MIME
19 messages though, the
\module{email
} package provides some convenient
20 subclasses to make things easier.
24 \begin{classdesc
}{MIMEBase
}{_maintype, _subtype, **_params
}
25 Module:
\module{email.mime.base
}
27 This is the base class for all the MIME-specific subclasses of
28 \class{Message
}. Ordinarily you won't create instances specifically
29 of
\class{MIMEBase
}, although you could.
\class{MIMEBase
} is provided
30 primarily as a convenient base class for more specific MIME-aware
33 \var{_maintype
} is the
\mailheader{Content-Type
} major type
34 (e.g.
\mimetype{text
} or
\mimetype{image
}), and
\var{_subtype
} is the
35 \mailheader{Content-Type
} minor type
36 (e.g.
\mimetype{plain
} or
\mimetype{gif
}).
\var{_params
} is a parameter
37 key/value dictionary and is passed directly to
38 \method{Message.add_header()
}.
40 The
\class{MIMEBase
} class always adds a
\mailheader{Content-Type
} header
41 (based on
\var{_maintype
},
\var{_subtype
}, and
\var{_params
}), and a
42 \mailheader{MIME-Version
} header (always set to
\code{1.0}).
45 \begin{classdesc
}{MIMENonMultipart
}{}
46 Module:
\module{email.mime.nonmultipart
}
48 A subclass of
\class{MIMEBase
}, this is an intermediate base class for
49 MIME messages that are not
\mimetype{multipart
}. The primary purpose
50 of this class is to prevent the use of the
\method{attach()
} method,
51 which only makes sense for
\mimetype{multipart
} messages. If
52 \method{attach()
} is called, a
\exception{MultipartConversionError
}
58 \begin{classdesc
}{MIMEMultipart
}{\optional{subtype
\optional{,
59 boundary
\optional{, _subparts
\optional{, _params
}}}}}
60 Module:
\module{email.mime.multipart
}
62 A subclass of
\class{MIMEBase
}, this is an intermediate base class for
63 MIME messages that are
\mimetype{multipart
}. Optional
\var{_subtype
}
64 defaults to
\mimetype{mixed
}, but can be used to specify the subtype
65 of the message. A
\mailheader{Content-Type
} header of
66 \mimetype{multipart/
}\var{_subtype
} will be added to the message
67 object. A
\mailheader{MIME-Version
} header will also be added.
69 Optional
\var{boundary
} is the multipart boundary string. When
70 \code{None
} (the default), the boundary is calculated when needed.
72 \var{_subparts
} is a sequence of initial subparts for the payload. It
73 must be possible to convert this sequence to a list. You can always
74 attach new subparts to the message by using the
75 \method{Message.attach()
} method.
77 Additional parameters for the
\mailheader{Content-Type
} header are
78 taken from the keyword arguments, or passed into the
\var{_params
}
79 argument, which is a keyword dictionary.
84 \begin{classdesc
}{MIMEApplication
}{_data
\optional{, _subtype
\optional{,
85 _encoder
\optional{, **_params
}}}}
86 Module:
\module{email.mime.application
}
88 A subclass of
\class{MIMENonMultipart
}, the
\class{MIMEApplication
} class is
89 used to represent MIME message objects of major type
\mimetype{application
}.
90 \var{_data
} is a string containing the raw byte data. Optional
\var{_subtype
}
91 specifies the MIME subtype and defaults to
\mimetype{octet-stream
}.
93 Optional
\var{_encoder
} is a callable (i.e. function) which will
94 perform the actual encoding of the data for transport. This
95 callable takes one argument, which is the
\class{MIMEApplication
} instance.
96 It should use
\method{get_payload()
} and
\method{set_payload()
} to
97 change the payload to encoded form. It should also add any
98 \mailheader{Content-Transfer-Encoding
} or other headers to the message
99 object as necessary. The default encoding is base64. See the
100 \refmodule{email.encoders
} module for a list of the built-in encoders.
102 \var{_params
} are passed straight through to the base class constructor.
106 \begin{classdesc
}{MIMEAudio
}{_audiodata
\optional{, _subtype
\optional{,
107 _encoder
\optional{, **_params
}}}}
108 Module:
\module{email.mime.audio
}
110 A subclass of
\class{MIMENonMultipart
}, the
\class{MIMEAudio
} class
111 is used to create MIME message objects of major type
\mimetype{audio
}.
112 \var{_audiodata
} is a string containing the raw audio data. If this
113 data can be decoded by the standard Python module
\refmodule{sndhdr
},
114 then the subtype will be automatically included in the
115 \mailheader{Content-Type
} header. Otherwise you can explicitly specify the
116 audio subtype via the
\var{_subtype
} parameter. If the minor type could
117 not be guessed and
\var{_subtype
} was not given, then
\exception{TypeError
}
120 Optional
\var{_encoder
} is a callable (i.e. function) which will
121 perform the actual encoding of the audio data for transport. This
122 callable takes one argument, which is the
\class{MIMEAudio
} instance.
123 It should use
\method{get_payload()
} and
\method{set_payload()
} to
124 change the payload to encoded form. It should also add any
125 \mailheader{Content-Transfer-Encoding
} or other headers to the message
126 object as necessary. The default encoding is base64. See the
127 \refmodule{email.encoders
} module for a list of the built-in encoders.
129 \var{_params
} are passed straight through to the base class constructor.
132 \begin{classdesc
}{MIMEImage
}{_imagedata
\optional{, _subtype
\optional{,
133 _encoder
\optional{, **_params
}}}}
134 Module:
\module{email.mime.image
}
136 A subclass of
\class{MIMENonMultipart
}, the
\class{MIMEImage
} class is
137 used to create MIME message objects of major type
\mimetype{image
}.
138 \var{_imagedata
} is a string containing the raw image data. If this
139 data can be decoded by the standard Python module
\refmodule{imghdr
},
140 then the subtype will be automatically included in the
141 \mailheader{Content-Type
} header. Otherwise you can explicitly specify the
142 image subtype via the
\var{_subtype
} parameter. If the minor type could
143 not be guessed and
\var{_subtype
} was not given, then
\exception{TypeError
}
146 Optional
\var{_encoder
} is a callable (i.e. function) which will
147 perform the actual encoding of the image data for transport. This
148 callable takes one argument, which is the
\class{MIMEImage
} instance.
149 It should use
\method{get_payload()
} and
\method{set_payload()
} to
150 change the payload to encoded form. It should also add any
151 \mailheader{Content-Transfer-Encoding
} or other headers to the message
152 object as necessary. The default encoding is base64. See the
153 \refmodule{email.encoders
} module for a list of the built-in encoders.
155 \var{_params
} are passed straight through to the
\class{MIMEBase
}
159 \begin{classdesc
}{MIMEMessage
}{_msg
\optional{, _subtype
}}
160 Module:
\module{email.mime.message
}
162 A subclass of
\class{MIMENonMultipart
}, the
\class{MIMEMessage
} class
163 is used to create MIME objects of main type
\mimetype{message
}.
164 \var{_msg
} is used as the payload, and must be an instance of class
165 \class{Message
} (or a subclass thereof), otherwise a
166 \exception{TypeError
} is raised.
168 Optional
\var{_subtype
} sets the subtype of the message; it defaults
169 to
\mimetype{rfc822
}.
172 \begin{classdesc
}{MIMEText
}{_text
\optional{, _subtype
\optional{, _charset
}}}
173 Module:
\module{email.mime.text
}
175 A subclass of
\class{MIMENonMultipart
}, the
\class{MIMEText
} class is
176 used to create MIME objects of major type
\mimetype{text
}.
177 \var{_text
} is the string for the payload.
\var{_subtype
} is the
178 minor type and defaults to
\mimetype{plain
}.
\var{_charset
} is the
179 character set of the text and is passed as a parameter to the
180 \class{MIMENonMultipart
} constructor; it defaults to
\code{us-ascii
}. No
181 guessing or encoding is performed on the text data.
183 \versionchanged[The previously deprecated
\var{_encoding
} argument has
184 been removed. Encoding happens implicitly based on the
\var{_charset
}