Doc/library/email.mime.rst

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