Changeset 5580 for django/branches/unicode/docs/email.txt

Timestamp:

07/01/07 00:55:01 (2 years ago)

Author:

mtredinnick

Message:

unicode: Merged changes from trunk up to [5579].

Files:

• django/branches/unicode (modified) (1 prop)
• django/branches/unicode/docs/email.txt (modified) (4 diffs)

django/branches/unicode/docs/email.txt

@@ -29 +29 @@
-
-    The character set of e-mail sent with ``django.core.mail`` will be set to
- setting`_
-
- setting
+`_ setting
+
+
-.. _EMAIL_HOST: ../settings/#email-host
-.. _EMAIL_PORT: ../settings/#email-port
@@ -199 +199 @@
-    Not all features of the ``EmailMessage`` class are available through the
-    ``send_mail()`` and related wrapper functions. If you wish to use advanced
-
-
+
+
+
+
+
+
+
+
-
-In general, ``EmailMessage`` is responsible for creating the e-mail message
@@ -207 +213 @@
-``SMTPConnection`` instance) for multiple messages.
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-For example::
-
-    email = EmailMessage('Hello', 'Body goes here', 'from@example.com',
-
-['bcc@example.com']
+ ['bcc@example.com'],
+headers = {'Reply-To': 'another@example.com'}
-
-The class has the following methods:
@@ -228 +259 @@
-
-    * ``message()`` constructs a ``django.core.mail.SafeMIMEText`` object (a
-
-
-
+
+
+
+
-      into the MIME object.
-
-    * ``recipients()`` returns a list of all the recipients of the message,
-      whether they're recorded in the ``to`` or ``bcc`` attributes. This is
--
+
-      SMTP server needs to be told the full list of recipients when the message
-      is sent. If you add another way to specify recipients in your class, they
-      need to be returned from this method as well.
+
+    * ``attach()`` creates a new file attachment and adds it to the message.
+      There are two ways to call ``attach()``:
+
+       * You can pass it a single argument that is an
+         ``email.MIMBase.MIMEBase`` instance. This will be inserted directly
+         into the resulting message.
+
+       * Alternatively, you can pass ``attach()`` three arguments:
+         ``filename``, ``content`` and ``mimetype``. ``filename`` is the name
+         of the file attachment as it will appear in the e-mail, ``content`` is
+         the data that will be contained inside the attachment and
+         ``mimetype`` is the optional MIME type for the attachment. If you
+         omit ``mimetype``, the MIME content type will be guessed from the
+         filename of the attachment.
+
+         For example::
+
+            message.attach('design.png', img_data, 'image/png')
+
+    * ``attach_file()`` creates a new attachment using a file from your
+      filesystem. Call it with the path of the file to attach and, optionally,
+      the MIME type to use for the attachment. If the MIME type is omitted, it
+      will be guessed from the filename. The simplest use would be::
+
+        message.attach_file('/images/weather_map.png')
+
+Sending alternative content types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It can be useful to include multiple versions of the content in an e-mail;
+the classic example is to send both text and HTML versions of a message. With
+Django's e-mail library, you can do this using the ``EmailMultiAlternatives``
+class. This subclass of ``EmailMessage`` has an ``attach_alternative()`` method
+for including extra versions of the message body in the e-mail. All the other
+methods (including the class initialization) are inherited directly from
+``EmailMessage``.
+
+To send a text and HTML combination, you could write::
+
+    from django.core.mail import EmailMultiAlternatives
+
+    subject, from_email, to = 'hello', 'from@example.com', 'to@example.com'
+    text_content = 'This is an important message.'
+    html_content = '<p>This is an <strong>important</strong> message.'
+    msg = EmailMultiAlternatives(subject, text_content, from_email, to)
+    msg.attach_alternative(html_content, "text/html")
+    msg.send()
+
+By default, the MIME type of the ``body`` parameter in an ``EmailMessage`` is
+``"text/plain"``. It is good practice to leave this alone, because it
+guarantees that any recipient will be able to read the e-mail, regardless of
+their mail client. However, if you are confident that your recipients can
+handle an alternative content type, you can use the ``content_subtype``
+attribute on the ``EmailMessage`` class to change the main content type. The
+major type will always be ``"text"``, but you can change it to the subtype. For
+example::
+
+    msg = EmailMessage(subject, html_content, from_email, to)
+    msg.content_subtype = "html"  # Main content is now text/html
+    msg.send()
+
+SMTP network connections
+------------------------
-
-The ``SMTPConnection`` class is initialized with the host, port, username and