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