|
1 ============== |
|
2 Sending e-mail |
|
3 ============== |
|
4 |
|
5 Although Python makes sending e-mail relatively easy via the `smtplib library`_, |
|
6 Django provides a couple of light wrappers over it, to make sending e-mail |
|
7 extra quick. |
|
8 |
|
9 The code lives in a single module: ``django.core.mail``. |
|
10 |
|
11 .. _smtplib library: http://www.python.org/doc/current/lib/module-smtplib.html |
|
12 |
|
13 Quick example |
|
14 ============= |
|
15 |
|
16 In two lines:: |
|
17 |
|
18 from django.core.mail import send_mail |
|
19 |
|
20 send_mail('Subject here', 'Here is the message.', 'from@example.com', |
|
21 ['to@example.com'], fail_silently=False) |
|
22 |
|
23 .. note:: |
|
24 |
|
25 The character set of email sent with ``django.core.mail`` will be set to |
|
26 the value of your `DEFAULT_CHARSET setting`_. |
|
27 |
|
28 .. _DEFAULT_CHARSET setting: ../settings/#DEFAULT_CHARSET |
|
29 |
|
30 send_mail() |
|
31 =========== |
|
32 |
|
33 The simplest way to send e-mail is using the function |
|
34 ``django.core.mail.send_mail()``. Here's its definition:: |
|
35 |
|
36 send_mail(subject, message, from_email, recipient_list, |
|
37 fail_silently=False, auth_user=None, |
|
38 auth_password=None) |
|
39 |
|
40 The ``subject``, ``message``, ``from_email`` and ``recipient_list`` parameters |
|
41 are required. |
|
42 |
|
43 * ``subject``: A string. |
|
44 * ``message``: A string. |
|
45 * ``from_email``: A string. |
|
46 * ``recipient_list``: A list of strings, each an e-mail address. Each |
|
47 member of ``recipient_list`` will see the other recipients in the "To:" |
|
48 field of the e-mail message. |
|
49 * ``fail_silently``: A boolean. If it's ``False``, ``send_mail`` will raise |
|
50 an ``smtplib.SMTPException``. See the `smtplib docs`_ for a list of |
|
51 possible exceptions, all of which are subclasses of ``SMTPException``. |
|
52 * ``auth_user``: The optional username to use to authenticate to the SMTP |
|
53 server. If this isn't provided, Django will use the value of the |
|
54 ``EMAIL_HOST_USER`` setting. |
|
55 * ``auth_password``: The optional password to use to authenticate to the |
|
56 SMTP server. If this isn't provided, Django will use the value of the |
|
57 ``EMAIL_HOST_PASSWORD`` setting. |
|
58 |
|
59 .. _smtplib docs: http://www.python.org/doc/current/lib/module-smtplib.html |
|
60 |
|
61 send_mass_mail() |
|
62 ================ |
|
63 |
|
64 ``django.core.mail.send_mass_mail()`` is intended to handle mass e-mailing. |
|
65 Here's the definition:: |
|
66 |
|
67 send_mass_mail(datatuple, fail_silently=False, |
|
68 auth_user=None, auth_password=None): |
|
69 |
|
70 ``datatuple`` is a tuple in which each element is in this format:: |
|
71 |
|
72 (subject, message, from_email, recipient_list) |
|
73 |
|
74 ``fail_silently``, ``auth_user`` and ``auth_password`` have the same functions |
|
75 as in ``send_mail()``. |
|
76 |
|
77 Each separate element of ``datatuple`` results in a separate e-mail message. |
|
78 As in ``send_mail()``, recipients in the same ``recipient_list`` will all see |
|
79 the other addresses in the e-mail messages's "To:" field. |
|
80 |
|
81 send_mass_mail() vs. send_mail() |
|
82 -------------------------------- |
|
83 |
|
84 The main difference between ``send_mass_mail()`` and ``send_mail()`` is that |
|
85 ``send_mail()`` opens a connection to the mail server each time it's executed, |
|
86 while ``send_mass_mail()`` uses a single connection for all of its messages. |
|
87 This makes ``send_mass_mail()`` slightly more efficient. |
|
88 |
|
89 mail_admins() |
|
90 ============= |
|
91 |
|
92 ``django.core.mail.mail_admins()`` is a shortcut for sending an e-mail to the |
|
93 site admins, as defined in the `ADMINS setting`_. Here's the definition:: |
|
94 |
|
95 mail_admins(subject, message, fail_silently=False) |
|
96 |
|
97 ``mail_admins()`` prefixes the subject with the value of the |
|
98 `EMAIL_SUBJECT_PREFIX setting`_, which is ``"[Django] "`` by default. |
|
99 |
|
100 The "From:" header of the e-mail will be the value of the `SERVER_EMAIL setting`_. |
|
101 |
|
102 This method exists for convenience and readability. |
|
103 |
|
104 .. _ADMINS setting: ../settings/#admins |
|
105 .. _EMAIL_SUBJECT_PREFIX setting: ../settings/#email-subject-prefix |
|
106 .. _SERVER_EMAIL setting: ../settings/#server-email |
|
107 |
|
108 mail_managers() function |
|
109 ======================== |
|
110 |
|
111 ``django.core.mail.mail_managers()`` is just like ``mail_admins()``, except it |
|
112 sends an e-mail to the site managers, as defined in the `MANAGERS setting`_. |
|
113 Here's the definition:: |
|
114 |
|
115 mail_managers(subject, message, fail_silently=False) |
|
116 |
|
117 .. _MANAGERS setting: ../settings/#managers |
|
118 |
|
119 Examples |
|
120 ======== |
|
121 |
|
122 This sends a single e-mail to john@example.com and jane@example.com, with them |
|
123 both appearing in the "To:":: |
|
124 |
|
125 send_mail('Subject', 'Message.', 'from@example.com', |
|
126 ['john@example.com', 'jane@example.com']) |
|
127 |
|
128 This sends a message to john@example.com and jane@example.com, with them both |
|
129 receiving a separate e-mail:: |
|
130 |
|
131 datatuple = ( |
|
132 ('Subject', 'Message.', 'from@example.com', ['john@example.com']), |
|
133 ('Subject', 'Message.', 'from@example.com', ['jane@example.com']), |
|
134 ) |
|
135 send_mass_mail(datatuple) |
|
136 |
|
137 Preventing header injection |
|
138 =========================== |
|
139 |
|
140 `Header injection`_ is a security exploit in which an attacker inserts extra |
|
141 e-mail headers to control the "To:" and "From:" in e-mail messages that your |
|
142 scripts generate. |
|
143 |
|
144 The Django e-mail functions outlined above all protect against header injection |
|
145 by forbidding newlines in header values. If any ``subject``, ``from_email`` or |
|
146 ``recipient_list`` contains a newline (in either Unix, Windows or Mac style), |
|
147 the e-mail function (e.g. ``send_mail()``) will raise |
|
148 ``django.core.mail.BadHeaderError`` (a subclass of ``ValueError``) and, hence, |
|
149 will not send the e-mail. It's your responsibility to validate all data before |
|
150 passing it to the e-mail functions. |
|
151 |
|
152 If a ``message`` contains headers at the start of the string, the headers will |
|
153 simply be printed as the first bit of the e-mail message. |
|
154 |
|
155 Here's an example view that takes a ``subject``, ``message`` and ``from_email`` |
|
156 from the request's POST data, sends that to admin@example.com and redirects to |
|
157 "/contact/thanks/" when it's done:: |
|
158 |
|
159 from django.core.mail import send_mail, BadHeaderError |
|
160 |
|
161 def send_email(request): |
|
162 subject = request.POST.get('subject', '') |
|
163 message = request.POST.get('message', '') |
|
164 from_email = request.POST.get('from_email', '') |
|
165 if subject and message and from_email: |
|
166 try: |
|
167 send_mail(subject, message, from_email, ['admin@example.com']) |
|
168 except BadHeaderError: |
|
169 return HttpResponse('Invalid header found.') |
|
170 return HttpResponseRedirect('/contact/thanks/') |
|
171 else: |
|
172 # In reality we'd use a manipulator |
|
173 # to get proper validation errors. |
|
174 return HttpResponse('Make sure all fields are entered and valid.') |
|
175 |
|
176 .. _Header injection: http://securephp.damonkohler.com/index.php/Email_Injection |