<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Sending email — Django 1.6.7 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.6.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Django 1.6.7 documentation" href="../index.html" />
<link rel="up" title="Using Django" href="index.html" />
<link rel="next" title="Internationalization and localization" href="i18n/index.html" />
<link rel="prev" title="Cryptographic signing" href="signing.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.6.7 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="signing.html" title="Cryptographic signing">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="i18n/index.html" title="Internationalization and localization">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="topics-email">
<div class="section" id="s-module-django.core.mail">
<span id="s-sending-email"></span><span id="module-django.core.mail"></span><span id="sending-email"></span><h1>Sending email<a class="headerlink" href="#module-django.core.mail" title="Permalink to this headline">¶</a></h1>
<p>Although Python makes sending email relatively easy via the <tt class="xref py py-mod docutils literal"><span class="pre">smtplib</span></tt>
module, Django provides a couple of light wrappers over it. These wrappers are
provided to make sending email extra quick, to make it easy to test email
sending during development, and to provide support for platforms that can’t use
SMTP.</p>
<p>The code lives in the <tt class="docutils literal"><span class="pre">django.core.mail</span></tt> module.</p>
<div class="section" id="s-quick-example">
<span id="quick-example"></span><h2>Quick example<a class="headerlink" href="#quick-example" title="Permalink to this headline">¶</a></h2>
<p>In two lines:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core.mail</span> <span class="kn">import</span> <span class="n">send_mail</span>
<span class="n">send_mail</span><span class="p">(</span><span class="s">'Subject here'</span><span class="p">,</span> <span class="s">'Here is the message.'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span>
<span class="p">[</span><span class="s">'to@example.com'</span><span class="p">],</span> <span class="n">fail_silently</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
</pre></div>
</div>
<p>Mail is sent using the SMTP host and port specified in the
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST</span></tt></a> and <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_PORT"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_PORT</span></tt></a> settings. The
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST_USER"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST_USER</span></tt></a> and <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST_PASSWORD"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST_PASSWORD</span></tt></a> settings, if
set, are used to authenticate to the SMTP server, and the
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_USE_TLS"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_USE_TLS</span></tt></a> setting controls whether a secure connection is used.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The character set of email sent with <tt class="docutils literal"><span class="pre">django.core.mail</span></tt> will be set to
the value of your <a class="reference internal" href="../ref/settings.html#std:setting-DEFAULT_CHARSET"><tt class="xref std std-setting docutils literal"><span class="pre">DEFAULT_CHARSET</span></tt></a> setting.</p>
</div>
</div>
<div class="section" id="s-send-mail">
<span id="send-mail"></span><h2>send_mail()<a class="headerlink" href="#send-mail" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="django.core.mail.send_mail">
<tt class="descname">send_mail</tt>(<em>subject</em>, <em>message</em>, <em>from_email</em>, <em>recipient_list</em>, <em>fail_silently=False</em>, <em>auth_user=None</em>, <em>auth_password=None</em>, <em>connection=None</em>)<a class="reference internal" href="../_modules/django/core/mail.html#send_mail"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.mail.send_mail" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The simplest way to send email is using
<tt class="docutils literal"><span class="pre">django.core.mail.send_mail()</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">subject</span></tt>, <tt class="docutils literal"><span class="pre">message</span></tt>, <tt class="docutils literal"><span class="pre">from_email</span></tt> and <tt class="docutils literal"><span class="pre">recipient_list</span></tt> parameters
are required.</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">subject</span></tt>: A string.</li>
<li><tt class="docutils literal"><span class="pre">message</span></tt>: A string.</li>
<li><tt class="docutils literal"><span class="pre">from_email</span></tt>: A string.</li>
<li><tt class="docutils literal"><span class="pre">recipient_list</span></tt>: A list of strings, each an email address. Each
member of <tt class="docutils literal"><span class="pre">recipient_list</span></tt> will see the other recipients in the “To:”
field of the email message.</li>
<li><tt class="docutils literal"><span class="pre">fail_silently</span></tt>: A boolean. If it’s <tt class="docutils literal"><span class="pre">False</span></tt>, <tt class="docutils literal"><span class="pre">send_mail</span></tt> will raise
an <tt class="xref py py-exc docutils literal"><span class="pre">smtplib.SMTPException</span></tt>. See the <tt class="xref py py-mod docutils literal"><span class="pre">smtplib</span></tt> docs for a list of
possible exceptions, all of which are subclasses of
<tt class="xref py py-exc docutils literal"><span class="pre">SMTPException</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">auth_user</span></tt>: The optional username to use to authenticate to the SMTP
server. If this isn’t provided, Django will use the value of the
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST_USER"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST_USER</span></tt></a> setting.</li>
<li><tt class="docutils literal"><span class="pre">auth_password</span></tt>: The optional password to use to authenticate to the
SMTP server. If this isn’t provided, Django will use the value of the
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST_PASSWORD"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST_PASSWORD</span></tt></a> setting.</li>
<li><tt class="docutils literal"><span class="pre">connection</span></tt>: The optional email backend to use to send the mail.
If unspecified, an instance of the default backend will be used.
See the documentation on <a class="reference internal" href="#topic-email-backends"><em>Email backends</em></a>
for more details.</li>
</ul>
</div>
<div class="section" id="s-send-mass-mail">
<span id="send-mass-mail"></span><h2>send_mass_mail()<a class="headerlink" href="#send-mass-mail" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="django.core.mail.send_mass_mail">
<tt class="descname">send_mass_mail</tt>(<em>datatuple</em>, <em>fail_silently=False</em>, <em>auth_user=None</em>, <em>auth_password=None</em>, <em>connection=None</em>)<a class="reference internal" href="../_modules/django/core/mail.html#send_mass_mail"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.mail.send_mass_mail" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><tt class="docutils literal"><span class="pre">django.core.mail.send_mass_mail()</span></tt> is intended to handle mass emailing.</p>
<p><tt class="docutils literal"><span class="pre">datatuple</span></tt> is a tuple in which each element is in this format:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="n">subject</span><span class="p">,</span> <span class="n">message</span><span class="p">,</span> <span class="n">from_email</span><span class="p">,</span> <span class="n">recipient_list</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fail_silently</span></tt>, <tt class="docutils literal"><span class="pre">auth_user</span></tt> and <tt class="docutils literal"><span class="pre">auth_password</span></tt> have the same functions
as in <a class="reference internal" href="#django.core.mail.send_mail" title="django.core.mail.send_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mail()</span></tt></a>.</p>
<p>Each separate element of <tt class="docutils literal"><span class="pre">datatuple</span></tt> results in a separate email message.
As in <a class="reference internal" href="#django.core.mail.send_mail" title="django.core.mail.send_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mail()</span></tt></a>, recipients in the same
<tt class="docutils literal"><span class="pre">recipient_list</span></tt> will all see the other addresses in the email messages’
“To:” field.</p>
<p>For example, the following code would send two different messages to
two different sets of recipients; however, only one connection to the
mail server would be opened:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">message1</span> <span class="o">=</span> <span class="p">(</span><span class="s">'Subject here'</span><span class="p">,</span> <span class="s">'Here is the message'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span> <span class="p">[</span><span class="s">'first@example.com'</span><span class="p">,</span> <span class="s">'other@example.com'</span><span class="p">])</span>
<span class="n">message2</span> <span class="o">=</span> <span class="p">(</span><span class="s">'Another Subject'</span><span class="p">,</span> <span class="s">'Here is another message'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span> <span class="p">[</span><span class="s">'second@test.com'</span><span class="p">])</span>
<span class="n">send_mass_mail</span><span class="p">((</span><span class="n">message1</span><span class="p">,</span> <span class="n">message2</span><span class="p">),</span> <span class="n">fail_silently</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="s-send-mass-mail-vs-send-mail">
<span id="send-mass-mail-vs-send-mail"></span><h3>send_mass_mail() vs. send_mail()<a class="headerlink" href="#send-mass-mail-vs-send-mail" title="Permalink to this headline">¶</a></h3>
<p>The main difference between <a class="reference internal" href="#django.core.mail.send_mass_mail" title="django.core.mail.send_mass_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mass_mail()</span></tt></a> and
<a class="reference internal" href="#django.core.mail.send_mail" title="django.core.mail.send_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mail()</span></tt></a> is that
<a class="reference internal" href="#django.core.mail.send_mail" title="django.core.mail.send_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mail()</span></tt></a> opens a connection to the mail server
each time it’s executed, while <a class="reference internal" href="#django.core.mail.send_mass_mail" title="django.core.mail.send_mass_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mass_mail()</span></tt></a> uses
a single connection for all of its messages. This makes
<a class="reference internal" href="#django.core.mail.send_mass_mail" title="django.core.mail.send_mass_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mass_mail()</span></tt></a> slightly more efficient.</p>
</div>
</div>
<div class="section" id="s-mail-admins">
<span id="mail-admins"></span><h2>mail_admins()<a class="headerlink" href="#mail-admins" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="django.core.mail.mail_admins">
<tt class="descname">mail_admins</tt>(<em>subject</em>, <em>message</em>, <em>fail_silently=False</em>, <em>connection=None</em>, <em>html_message=None</em>)<a class="reference internal" href="../_modules/django/core/mail.html#mail_admins"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.mail.mail_admins" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><tt class="docutils literal"><span class="pre">django.core.mail.mail_admins()</span></tt> is a shortcut for sending an email to the
site admins, as defined in the <a class="reference internal" href="../ref/settings.html#std:setting-ADMINS"><tt class="xref std std-setting docutils literal"><span class="pre">ADMINS</span></tt></a> setting.</p>
<p><tt class="docutils literal"><span class="pre">mail_admins()</span></tt> prefixes the subject with the value of the
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_SUBJECT_PREFIX"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_SUBJECT_PREFIX</span></tt></a> setting, which is <tt class="docutils literal"><span class="pre">"[Django]</span> <span class="pre">"</span></tt> by default.</p>
<p>The “From:” header of the email will be the value of the
<a class="reference internal" href="../ref/settings.html#std:setting-SERVER_EMAIL"><tt class="xref std std-setting docutils literal"><span class="pre">SERVER_EMAIL</span></tt></a> setting.</p>
<p>This method exists for convenience and readability.</p>
<p>If <tt class="docutils literal"><span class="pre">html_message</span></tt> is provided, the resulting email will be a
<em class="mimetype">multipart/alternative</em> email with <tt class="docutils literal"><span class="pre">message</span></tt> as the
<em class="mimetype">text/plain</em> content type and <tt class="docutils literal"><span class="pre">html_message</span></tt> as the
<em class="mimetype">text/html</em> content type.</p>
</div>
<div class="section" id="s-mail-managers">
<span id="mail-managers"></span><h2>mail_managers()<a class="headerlink" href="#mail-managers" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="django.core.mail.mail_managers">
<tt class="descname">mail_managers</tt>(<em>subject</em>, <em>message</em>, <em>fail_silently=False</em>, <em>connection=None</em>, <em>html_message=None</em>)<a class="reference internal" href="../_modules/django/core/mail.html#mail_managers"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.mail.mail_managers" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><tt class="docutils literal"><span class="pre">django.core.mail.mail_managers()</span></tt> is just like <tt class="docutils literal"><span class="pre">mail_admins()</span></tt>, except it
sends an email to the site managers, as defined in the <a class="reference internal" href="../ref/settings.html#std:setting-MANAGERS"><tt class="xref std std-setting docutils literal"><span class="pre">MANAGERS</span></tt></a>
setting.</p>
</div>
<div class="section" id="s-examples">
<span id="examples"></span><h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>This sends a single email to <a class="reference external" href="mailto:john%40example.com">john<span>@</span>example<span>.</span>com</a> and <a class="reference external" href="mailto:jane%40example.com">jane<span>@</span>example<span>.</span>com</a>, with them
both appearing in the “To:”:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">send_mail</span><span class="p">(</span><span class="s">'Subject'</span><span class="p">,</span> <span class="s">'Message.'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span>
<span class="p">[</span><span class="s">'john@example.com'</span><span class="p">,</span> <span class="s">'jane@example.com'</span><span class="p">])</span>
</pre></div>
</div>
<p>This sends a message to <a class="reference external" href="mailto:john%40example.com">john<span>@</span>example<span>.</span>com</a> and <a class="reference external" href="mailto:jane%40example.com">jane<span>@</span>example<span>.</span>com</a>, with them both
receiving a separate email:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">datatuple</span> <span class="o">=</span> <span class="p">(</span>
<span class="p">(</span><span class="s">'Subject'</span><span class="p">,</span> <span class="s">'Message.'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span> <span class="p">[</span><span class="s">'john@example.com'</span><span class="p">]),</span>
<span class="p">(</span><span class="s">'Subject'</span><span class="p">,</span> <span class="s">'Message.'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span> <span class="p">[</span><span class="s">'jane@example.com'</span><span class="p">]),</span>
<span class="p">)</span>
<span class="n">send_mass_mail</span><span class="p">(</span><span class="n">datatuple</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-preventing-header-injection">
<span id="preventing-header-injection"></span><h2>Preventing header injection<a class="headerlink" href="#preventing-header-injection" title="Permalink to this headline">¶</a></h2>
<p><a class="reference external" href="http://www.nyphp.org/phundamentals/8_Preventing-Email-Header-Injection">Header injection</a> is a security exploit in which an attacker inserts extra
email headers to control the “To:” and “From:” in email messages that your
scripts generate.</p>
<p>The Django email functions outlined above all protect against header injection
by forbidding newlines in header values. If any <tt class="docutils literal"><span class="pre">subject</span></tt>, <tt class="docutils literal"><span class="pre">from_email</span></tt> or
<tt class="docutils literal"><span class="pre">recipient_list</span></tt> contains a newline (in either Unix, Windows or Mac style),
the email function (e.g. <a class="reference internal" href="#django.core.mail.send_mail" title="django.core.mail.send_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mail()</span></tt></a>) will raise
<tt class="docutils literal"><span class="pre">django.core.mail.BadHeaderError</span></tt> (a subclass of <tt class="docutils literal"><span class="pre">ValueError</span></tt>) and, hence,
will not send the email. It’s your responsibility to validate all data before
passing it to the email functions.</p>
<p>If a <tt class="docutils literal"><span class="pre">message</span></tt> contains headers at the start of the string, the headers will
simply be printed as the first bit of the email message.</p>
<p>Here’s an example view that takes a <tt class="docutils literal"><span class="pre">subject</span></tt>, <tt class="docutils literal"><span class="pre">message</span></tt> and <tt class="docutils literal"><span class="pre">from_email</span></tt>
from the request’s POST data, sends that to <a class="reference external" href="mailto:admin%40example.com">admin<span>@</span>example<span>.</span>com</a> and redirects to
“/contact/thanks/” when it’s done:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core.mail</span> <span class="kn">import</span> <span class="n">send_mail</span><span class="p">,</span> <span class="n">BadHeaderError</span>
<span class="k">def</span> <span class="nf">send_email</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="n">subject</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'subject'</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span>
<span class="n">message</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'message'</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span>
<span class="n">from_email</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'from_email'</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span>
<span class="k">if</span> <span class="n">subject</span> <span class="ow">and</span> <span class="n">message</span> <span class="ow">and</span> <span class="n">from_email</span><span class="p">:</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">send_mail</span><span class="p">(</span><span class="n">subject</span><span class="p">,</span> <span class="n">message</span><span class="p">,</span> <span class="n">from_email</span><span class="p">,</span> <span class="p">[</span><span class="s">'admin@example.com'</span><span class="p">])</span>
<span class="k">except</span> <span class="n">BadHeaderError</span><span class="p">:</span>
<span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="s">'Invalid header found.'</span><span class="p">)</span>
<span class="k">return</span> <span class="n">HttpResponseRedirect</span><span class="p">(</span><span class="s">'/contact/thanks/'</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="c"># In reality we'd use a form class</span>
<span class="c"># to get proper validation errors.</span>
<span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="s">'Make sure all fields are entered and valid.'</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-the-emailmessage-class">
<span id="s-emailmessage-and-smtpconnection"></span><span id="the-emailmessage-class"></span><span id="emailmessage-and-smtpconnection"></span><h2>The EmailMessage class<a class="headerlink" href="#the-emailmessage-class" title="Permalink to this headline">¶</a></h2>
<p>Django’s <a class="reference internal" href="#django.core.mail.send_mail" title="django.core.mail.send_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mail()</span></tt></a> and
<a class="reference internal" href="#django.core.mail.send_mass_mail" title="django.core.mail.send_mass_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mass_mail()</span></tt></a> functions are actually thin
wrappers that make use of the <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> class.</p>
<p>Not all features of the <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> class are
available through the <a class="reference internal" href="#django.core.mail.send_mail" title="django.core.mail.send_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mail()</span></tt></a> and related
wrapper functions. If you wish to use advanced features, such as BCC’ed
recipients, file attachments, or multi-part email, you’ll need to create
<a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> instances directly.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This is a design feature. <a class="reference internal" href="#django.core.mail.send_mail" title="django.core.mail.send_mail"><tt class="xref py py-meth docutils literal"><span class="pre">send_mail()</span></tt></a> and
related functions were originally the only interface Django provided.
However, the list of parameters they accepted was slowly growing over
time. It made sense to move to a more object-oriented design for email
messages and retain the original functions only for backwards
compatibility.</p>
</div>
<p><a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> is responsible for creating the email
message itself. The <a class="reference internal" href="#topic-email-backends"><em>email backend</em></a> is then
responsible for sending the email.</p>
<p>For convenience, <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> provides a simple
<tt class="docutils literal"><span class="pre">send()</span></tt> method for sending a single email. If you need to send multiple
messages, the email backend API <a class="reference internal" href="#topics-sending-multiple-emails"><em>provides an alternative</em></a>.</p>
<div class="section" id="s-emailmessage-objects">
<span id="emailmessage-objects"></span><h3>EmailMessage Objects<a class="headerlink" href="#emailmessage-objects" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.core.mail.EmailMessage">
<em class="property">class </em><tt class="descname">EmailMessage</tt><a class="headerlink" href="#django.core.mail.EmailMessage" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> class is initialized with the
following parameters (in the given order, if positional arguments are used).
All parameters are optional and can be set at any time prior to calling the
<tt class="docutils literal"><span class="pre">send()</span></tt> method.</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">subject</span></tt>: The subject line of the email.</li>
<li><tt class="docutils literal"><span class="pre">body</span></tt>: The body text. This should be a plain text message.</li>
<li><tt class="docutils literal"><span class="pre">from_email</span></tt>: The sender’s address. Both <tt class="docutils literal"><span class="pre">fred@example.com</span></tt> and
<tt class="docutils literal"><span class="pre">Fred</span> <span class="pre"><fred@example.com></span></tt> forms are legal. If omitted, the
<a class="reference internal" href="../ref/settings.html#std:setting-DEFAULT_FROM_EMAIL"><tt class="xref std std-setting docutils literal"><span class="pre">DEFAULT_FROM_EMAIL</span></tt></a> setting is used.</li>
<li><tt class="docutils literal"><span class="pre">to</span></tt>: A list or tuple of recipient addresses.</li>
<li><tt class="docutils literal"><span class="pre">bcc</span></tt>: A list or tuple of addresses used in the “Bcc” header when
sending the email.</li>
<li><tt class="docutils literal"><span class="pre">connection</span></tt>: An email backend instance. Use this parameter if
you want to use the same connection for multiple messages. If omitted, a
new connection is created when <tt class="docutils literal"><span class="pre">send()</span></tt> is called.</li>
<li><tt class="docutils literal"><span class="pre">attachments</span></tt>: A list of attachments to put on the message. These can
be either <tt class="docutils literal"><span class="pre">email.MIMEBase.MIMEBase</span></tt> instances, or <tt class="docutils literal"><span class="pre">(filename,</span>
<span class="pre">content,</span> <span class="pre">mimetype)</span></tt> triples.</li>
<li><tt class="docutils literal"><span class="pre">headers</span></tt>: A dictionary of extra headers to put on the message. The
keys are the header name, values are the header values. It’s up to the
caller to ensure header names and values are in the correct format for
an email message. The corresponding attribute is <tt class="docutils literal"><span class="pre">extra_headers</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">cc</span></tt>: A list or tuple of recipient addresses used in the “Cc” header
when sending the email.</li>
</ul>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">email</span> <span class="o">=</span> <span class="n">EmailMessage</span><span class="p">(</span><span class="s">'Hello'</span><span class="p">,</span> <span class="s">'Body goes here'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span>
<span class="p">[</span><span class="s">'to1@example.com'</span><span class="p">,</span> <span class="s">'to2@example.com'</span><span class="p">],</span> <span class="p">[</span><span class="s">'bcc@example.com'</span><span class="p">],</span>
<span class="n">headers</span> <span class="o">=</span> <span class="p">{</span><span class="s">'Reply-To'</span><span class="p">:</span> <span class="s">'another@example.com'</span><span class="p">})</span>
</pre></div>
</div>
<p>The class has the following methods:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">send(fail_silently=False)</span></tt> sends the message. If a connection was
specified when the email was constructed, that connection will be used.
Otherwise, an instance of the default backend will be instantiated and
used. If the keyword argument <tt class="docutils literal"><span class="pre">fail_silently</span></tt> is <tt class="docutils literal"><span class="pre">True</span></tt>, exceptions
raised while sending the message will be quashed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">message()</span></tt> constructs a <tt class="docutils literal"><span class="pre">django.core.mail.SafeMIMEText</span></tt> object (a
subclass of Python’s <tt class="docutils literal"><span class="pre">email.MIMEText.MIMEText</span></tt> class) or a
<tt class="docutils literal"><span class="pre">django.core.mail.SafeMIMEMultipart</span></tt> object holding the message to be
sent. If you ever need to extend the
<a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> class, you’ll probably want to
override this method to put the content you want into the MIME object.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">recipients()</span></tt> returns a list of all the recipients of the message,
whether they’re recorded in the <tt class="docutils literal"><span class="pre">to</span></tt>, <tt class="docutils literal"><span class="pre">cc</span></tt> or <tt class="docutils literal"><span class="pre">bcc</span></tt> attributes. This
is another method you might need to override when subclassing, 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.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">attach()</span></tt> creates a new file attachment and adds it to the message.
There are two ways to call <tt class="docutils literal"><span class="pre">attach()</span></tt>:</p>
<ul>
<li><p class="first">You can pass it a single argument that is an
<tt class="docutils literal"><span class="pre">email.MIMEBase.MIMEBase</span></tt> instance. This will be inserted directly
into the resulting message.</p>
</li>
<li><p class="first">Alternatively, you can pass <tt class="docutils literal"><span class="pre">attach()</span></tt> three arguments:
<tt class="docutils literal"><span class="pre">filename</span></tt>, <tt class="docutils literal"><span class="pre">content</span></tt> and <tt class="docutils literal"><span class="pre">mimetype</span></tt>. <tt class="docutils literal"><span class="pre">filename</span></tt> is the name
of the file attachment as it will appear in the email, <tt class="docutils literal"><span class="pre">content</span></tt> is
the data that will be contained inside the attachment and
<tt class="docutils literal"><span class="pre">mimetype</span></tt> is the optional MIME type for the attachment. If you
omit <tt class="docutils literal"><span class="pre">mimetype</span></tt>, the MIME content type will be guessed from the
filename of the attachment.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">message</span><span class="o">.</span><span class="n">attach</span><span class="p">(</span><span class="s">'design.png'</span><span class="p">,</span> <span class="n">img_data</span><span class="p">,</span> <span class="s">'image/png'</span><span class="p">)</span>
</pre></div>
</div>
</li>
</ul>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">attach_file()</span></tt> 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:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">message</span><span class="o">.</span><span class="n">attach_file</span><span class="p">(</span><span class="s">'/images/weather_map.png'</span><span class="p">)</span>
</pre></div>
</div>
</li>
</ul>
<div class="section" id="s-sending-alternative-content-types">
<span id="sending-alternative-content-types"></span><h4>Sending alternative content types<a class="headerlink" href="#sending-alternative-content-types" title="Permalink to this headline">¶</a></h4>
<p>It can be useful to include multiple versions of the content in an email; the
classic example is to send both text and HTML versions of a message. With
Django’s email library, you can do this using the <tt class="docutils literal"><span class="pre">EmailMultiAlternatives</span></tt>
class. This subclass of <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> has an
<tt class="docutils literal"><span class="pre">attach_alternative()</span></tt> method for including extra versions of the message
body in the email. All the other methods (including the class initialization)
are inherited directly from <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a>.</p>
<p>To send a text and HTML combination, you could write:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core.mail</span> <span class="kn">import</span> <span class="n">EmailMultiAlternatives</span>
<span class="n">subject</span><span class="p">,</span> <span class="n">from_email</span><span class="p">,</span> <span class="n">to</span> <span class="o">=</span> <span class="s">'hello'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span> <span class="s">'to@example.com'</span>
<span class="n">text_content</span> <span class="o">=</span> <span class="s">'This is an important message.'</span>
<span class="n">html_content</span> <span class="o">=</span> <span class="s">'<p>This is an <strong>important</strong> message.</p>'</span>
<span class="n">msg</span> <span class="o">=</span> <span class="n">EmailMultiAlternatives</span><span class="p">(</span><span class="n">subject</span><span class="p">,</span> <span class="n">text_content</span><span class="p">,</span> <span class="n">from_email</span><span class="p">,</span> <span class="p">[</span><span class="n">to</span><span class="p">])</span>
<span class="n">msg</span><span class="o">.</span><span class="n">attach_alternative</span><span class="p">(</span><span class="n">html_content</span><span class="p">,</span> <span class="s">"text/html"</span><span class="p">)</span>
<span class="n">msg</span><span class="o">.</span><span class="n">send</span><span class="p">()</span>
</pre></div>
</div>
<p>By default, the MIME type of the <tt class="docutils literal"><span class="pre">body</span></tt> parameter in an
<a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> is <tt class="docutils literal"><span class="pre">"text/plain"</span></tt>. It is good
practice to leave this alone, because it guarantees that any recipient will be
able to read the email, regardless of their mail client. However, if you are
confident that your recipients can handle an alternative content type, you can
use the <tt class="docutils literal"><span class="pre">content_subtype</span></tt> attribute on the
<a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> class to change the main content type.
The major type will always be <tt class="docutils literal"><span class="pre">"text"</span></tt>, but you can change the
subtype. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">msg</span> <span class="o">=</span> <span class="n">EmailMessage</span><span class="p">(</span><span class="n">subject</span><span class="p">,</span> <span class="n">html_content</span><span class="p">,</span> <span class="n">from_email</span><span class="p">,</span> <span class="p">[</span><span class="n">to</span><span class="p">])</span>
<span class="n">msg</span><span class="o">.</span><span class="n">content_subtype</span> <span class="o">=</span> <span class="s">"html"</span> <span class="c"># Main content is now text/html</span>
<span class="n">msg</span><span class="o">.</span><span class="n">send</span><span class="p">()</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="s-email-backends">
<span id="s-topic-email-backends"></span><span id="email-backends"></span><span id="topic-email-backends"></span><h2>Email backends<a class="headerlink" href="#email-backends" title="Permalink to this headline">¶</a></h2>
<p>The actual sending of an email is handled by the email backend.</p>
<p>The email backend class has the following methods:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">open()</span></tt> instantiates an long-lived email-sending connection.</li>
<li><tt class="docutils literal"><span class="pre">close()</span></tt> closes the current email-sending connection.</li>
<li><tt class="docutils literal"><span class="pre">send_messages(email_messages)</span></tt> sends a list of
<a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> objects. If the connection is
not open, this call will implicitly open the connection, and close the
connection afterwards. If the connection is already open, it will be
left open after mail has been sent.</li>
</ul>
<div class="section" id="s-obtaining-an-instance-of-an-email-backend">
<span id="obtaining-an-instance-of-an-email-backend"></span><h3>Obtaining an instance of an email backend<a class="headerlink" href="#obtaining-an-instance-of-an-email-backend" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#django.core.mail.get_connection" title="django.core.mail.get_connection"><tt class="xref py py-meth docutils literal"><span class="pre">get_connection()</span></tt></a> function in <tt class="docutils literal"><span class="pre">django.core.mail</span></tt> returns an
instance of the email backend that you can use.</p>
<dl class="function">
<dt id="django.core.mail.get_connection">
<tt class="descname">get_connection</tt>(<em>backend=None</em>, <em>fail_silently=False</em>, <em>*args</em>, <em>**kwargs</em>)<a class="reference internal" href="../_modules/django/core/mail.html#get_connection"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.mail.get_connection" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>By default, a call to <tt class="docutils literal"><span class="pre">get_connection()</span></tt> will return an instance of the
email backend specified in <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_BACKEND"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_BACKEND</span></tt></a>. If you specify the
<tt class="docutils literal"><span class="pre">backend</span></tt> argument, an instance of that backend will be instantiated.</p>
<p>The <tt class="docutils literal"><span class="pre">fail_silently</span></tt> argument controls how the backend should handle errors.
If <tt class="docutils literal"><span class="pre">fail_silently</span></tt> is True, exceptions during the email sending process
will be silently ignored.</p>
<p>All other arguments are passed directly to the constructor of the
email backend.</p>
<p>Django ships with several email sending backends. With the exception of the
SMTP backend (which is the default), these backends are only useful during
testing and development. If you have special email sending requirements, you
can <a class="reference internal" href="#topic-custom-email-backend"><em>write your own email backend</em></a>.</p>
<div class="section" id="s-smtp-backend">
<span id="s-topic-email-smtp-backend"></span><span id="smtp-backend"></span><span id="topic-email-smtp-backend"></span><h4>SMTP backend<a class="headerlink" href="#smtp-backend" title="Permalink to this headline">¶</a></h4>
<p>This is the default backend. Email will be sent through a SMTP server.
The server address and authentication credentials are set in the
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST</span></tt></a>, <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_PORT"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_PORT</span></tt></a>, <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST_USER"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST_USER</span></tt></a>,
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST_PASSWORD"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST_PASSWORD</span></tt></a> and <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_USE_TLS"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_USE_TLS</span></tt></a> settings in your
settings file.</p>
<p>The SMTP backend is the default configuration inherited by Django. If you
want to specify it explicitly, put the following in your settings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">EMAIL_BACKEND</span> <span class="o">=</span> <span class="s">'django.core.mail.backends.smtp.EmailBackend'</span>
</pre></div>
</div>
</div>
<div class="section" id="s-console-backend">
<span id="s-topic-email-console-backend"></span><span id="console-backend"></span><span id="topic-email-console-backend"></span><h4>Console backend<a class="headerlink" href="#console-backend" title="Permalink to this headline">¶</a></h4>
<p>Instead of sending out real emails the console backend just writes the
emails that would be sent to the standard output. By default, the console
backend writes to <tt class="docutils literal"><span class="pre">stdout</span></tt>. You can use a different stream-like object by
providing the <tt class="docutils literal"><span class="pre">stream</span></tt> keyword argument when constructing the connection.</p>
<p>To specify this backend, put the following in your settings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">EMAIL_BACKEND</span> <span class="o">=</span> <span class="s">'django.core.mail.backends.console.EmailBackend'</span>
</pre></div>
</div>
<p>This backend is not intended for use in production – it is provided as a
convenience that can be used during development.</p>
</div>
<div class="section" id="s-file-backend">
<span id="s-topic-email-file-backend"></span><span id="file-backend"></span><span id="topic-email-file-backend"></span><h4>File backend<a class="headerlink" href="#file-backend" title="Permalink to this headline">¶</a></h4>
<p>The file backend writes emails to a file. A new file is created for each new
session that is opened on this backend. The directory to which the files are
written is either taken from the <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_FILE_PATH"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_FILE_PATH</span></tt></a> setting or from
the <tt class="docutils literal"><span class="pre">file_path</span></tt> keyword when creating a connection with
<a class="reference internal" href="#django.core.mail.get_connection" title="django.core.mail.get_connection"><tt class="xref py py-meth docutils literal"><span class="pre">get_connection()</span></tt></a>.</p>
<p>To specify this backend, put the following in your settings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">EMAIL_BACKEND</span> <span class="o">=</span> <span class="s">'django.core.mail.backends.filebased.EmailBackend'</span>
<span class="n">EMAIL_FILE_PATH</span> <span class="o">=</span> <span class="s">'/tmp/app-messages'</span> <span class="c"># change this to a proper location</span>
</pre></div>
</div>
<p>This backend is not intended for use in production – it is provided as a
convenience that can be used during development.</p>
</div>
<div class="section" id="s-in-memory-backend">
<span id="s-topic-email-memory-backend"></span><span id="in-memory-backend"></span><span id="topic-email-memory-backend"></span><h4>In-memory backend<a class="headerlink" href="#in-memory-backend" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">'locmem'</span></tt> backend stores messages in a special attribute of the
<tt class="docutils literal"><span class="pre">django.core.mail</span></tt> module. The <tt class="docutils literal"><span class="pre">outbox</span></tt> attribute is created when the
first message is sent. It’s a list with an
<a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> instance for each message that would
be sent.</p>
<p>To specify this backend, put the following in your settings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">EMAIL_BACKEND</span> <span class="o">=</span> <span class="s">'django.core.mail.backends.locmem.EmailBackend'</span>
</pre></div>
</div>
<p>This backend is not intended for use in production – it is provided as a
convenience that can be used during development and testing.</p>
</div>
<div class="section" id="s-dummy-backend">
<span id="s-topic-email-dummy-backend"></span><span id="dummy-backend"></span><span id="topic-email-dummy-backend"></span><h4>Dummy backend<a class="headerlink" href="#dummy-backend" title="Permalink to this headline">¶</a></h4>
<p>As the name suggests the dummy backend does nothing with your messages. To
specify this backend, put the following in your settings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">EMAIL_BACKEND</span> <span class="o">=</span> <span class="s">'django.core.mail.backends.dummy.EmailBackend'</span>
</pre></div>
</div>
<p>This backend is not intended for use in production – it is provided as a
convenience that can be used during development.</p>
</div>
</div>
<div class="section" id="s-defining-a-custom-email-backend">
<span id="s-topic-custom-email-backend"></span><span id="defining-a-custom-email-backend"></span><span id="topic-custom-email-backend"></span><h3>Defining a custom email backend<a class="headerlink" href="#defining-a-custom-email-backend" title="Permalink to this headline">¶</a></h3>
<p>If you need to change how emails are sent you can write your own email
backend. The <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_BACKEND"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_BACKEND</span></tt></a> setting in your settings file is then
the Python import path for your backend class.</p>
<p>Custom email backends should subclass <tt class="docutils literal"><span class="pre">BaseEmailBackend</span></tt> that is located in
the <tt class="docutils literal"><span class="pre">django.core.mail.backends.base</span></tt> module. A custom email backend must
implement the <tt class="docutils literal"><span class="pre">send_messages(email_messages)</span></tt> method. This method receives a
list of <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> instances and returns the
number of successfully delivered messages. If your backend has any concept of
a persistent session or connection, you should also implement the <tt class="docutils literal"><span class="pre">open()</span></tt>
and <tt class="docutils literal"><span class="pre">close()</span></tt> methods. Refer to <tt class="docutils literal"><span class="pre">smtp.EmailBackend</span></tt> for a reference
implementation.</p>
</div>
<div class="section" id="s-sending-multiple-emails">
<span id="s-topics-sending-multiple-emails"></span><span id="sending-multiple-emails"></span><span id="topics-sending-multiple-emails"></span><h3>Sending multiple emails<a class="headerlink" href="#sending-multiple-emails" title="Permalink to this headline">¶</a></h3>
<p>Establishing and closing an SMTP connection (or any other network connection,
for that matter) is an expensive process. If you have a lot of emails to send,
it makes sense to reuse an SMTP connection, rather than creating and
destroying a connection every time you want to send an email.</p>
<p>There are two ways you tell an email backend to reuse a connection.</p>
<p>Firstly, you can use the <tt class="docutils literal"><span class="pre">send_messages()</span></tt> method. <tt class="docutils literal"><span class="pre">send_messages()</span></tt> takes
a list of <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> instances (or subclasses),
and sends them all using a single connection.</p>
<p>For example, if you have a function called <tt class="docutils literal"><span class="pre">get_notification_email()</span></tt> that
returns a list of <a class="reference internal" href="#django.core.mail.EmailMessage" title="django.core.mail.EmailMessage"><tt class="xref py py-class docutils literal"><span class="pre">EmailMessage</span></tt></a> objects representing
some periodic email you wish to send out, you could send these emails using
a single call to send_messages:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core</span> <span class="kn">import</span> <span class="n">mail</span>
<span class="n">connection</span> <span class="o">=</span> <span class="n">mail</span><span class="o">.</span><span class="n">get_connection</span><span class="p">()</span> <span class="c"># Use default email connection</span>
<span class="n">messages</span> <span class="o">=</span> <span class="n">get_notification_email</span><span class="p">()</span>
<span class="n">connection</span><span class="o">.</span><span class="n">send_messages</span><span class="p">(</span><span class="n">messages</span><span class="p">)</span>
</pre></div>
</div>
<p>In this example, the call to <tt class="docutils literal"><span class="pre">send_messages()</span></tt> opens a connection on the
backend, sends the list of messages, and then closes the connection again.</p>
<p>The second approach is to use the <tt class="docutils literal"><span class="pre">open()</span></tt> and <tt class="docutils literal"><span class="pre">close()</span></tt> methods on the
email backend to manually control the connection. <tt class="docutils literal"><span class="pre">send_messages()</span></tt> will not
manually open or close the connection if it is already open, so if you
manually open the connection, you can control when it is closed. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core</span> <span class="kn">import</span> <span class="n">mail</span>
<span class="n">connection</span> <span class="o">=</span> <span class="n">mail</span><span class="o">.</span><span class="n">get_connection</span><span class="p">()</span>
<span class="c"># Manually open the connection</span>
<span class="n">connection</span><span class="o">.</span><span class="n">open</span><span class="p">()</span>
<span class="c"># Construct an email message that uses the connection</span>
<span class="n">email1</span> <span class="o">=</span> <span class="n">mail</span><span class="o">.</span><span class="n">EmailMessage</span><span class="p">(</span><span class="s">'Hello'</span><span class="p">,</span> <span class="s">'Body goes here'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span>
<span class="p">[</span><span class="s">'to1@example.com'</span><span class="p">],</span> <span class="n">connection</span><span class="o">=</span><span class="n">connection</span><span class="p">)</span>
<span class="n">email1</span><span class="o">.</span><span class="n">send</span><span class="p">()</span> <span class="c"># Send the email</span>
<span class="c"># Construct two more messages</span>
<span class="n">email2</span> <span class="o">=</span> <span class="n">mail</span><span class="o">.</span><span class="n">EmailMessage</span><span class="p">(</span><span class="s">'Hello'</span><span class="p">,</span> <span class="s">'Body goes here'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span>
<span class="p">[</span><span class="s">'to2@example.com'</span><span class="p">])</span>
<span class="n">email3</span> <span class="o">=</span> <span class="n">mail</span><span class="o">.</span><span class="n">EmailMessage</span><span class="p">(</span><span class="s">'Hello'</span><span class="p">,</span> <span class="s">'Body goes here'</span><span class="p">,</span> <span class="s">'from@example.com'</span><span class="p">,</span>
<span class="p">[</span><span class="s">'to3@example.com'</span><span class="p">])</span>
<span class="c"># Send the two emails in a single call -</span>
<span class="n">connection</span><span class="o">.</span><span class="n">send_messages</span><span class="p">([</span><span class="n">email2</span><span class="p">,</span> <span class="n">email3</span><span class="p">])</span>
<span class="c"># The connection was already open so send_messages() doesn't close it.</span>
<span class="c"># We need to manually close the connection.</span>
<span class="n">connection</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-configuring-email-for-development">
<span id="configuring-email-for-development"></span><h2>Configuring email for development<a class="headerlink" href="#configuring-email-for-development" title="Permalink to this headline">¶</a></h2>
<p>There are times when you do not want Django to send emails at
all. For example, while developing a Web site, you probably don’t want
to send out thousands of emails – but you may want to validate that
emails will be sent to the right people under the right conditions,
and that those emails will contain the correct content.</p>
<p>The easiest way to configure email for local development is to use the
<a class="reference internal" href="#topic-email-console-backend"><em>console</em></a> email backend. This backend
redirects all email to stdout, allowing you to inspect the content of mail.</p>
<p>The <a class="reference internal" href="#topic-email-file-backend"><em>file</em></a> email backend can also be useful
during development – this backend dumps the contents of every SMTP connection
to a file that can be inspected at your leisure.</p>
<p>Another approach is to use a “dumb” SMTP server that receives the emails
locally and displays them to the terminal, but does not actually send
anything. Python has a built-in way to accomplish this with a single command:</p>
<div class="highlight-python"><pre>python -m smtpd -n -c DebuggingServer localhost:1025</pre>
</div>
<p>This command will start a simple SMTP server listening on port 1025 of
localhost. This server simply prints to standard output all email headers and
the email body. You then only need to set the <a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_HOST"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_HOST</span></tt></a> and
<a class="reference internal" href="../ref/settings.html#std:setting-EMAIL_PORT"><tt class="xref std std-setting docutils literal"><span class="pre">EMAIL_PORT</span></tt></a> accordingly. For a more detailed discussion of SMTP
server options, see the Python documentation for the <tt class="xref py py-mod docutils literal"><span class="pre">smtpd</span></tt> module.</p>
<p>For information about unit-testing the sending of emails in your application,
see the <a class="reference internal" href="testing/tools.html#topics-testing-email"><em>Email services</em></a> section of the testing documentation.</p>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Sending email</a><ul>
<li><a class="reference internal" href="#quick-example">Quick example</a></li>
<li><a class="reference internal" href="#send-mail">send_mail()</a></li>
<li><a class="reference internal" href="#send-mass-mail">send_mass_mail()</a><ul>
<li><a class="reference internal" href="#send-mass-mail-vs-send-mail">send_mass_mail() vs. send_mail()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mail-admins">mail_admins()</a></li>
<li><a class="reference internal" href="#mail-managers">mail_managers()</a></li>
<li><a class="reference internal" href="#examples">Examples</a></li>
<li><a class="reference internal" href="#preventing-header-injection">Preventing header injection</a></li>
<li><a class="reference internal" href="#the-emailmessage-class">The EmailMessage class</a><ul>
<li><a class="reference internal" href="#emailmessage-objects">EmailMessage Objects</a><ul>
<li><a class="reference internal" href="#sending-alternative-content-types">Sending alternative content types</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#email-backends">Email backends</a><ul>
<li><a class="reference internal" href="#obtaining-an-instance-of-an-email-backend">Obtaining an instance of an email backend</a><ul>
<li><a class="reference internal" href="#smtp-backend">SMTP backend</a></li>
<li><a class="reference internal" href="#console-backend">Console backend</a></li>
<li><a class="reference internal" href="#file-backend">File backend</a></li>
<li><a class="reference internal" href="#in-memory-backend">In-memory backend</a></li>
<li><a class="reference internal" href="#dummy-backend">Dummy backend</a></li>
</ul>
</li>
<li><a class="reference internal" href="#defining-a-custom-email-backend">Defining a custom email backend</a></li>
<li><a class="reference internal" href="#sending-multiple-emails">Sending multiple emails</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-email-for-development">Configuring email for development</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="signing.html">Cryptographic signing</a></li>
<li>Next: <a href="i18n/index.html">Internationalization and localization</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django 1.6.7 documentation</a>
<ul><li><a href="index.html">Using Django</a>
<ul><li>Sending email</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/topics/email.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Sep 26, 2014</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="signing.html" title="Cryptographic signing">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="i18n/index.html" title="Internationalization and localization">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
