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 

    23 .. class:: MIMEBase(_maintype, _subtype, **_params)

    24 

    25    Module: :mod:`email.mime.base`

    26 

    27    This is the base class for all the MIME-specific subclasses of :class:`Message`.

    28    Ordinarily you won't create instances specifically of :class:`MIMEBase`,

    29    although you could.  :class:`MIMEBase` is provided primarily as a convenient

    30    base class for more specific MIME-aware subclasses.

    31 

    32    *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`

    33    or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor

    34    type  (e.g. :mimetype:`plain` or :mimetype:`gif`).  *_params* is a parameter

    35    key/value dictionary and is passed directly to :meth:`Message.add_header`.

    36 

    37    The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header

    38    (based on *_maintype*, *_subtype*, and *_params*), and a

    39    :mailheader:`MIME-Version` header (always set to ``1.0``).

    40 

    41 

    42 .. class:: MIMENonMultipart()

    43 

    44    Module: :mod:`email.mime.nonmultipart`

    45 

    46    A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME

    47    messages that are not :mimetype:`multipart`.  The primary purpose of this class

    48    is to prevent the use of the :meth:`attach` method, which only makes sense for

    49    :mimetype:`multipart` messages.  If :meth:`attach` is called, a

    50    :exc:`MultipartConversionError` exception is raised.

    51 

    52    .. versionadded:: 2.2.2

    53 

    54 

    55 .. class:: MIMEMultipart([subtype[, boundary[, _subparts[, _params]]]])

    56 

    57    Module: :mod:`email.mime.multipart`

    58 

    59    A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME

    60    messages that are :mimetype:`multipart`.  Optional *_subtype* defaults to

    61    :mimetype:`mixed`, but can be used to specify the subtype of the message.  A

    62    :mailheader:`Content-Type` header of :mimetype:`multipart/`*_subtype* will be

    63    added to the message object.  A :mailheader:`MIME-Version` header will also be

    64    added.

    65 

    66    Optional *boundary* is the multipart boundary string.  When ``None`` (the

    67    default), the boundary is calculated when needed.

    68 

    69    *_subparts* is a sequence of initial subparts for the payload.  It must be

    70    possible to convert this sequence to a list.  You can always attach new subparts

    71    to the message by using the :meth:`Message.attach` method.

    72 

    73    Additional parameters for the :mailheader:`Content-Type` header are taken from

    74    the keyword arguments, or passed into the *_params* argument, which is a keyword

    75    dictionary.

    76 

    77    .. versionadded:: 2.2.2

    78 

    79 

    80 .. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])

    81 

    82    Module: :mod:`email.mime.application`

    83 

    84    A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is

    85    used to represent MIME message objects of major type :mimetype:`application`.

    86    *_data* is a string containing the raw byte data.  Optional *_subtype* specifies

    87    the MIME subtype and defaults to :mimetype:`octet-stream`.

    88 

    89    Optional *_encoder* is a callable (i.e. function) which will perform the actual

    90    encoding of the data for transport.  This callable takes one argument, which is

    91    the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and

    92    :meth:`set_payload` to change the payload to encoded form.  It should also add

    93    any :mailheader:`Content-Transfer-Encoding` or other headers to the message

    94    object as necessary.  The default encoding is base64.  See the

    95    :mod:`email.encoders` module for a list of the built-in encoders.

    96 

    97    *_params* are passed straight through to the base class constructor.

    98 

    99    .. versionadded:: 2.5

   100 

   101 

   102 .. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])

   103 

   104    Module: :mod:`email.mime.audio`

   105 

   106    A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to

   107    create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a

   108    string containing the raw audio data.  If this data can be decoded by the

   109    standard Python module :mod:`sndhdr`, then the subtype will be automatically

   110    included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly

   111    specify the audio subtype via the *_subtype* parameter.  If the minor type could

   112    not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.

   113 

   114    Optional *_encoder* is a callable (i.e. function) which will perform the actual

   115    encoding of the audio data for transport.  This callable takes one argument,

   116    which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and

   117    :meth:`set_payload` to change the payload to encoded form.  It should also add

   118    any :mailheader:`Content-Transfer-Encoding` or other headers to the message

   119    object as necessary.  The default encoding is base64.  See the

   120    :mod:`email.encoders` module for a list of the built-in encoders.

   121 

   122    *_params* are passed straight through to the base class constructor.

   123 

   124 

   125 .. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])

   126 

   127    Module: :mod:`email.mime.image`

   128 

   129    A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to

   130    create MIME message objects of major type :mimetype:`image`. *_imagedata* is a

   131    string containing the raw image data.  If this data can be decoded by the

   132    standard Python module :mod:`imghdr`, then the subtype will be automatically

   133    included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly

   134    specify the image subtype via the *_subtype* parameter.  If the minor type could

   135    not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.

   136 

   137    Optional *_encoder* is a callable (i.e. function) which will perform the actual

   138    encoding of the image data for transport.  This callable takes one argument,

   139    which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and

   140    :meth:`set_payload` to change the payload to encoded form.  It should also add

   141    any :mailheader:`Content-Transfer-Encoding` or other headers to the message

   142    object as necessary.  The default encoding is base64.  See the

   143    :mod:`email.encoders` module for a list of the built-in encoders.

   144 

   145    *_params* are passed straight through to the :class:`MIMEBase` constructor.

   146 

   147 

   148 .. class:: MIMEMessage(_msg[, _subtype])

   149 

   150    Module: :mod:`email.mime.message`

   151 

   152    A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used

   153    to create MIME objects of main type :mimetype:`message`. *_msg* is used as the

   154    payload, and must be an instance of class :class:`Message` (or a subclass

   155    thereof), otherwise a :exc:`TypeError` is raised.

   156 

   157    Optional *_subtype* sets the subtype of the message; it defaults to

   158    :mimetype:`rfc822`.

   159 

   160 

   161 .. class:: MIMEText(_text[, _subtype[, _charset]])

   162 

   163    Module: :mod:`email.mime.text`

   164 

   165    A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to

   166    create MIME objects of major type :mimetype:`text`. *_text* is the string for

   167    the payload.  *_subtype* is the minor type and defaults to :mimetype:`plain`.

   168    *_charset* is the character set of the text and is passed as a parameter to the

   169    :class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``.  No guessing

   170    or encoding is performed on the text data.

   171 

   172    .. versionchanged:: 2.4

   173       The previously deprecated *_encoding* argument has been removed.  Encoding

   174       happens implicitly based on the *_charset* argument.

   175