mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-09-26 12:09:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Fixed #3307 -- Added BCC support to the EmailMessage class. En-passant, fixed a

Browse source 
number of RST formatting errors in the email docs.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@5146 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Malcolm Tredinnick 2007-05-03 14:38:45 +00:00
parent bc6535b599
commit 5ff1d96a52
2 changed files with 52 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

62
docs/email.txt
View file

@ -189,42 +189,56 @@ from the request's POST data, sends that to admin@example.com and redirects to
The EmailMessage and SMTPConnection classes
===========================================
Django's `send_mail()` and `send_mass_mail()` functions are actually thin
wrappers that make use of the `EmailMessage` and `SMTPConnection` classes in
`django.mail`. If you ever need to customize the way Django sends email, you
can subclass these two classes to suit your needs.
Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin
wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes
in ``django.mail``. If you ever need to customize the way Django sends email,
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
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 including BCC recipients or multi-part email, you will
need to create `EmailMessage` instances directly.
need to create ``EmailMessage`` instances directly.
In general, `EmailMessage` is responsible for creating the email 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.
In general, ``EmailMessage`` is responsible for creating the email 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 has the following methods that you can use:
The ``EmailMessage`` class is initialised as follows::
* `send()` sends the message, using either the connection that is specified
in the `connection` attribute, or creating a new connection if none already
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.
The class has the following methods that you can use:
* ``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 will
probably want to override this method to put the content you wish into the
MIME object.
* ``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 will probably want to override this method to put the content you wish
into the MIME object.
* ``recipients()`` returns a lists of all the recipients of the message,
whether they are recorded in the ``to`` or ``bcc`` attributes. This is
another method you need to possibly override when sub-classing, since 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
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 are sending lots of messages at once, the `send_messages()` method of
the `SMTPConnection` class will be useful. It takes a list of `EmailMessage`
If you are sending lots of messages at once, the ``send_messages()`` method of
the ``SMTPConnection`` class will be useful. It takes a list of ``EmailMessage``
instances (or sub-classes) 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 email you wish to
example, if you have a function called ``get_notification_email()`` that returns a
list of ``EmailMessage`` objects representing some periodic email you wish to
send out, you could send this with::
connection = SMTPConnection() # Use default settings for connection