Changeset 5488 for django/branches/per-object-permissions/docs/email.txt

Timestamp:

06/17/07 17:18:54 (2 years ago)

Author:

clong

Message:

per-object-permissions: Merged to trunk [5486] NOTE: Not fully tested, will be working on this over the next few weeks.

Files:

• django/branches/per-object-permissions/docs/email.txt (modified) (6 diffs)

django/branches/per-object-permissions/docs/email.txt

@@ -20 +20 @@
-    send_mail('Subject here', 'Here is the message.', 'from@example.com',
-        ['to@example.com'], fail_silently=False)
-
+
+
+
+
+
+
-.. note::
-
-
+-
-    the value of your `DEFAULT_CHARSET setting`_.
-
-
+
+
+
+
+
+
+
-
-send_mail()
@@ -35 +45 @@
-
-    send_mail(subject, message, from_email, recipient_list,
-EMAIL_HOST_USER
-EMAIL_HOST_PASSWORD
+None
+None
-
-The ``subject``, ``message``, ``from_email`` and ``recipient_list`` parameters
@@ -66 +76 @@
-
-    send_mass_mail(datatuple, fail_silently=False,
-EMAIL_HOST_USER, auth_password=EMAIL_HOST_PASSWORD
+None, auth_password=None
-
-``datatuple`` is a tuple in which each element is in this format::
@@ -102 +112 @@
-This method exists for convenience and readability.
-
-http://www.djangoproject.com/documentation
-http://www.djangoproject.com/documentation
-http://www.djangoproject.com/documentation
+..
+..
+..
-
-mail_managers() function
@@ -115 +125 @@
-    mail_managers(subject, message, fail_silently=False)
-
-http://www.djangoproject.com/documentation
+..
-
-Examples
@@ -175 +185 @@
-
-.. _Header injection: http://securephp.damonkohler.com/index.php/Email_Injection
+
+The EmailMessage and SMTPConnection classes
+===========================================
+
+**New in Django development version**
+
+Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin
+wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes
+in ``django.core.mail``.  If you ever need to customize the way Django sends
+e-mail, you can subclass these two classes to suit your needs.
+
+.. note::
+    Not all features of the ``EmailMessage`` class are available through the
+    ``send_mail()`` and related wrapper functions. If you wish to use advanced
+    features, such as BCC'ed recipients or multi-part e-mail, you'll need to
+    create ``EmailMessage`` instances directly.
+
+In general, ``EmailMessage`` is responsible for creating the e-mail message
+itself. ``SMTPConnection`` is responsible for the network connection side of
+the operation. This means you can reuse the same connection (an
+``SMTPConnection`` instance) for multiple messages.
+
+The ``EmailMessage`` class is initialized as follows::
+
+    email = EmailMessage(subject, body, from_email, to, bcc, connection)
+
+All of these parameters are optional. If ``from_email`` is omitted, the value
+from ``settings.DEFAULT_FROM_EMAIL`` is used. Both the ``to`` and ``bcc``
+parameters are lists of addresses, as strings.
+
+For example::
+
+    email = EmailMessage('Hello', 'Body goes here', 'from@example.com',
+                ['to1@example.com', 'to2@example.com'],
+                ['bcc@example.com'])
+
+The class has the following methods:
+
+    * ``send()`` sends the message, using either the connection that is
+      specified in the ``connection`` attribute, or creating a new connection
+      if none already exists.
+
+    * ``message()`` constructs a ``django.core.mail.SafeMIMEText`` object (a
+      sub-class of Python's ``email.MIMEText.MIMEText`` class) holding the
+      message to be sent. If you ever need to extend the `EmailMessage` class,
+      you'll probably want to override this method to put the content you wish
+      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
+      another method you might need to override when sub-classing, because the
+      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.
+
+The ``SMTPConnection`` class is initialized with the host, port, username and
+password for the SMTP server. If you don't specify one or more of those
+options, they are read from your settings file.
+
+If you're sending lots of messages at once, the ``send_messages()`` method of
+the ``SMTPConnection`` class is useful. It takes a list of ``EmailMessage``
+instances (or subclasses) and sends them over a single connection. For example,
+if you have a function called ``get_notification_email()`` that returns a
+list of ``EmailMessage`` objects representing some periodic e-mail you wish to
+send out, you could send this with::
+
+    connection = SMTPConnection()   # Use default settings for connection
+    messages = get_notification_email()
+    connection.send_messages(messages)