--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/thirdparty/google_appengine/lib/django/docs/email.txt Tue Aug 26 21:49:54 2008 +0000
@@ -0,0 +1,176 @@
+==============
+Sending e-mail
+==============
+
+Although Python makes sending e-mail relatively easy via the `smtplib library`_,
+Django provides a couple of light wrappers over it, to make sending e-mail
+extra quick.
+
+The code lives in a single module: ``django.core.mail``.
+
+.. _smtplib library: http://www.python.org/doc/current/lib/module-smtplib.html
+
+Quick example
+=============
+
+In two lines::
+
+ from django.core.mail import send_mail
+
+ send_mail('Subject here', 'Here is the message.', 'from@example.com',
+ ['to@example.com'], fail_silently=False)
+
+.. note::
+
+ The character set of email sent with ``django.core.mail`` will be set to
+ the value of your `DEFAULT_CHARSET setting`_.
+
+.. _DEFAULT_CHARSET setting: ../settings/#DEFAULT_CHARSET
+
+send_mail()
+===========
+
+The simplest way to send e-mail is using the function
+``django.core.mail.send_mail()``. Here's its definition::
+
+ send_mail(subject, message, from_email, recipient_list,
+ fail_silently=False, auth_user=None,
+ auth_password=None)
+
+The ``subject``, ``message``, ``from_email`` and ``recipient_list`` parameters
+are required.
+
+ * ``subject``: A string.
+ * ``message``: A string.
+ * ``from_email``: A string.
+ * ``recipient_list``: A list of strings, each an e-mail address. Each
+ member of ``recipient_list`` will see the other recipients in the "To:"
+ field of the e-mail message.
+ * ``fail_silently``: A boolean. If it's ``False``, ``send_mail`` will raise
+ an ``smtplib.SMTPException``. See the `smtplib docs`_ for a list of
+ possible exceptions, all of which are subclasses of ``SMTPException``.
+ * ``auth_user``: The optional username to use to authenticate to the SMTP
+ server. If this isn't provided, Django will use the value of the
+ ``EMAIL_HOST_USER`` setting.
+ * ``auth_password``: The optional password to use to authenticate to the
+ SMTP server. If this isn't provided, Django will use the value of the
+ ``EMAIL_HOST_PASSWORD`` setting.
+
+.. _smtplib docs: http://www.python.org/doc/current/lib/module-smtplib.html
+
+send_mass_mail()
+================
+
+``django.core.mail.send_mass_mail()`` is intended to handle mass e-mailing.
+Here's the definition::
+
+ send_mass_mail(datatuple, fail_silently=False,
+ auth_user=None, auth_password=None):
+
+``datatuple`` is a tuple in which each element is in this format::
+
+ (subject, message, from_email, recipient_list)
+
+``fail_silently``, ``auth_user`` and ``auth_password`` have the same functions
+as in ``send_mail()``.
+
+Each separate element of ``datatuple`` results in a separate e-mail message.
+As in ``send_mail()``, recipients in the same ``recipient_list`` will all see
+the other addresses in the e-mail messages's "To:" field.
+
+send_mass_mail() vs. send_mail()
+--------------------------------
+
+The main difference between ``send_mass_mail()`` and ``send_mail()`` is that
+``send_mail()`` opens a connection to the mail server each time it's executed,
+while ``send_mass_mail()`` uses a single connection for all of its messages.
+This makes ``send_mass_mail()`` slightly more efficient.
+
+mail_admins()
+=============
+
+``django.core.mail.mail_admins()`` is a shortcut for sending an e-mail to the
+site admins, as defined in the `ADMINS setting`_. Here's the definition::
+
+ mail_admins(subject, message, fail_silently=False)
+
+``mail_admins()`` prefixes the subject with the value of the
+`EMAIL_SUBJECT_PREFIX setting`_, which is ``"[Django] "`` by default.
+
+The "From:" header of the e-mail will be the value of the `SERVER_EMAIL setting`_.
+
+This method exists for convenience and readability.
+
+.. _ADMINS setting: ../settings/#admins
+.. _EMAIL_SUBJECT_PREFIX setting: ../settings/#email-subject-prefix
+.. _SERVER_EMAIL setting: ../settings/#server-email
+
+mail_managers() function
+========================
+
+``django.core.mail.mail_managers()`` is just like ``mail_admins()``, except it
+sends an e-mail to the site managers, as defined in the `MANAGERS setting`_.
+Here's the definition::
+
+ mail_managers(subject, message, fail_silently=False)
+
+.. _MANAGERS setting: ../settings/#managers
+
+Examples
+========
+
+This sends a single e-mail to john@example.com and jane@example.com, with them
+both appearing in the "To:"::
+
+ send_mail('Subject', 'Message.', 'from@example.com',
+ ['john@example.com', 'jane@example.com'])
+
+This sends a message to john@example.com and jane@example.com, with them both
+receiving a separate e-mail::
+
+ datatuple = (
+ ('Subject', 'Message.', 'from@example.com', ['john@example.com']),
+ ('Subject', 'Message.', 'from@example.com', ['jane@example.com']),
+ )
+ send_mass_mail(datatuple)
+
+Preventing header injection
+===========================
+
+`Header injection`_ is a security exploit in which an attacker inserts extra
+e-mail headers to control the "To:" and "From:" in e-mail messages that your
+scripts generate.
+
+The Django e-mail functions outlined above all protect against header injection
+by forbidding newlines in header values. If any ``subject``, ``from_email`` or
+``recipient_list`` contains a newline (in either Unix, Windows or Mac style),
+the e-mail function (e.g. ``send_mail()``) will raise
+``django.core.mail.BadHeaderError`` (a subclass of ``ValueError``) and, hence,
+will not send the e-mail. It's your responsibility to validate all data before
+passing it to the e-mail functions.
+
+If a ``message`` contains headers at the start of the string, the headers will
+simply be printed as the first bit of the e-mail message.
+
+Here's an example view that takes a ``subject``, ``message`` and ``from_email``
+from the request's POST data, sends that to admin@example.com and redirects to
+"/contact/thanks/" when it's done::
+
+ from django.core.mail import send_mail, BadHeaderError
+
+ def send_email(request):
+ subject = request.POST.get('subject', '')
+ message = request.POST.get('message', '')
+ from_email = request.POST.get('from_email', '')
+ if subject and message and from_email:
+ try:
+ send_mail(subject, message, from_email, ['admin@example.com'])
+ except BadHeaderError:
+ return HttpResponse('Invalid header found.')
+ return HttpResponseRedirect('/contact/thanks/')
+ else:
+ # In reality we'd use a manipulator
+ # to get proper validation errors.
+ return HttpResponse('Make sure all fields are entered and valid.')
+
+.. _Header injection: http://securephp.damonkohler.com/index.php/Email_Injection