<!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.5.8 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.5.8', 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.5.8 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.5.8 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 <a class="reference external" href="http://docs.python.org/2.7/library/smtplib.html#smtplib" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">smtplib</span></tt></a> 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="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 <a class="reference external" href="http://docs.python.org/2.7/library/smtplib.html#smtplib.SMTPException" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">smtplib.SMTPException</span></tt></a>. See the <a class="reference external" href="http://docs.python.org/2.7/library/smtplib.html#smtplib" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">smtplib</span></tt></a> docs for a list of possible exceptions, all of which are subclasses of <a class="reference external" href="http://docs.python.org/2.7/library/smtplib.html#smtplib.SMTPException" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">SMTPException</span></tt></a>.</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="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="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="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.</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="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-testing-email-sending"> <span id="testing-email-sending"></span><h2>Testing email sending<a class="headerlink" href="#testing-email-sending" 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 test your project’s use of email is to use the <tt class="docutils literal"><span class="pre">console</span></tt> email backend. This backend redirects all email to stdout, allowing you to inspect the content of mail.</p> <p>The <tt class="docutils literal"><span class="pre">file</span></tt> 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, and you are set.</p> <p>For a more detailed discussion of testing and processing of emails locally, see the Python documentation for the <a class="reference external" href="http://docs.python.org/2.7/library/smtpd.html#smtpd" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">smtpd</span></tt></a> module.</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="#testing-email-sending">Testing email sending</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.5.8 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">May 15, 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>