Although Python provides a mail sending interface via the smtplib\nmodule, Django provides a couple of light wrappers over it. These wrappers are\nprovided to make sending email extra quick, to help test email sending during\ndevelopment, and to provide support for platforms that can’t use SMTP.
The code lives in the django.core.mail module.
In two lines:
\nfrom django.core.mail import send_mail\n\nsend_mail(\n "Subject here",\n "Here is the message.",\n "from@example.com",\n ["to@example.com"],\n fail_silently=False,\n)\nMail is sent using the SMTP host and port specified in the\nEMAIL_HOST and EMAIL_PORT settings. The\nEMAIL_HOST_USER and EMAIL_HOST_PASSWORD settings, if\nset, are used to authenticate to the SMTP server, and the\nEMAIL_USE_TLS and EMAIL_USE_SSL settings control whether\na secure connection is used.
send_mail()Link to this heading#In most cases, you can send email using django.core.mail.send_mail().
The subject, message, from_email and recipient_list parameters\nare required.
subject: A string.
message: A string.
from_email: A string. If None, Django will use the value of the\nDEFAULT_FROM_EMAIL setting.
recipient_list: A list of strings, each an email address. Each\nmember of recipient_list will see the other recipients in the «To:»\nfield of the email message.
fail_silently: A boolean. When it’s False, send_mail() will raise\nan smtplib.SMTPException if an error occurs. See the smtplib\ndocs for a list of possible exceptions, all of which are subclasses of\nSMTPException.
auth_user: The optional username to use to authenticate to the SMTP\nserver. If this isn’t provided, Django will use the value of the\nEMAIL_HOST_USER setting.
auth_password: The optional password to use to authenticate to the\nSMTP server. If this isn’t provided, Django will use the value of the\nEMAIL_HOST_PASSWORD setting.
connection: The optional email backend to use to send the mail.\nIf unspecified, an instance of the default backend will be used.\nSee the documentation on Email backends\nfor more details.
html_message: If html_message is provided, the resulting email will be a\nmultipart/alternative email with message as the\ntext/plain content type and html_message as the\ntext/html content type.
The return value will be the number of successfully delivered messages (which\ncan be 0 or 1 since it can only send one message).
send_mass_mail()Link to this heading#django.core.mail.send_mass_mail() is intended to handle mass emailing.
datatuple is a tuple in which each element is in this format:
(subject, message, from_email, recipient_list)\nfail_silently, auth_user and auth_password have the same functions\nas in send_mail().
Each separate element of datatuple results in a separate email message.\nAs in send_mail(), recipients in the same\nrecipient_list will all see the other addresses in the email messages”\n«To:» field.
For example, the following code would send two different messages to\ntwo different sets of recipients; however, only one connection to the\nmail server would be opened:
\nmessage1 = (\n "Subject here",\n "Here is the message",\n "from@example.com",\n ["first@example.com", "other@example.com"],\n)\nmessage2 = (\n "Another Subject",\n "Here is another message",\n "from@example.com",\n ["second@test.com"],\n)\nsend_mass_mail((message1, message2), fail_silently=False)\nThe return value will be the number of successfully delivered messages.
\nsend_mass_mail() vs. send_mail()Link to this heading#The main difference between send_mass_mail() and\nsend_mail() is that\nsend_mail() opens a connection to the mail server\neach time it’s executed, while send_mass_mail() uses\na single connection for all of its messages. This makes\nsend_mass_mail() slightly more efficient.
mail_admins()Link to this heading#django.core.mail.mail_admins() is a shortcut for sending an email to the\nsite admins, as defined in the ADMINS setting.
mail_admins() prefixes the subject with the value of the\nEMAIL_SUBJECT_PREFIX setting, which is "[Django] " by default.
The «From:» header of the email will be the value of the\nSERVER_EMAIL setting.
This method exists for convenience and readability.
\nIf html_message is provided, the resulting email will be a\nmultipart/alternative email with message as the\ntext/plain content type and html_message as the\ntext/html content type.
mail_managers()Link to this heading#django.core.mail.mail_managers() is just like mail_admins(), except it\nsends an email to the site managers, as defined in the MANAGERS\nsetting.
This sends a single email to john@example.com and jane@example.com, with them\nboth appearing in the «To:»:
\nsend_mail(\n "Subject",\n "Message.",\n "from@example.com",\n ["john@example.com", "jane@example.com"],\n)\nThis sends a message to john@example.com and jane@example.com, with them both\nreceiving a separate email:
\ndatatuple = (\n ("Subject", "Message.", "from@example.com", ["john@example.com"]),\n ("Subject", "Message.", "from@example.com", ["jane@example.com"]),\n)\nsend_mass_mail(datatuple)\nHeader injection is a security exploit in which an attacker inserts extra\nemail headers to control the «To:» and «From:» in email messages that your\nscripts generate.
\nThe Django email functions outlined above all protect against header injection\nby forbidding newlines in header values. If any subject, from_email or\nrecipient_list contains a newline (in either Unix, Windows or Mac style),\nthe email function (e.g. send_mail()) will raise\ndjango.core.mail.BadHeaderError (a subclass of ValueError) and, hence,\nwill not send the email. It’s your responsibility to validate all data before\npassing it to the email functions.
If a message contains headers at the start of the string, the headers will\nbe printed as the first bit of the email message.
Here’s an example view that takes a subject, message and from_email\nfrom the request’s POST data, sends that to admin@example.com and redirects to\n«/contact/thanks/» when it’s done:
from django.core.mail import BadHeaderError, send_mail\nfrom django.http import HttpResponse, HttpResponseRedirect\n\n\ndef send_email(request):\n subject = request.POST.get("subject", "")\n message = request.POST.get("message", "")\n from_email = request.POST.get("from_email", "")\n if subject and message and from_email:\n try:\n send_mail(subject, message, from_email, ["admin@example.com"])\n except BadHeaderError:\n return HttpResponse("Invalid header found.")\n return HttpResponseRedirect("/contact/thanks/")\n else:\n # In reality we'd use a form class\n # to get proper validation errors.\n return HttpResponse("Make sure all fields are entered and valid.")\nEmailMessage classLink to this heading#Django’s send_mail() and\nsend_mass_mail() functions are actually thin\nwrappers that make use of the EmailMessage class.
Not all features of the EmailMessage class are\navailable through the send_mail() and related\nwrapper functions. If you wish to use advanced features, such as BCC’ed\nrecipients, file attachments, or multi-part email, you’ll need to create\nEmailMessage instances directly.
EmailMessage is responsible for creating the email\nmessage itself. The email backend is then\nresponsible for sending the email.
For convenience, EmailMessage provides a send()\nmethod for sending a single email. If you need to send multiple messages, the\nemail backend API provides an alternative.
EmailMessage ObjectsLink to this heading#The EmailMessage class is initialized with the\nfollowing parameters (in the given order, if positional arguments are used).\nAll parameters are optional and can be set at any time prior to calling the\nsend() method.
subject: The subject line of the email.
body: The body text. This should be a plain text message.
from_email: The sender’s address. Both fred@example.com and\n"Fred" <fred@example.com> forms are legal. If omitted, the\nDEFAULT_FROM_EMAIL setting is used.
to: A list or tuple of recipient addresses.
bcc: A list or tuple of addresses used in the «Bcc» header when\nsending the email.
connection: An email backend instance. Use this parameter if\nyou want to use the same connection for multiple messages. If omitted, a\nnew connection is created when send() is called.
attachments: A list of attachments to put on the message. These can\nbe either MIMEBase instances, or (filename,\ncontent, mimetype) triples.
headers: A dictionary of extra headers to put on the message. The\nkeys are the header name, values are the header values. It’s up to the\ncaller to ensure header names and values are in the correct format for\nan email message. The corresponding attribute is extra_headers.
cc: A list or tuple of recipient addresses used in the «Cc» header\nwhen sending the email.
reply_to: A list or tuple of recipient addresses used in the «Reply-To»\nheader when sending the email.
For example:
\nfrom django.core.mail import EmailMessage\n\nemail = EmailMessage(\n "Hello",\n "Body goes here",\n "from@example.com",\n ["to1@example.com", "to2@example.com"],\n ["bcc@example.com"],\n reply_to=["another@example.com"],\n headers={"Message-ID": "foo"},\n)\nThe class has the following methods:
\nsend(fail_silently=False) sends the message. If a connection was\nspecified when the email was constructed, that connection will be used.\nOtherwise, an instance of the default backend will be instantiated and\nused. If the keyword argument fail_silently is True, exceptions\nraised while sending the message will be quashed. An empty list of\nrecipients will not raise an exception. It will return 1 if the message\nwas sent successfully, otherwise 0.
message() constructs a django.core.mail.SafeMIMEText object (a\nsubclass of Python’s MIMEText class) or a\ndjango.core.mail.SafeMIMEMultipart object holding the message to be\nsent. If you ever need to extend the\nEmailMessage class, you’ll probably want to\noverride this method to put the content you want into the MIME object.
recipients() returns a list of all the recipients of the message,\nwhether they’re recorded in the to, cc or bcc attributes. This\nis another method you might need to override when subclassing, because the\nSMTP server needs to be told the full list of recipients when the message\nis sent. If you add another way to specify recipients in your class, they\nneed to be returned from this method as well.
attach() creates a new file attachment and adds it to the message.\nThere are two ways to call attach():
You can pass it a single argument that is a\nMIMEBase instance. This will be inserted directly\ninto the resulting message.
Alternatively, you can pass attach() three arguments:\nfilename, content and mimetype. filename is the name\nof the file attachment as it will appear in the email, content is\nthe data that will be contained inside the attachment and\nmimetype is the optional MIME type for the attachment. If you\nomit mimetype, the MIME content type will be guessed from the\nfilename of the attachment.
For example:
\nmessage.attach("design.png", img_data, "image/png")\nIf you specify a mimetype of message/rfc822, it will also\naccept django.core.mail.EmailMessage and\nemail.message.Message.
For a mimetype starting with text/, content is expected to\nbe a string. Binary data will be decoded using UTF-8, and if that fails,\nthe MIME type will be changed to application/octet-stream and\nthe data will be attached unchanged.
In addition, message/rfc822 attachments will no longer be\nbase64-encoded in violation of RFC 2046 Section 5.2.1, which can cause\nissues with displaying the attachments in Evolution and Thunderbird.
\nattach_file() creates a new attachment using a file from your\nfilesystem. Call it with the path of the file to attach and, optionally,\nthe MIME type to use for the attachment. If the MIME type is omitted, it\nwill be guessed from the filename. You can use it like this:
message.attach_file("/images/weather_map.png")\nFor MIME types starting with text/, binary data is handled as in\nattach().
It can be useful to include multiple versions of the content in an email; the\nclassic example is to send both text and HTML versions of a message. With\nDjango’s email library, you can do this using the EmailMultiAlternatives\nclass. This subclass of EmailMessage has an\nattach_alternative() method for including extra versions of the message\nbody in the email. All the other methods (including the class initialization)\nare inherited directly from EmailMessage.
To send a text and HTML combination, you could write:
\nfrom django.core.mail import EmailMultiAlternatives\n\nsubject, from_email, to = "hello", "from@example.com", "to@example.com"\ntext_content = "This is an important message."\nhtml_content = "<p>This is an <strong>important</strong> message.</p>"\nmsg = EmailMultiAlternatives(subject, text_content, from_email, [to])\nmsg.attach_alternative(html_content, "text/html")\nmsg.send()\nBy default, the MIME type of the body parameter in an\nEmailMessage is "text/plain". It is good\npractice to leave this alone, because it guarantees that any recipient will be\nable to read the email, regardless of their mail client. However, if you are\nconfident that your recipients can handle an alternative content type, you can\nuse the content_subtype attribute on the\nEmailMessage class to change the main content type.\nThe major type will always be "text", but you can change the\nsubtype. For example:
msg = EmailMessage(subject, html_content, from_email, [to])\nmsg.content_subtype = "html" # Main content is now text/html\nmsg.send()\nThe actual sending of an email is handled by the email backend.
\nThe email backend class has the following methods:
\nopen() instantiates a long-lived email-sending connection.
close() closes the current email-sending connection.
send_messages(email_messages) sends a list of\nEmailMessage objects. If the connection is\nnot open, this call will implicitly open the connection, and close the\nconnection afterward. If the connection is already open, it will be\nleft open after mail has been sent.
It can also be used as a context manager, which will automatically call\nopen() and close() as needed:
from django.core import mail\n\nwith mail.get_connection() as connection:\n mail.EmailMessage(\n subject1,\n body1,\n from1,\n [to1],\n connection=connection,\n ).send()\n mail.EmailMessage(\n subject2,\n body2,\n from2,\n [to2],\n connection=connection,\n ).send()\nThe get_connection() function in django.core.mail returns an\ninstance of the email backend that you can use.
By default, a call to get_connection() will return an instance of the\nemail backend specified in EMAIL_BACKEND. If you specify the\nbackend argument, an instance of that backend will be instantiated.
The fail_silently argument controls how the backend should handle errors.\nIf fail_silently is True, exceptions during the email sending process\nwill be silently ignored.
All other arguments are passed directly to the constructor of the\nemail backend.
\nDjango ships with several email sending backends. With the exception of the\nSMTP backend (which is the default), these backends are only useful during\ntesting and development. If you have special email sending requirements, you\ncan write your own email backend.
\nThis is the default backend. Email will be sent through a SMTP server.
\nThe value for each argument is retrieved from the matching setting if the\nargument is None:
host: EMAIL_HOST
port: EMAIL_PORT
username: EMAIL_HOST_USER
password: EMAIL_HOST_PASSWORD
use_tls: EMAIL_USE_TLS
use_ssl: EMAIL_USE_SSL
timeout: EMAIL_TIMEOUT
ssl_keyfile: EMAIL_SSL_KEYFILE
ssl_certfile: EMAIL_SSL_CERTFILE
The SMTP backend is the default configuration inherited by Django. If you\nwant to specify it explicitly, put the following in your settings:
\nEMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"\nIf unspecified, the default timeout will be the one provided by\nsocket.getdefaulttimeout(), which defaults to None (no timeout).
Instead of sending out real emails the console backend just writes the\nemails that would be sent to the standard output. By default, the console\nbackend writes to stdout. You can use a different stream-like object by\nproviding the stream keyword argument when constructing the connection.
To specify this backend, put the following in your settings:
\nEMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"\nThis backend is not intended for use in production – it is provided as a\nconvenience that can be used during development.
\nThe file backend writes emails to a file. A new file is created for each new\nsession that is opened on this backend. The directory to which the files are\nwritten is either taken from the EMAIL_FILE_PATH setting or from\nthe file_path keyword when creating a connection with\nget_connection().
To specify this backend, put the following in your settings:
\nEMAIL_BACKEND = "django.core.mail.backends.filebased.EmailBackend"\nEMAIL_FILE_PATH = "/tmp/app-messages" # change this to a proper location\nThis backend is not intended for use in production – it is provided as a\nconvenience that can be used during development.
\nThe 'locmem' backend stores messages in a special attribute of the\ndjango.core.mail module. The outbox attribute is created when the\nfirst message is sent. It’s a list with an\nEmailMessage instance for each message that would\nbe sent.
To specify this backend, put the following in your settings:
\nEMAIL_BACKEND = "django.core.mail.backends.locmem.EmailBackend"\nThis backend is not intended for use in production – it is provided as a\nconvenience that can be used during development and testing.
\nDjango’s test runner automatically uses this backend for testing.
\nAs the name suggests the dummy backend does nothing with your messages. To\nspecify this backend, put the following in your settings:
\nEMAIL_BACKEND = "django.core.mail.backends.dummy.EmailBackend"\nThis backend is not intended for use in production – it is provided as a\nconvenience that can be used during development.
\nIf you need to change how emails are sent you can write your own email\nbackend. The EMAIL_BACKEND setting in your settings file is then\nthe Python import path for your backend class.
Custom email backends should subclass BaseEmailBackend that is located in\nthe django.core.mail.backends.base module. A custom email backend must\nimplement the send_messages(email_messages) method. This method receives a\nlist of EmailMessage instances and returns the\nnumber of successfully delivered messages. If your backend has any concept of\na persistent session or connection, you should also implement the open()\nand close() methods. Refer to smtp.EmailBackend for a reference\nimplementation.
Establishing and closing an SMTP connection (or any other network connection,\nfor that matter) is an expensive process. If you have a lot of emails to send,\nit makes sense to reuse an SMTP connection, rather than creating and\ndestroying a connection every time you want to send an email.
\nThere are two ways you tell an email backend to reuse a connection.
\nFirstly, you can use the send_messages() method. send_messages() takes\na list of EmailMessage instances (or subclasses),\nand sends them all using a single connection.
For example, if you have a function called get_notification_email() that\nreturns a list of EmailMessage objects representing\nsome periodic email you wish to send out, you could send these emails using\na single call to send_messages:
from django.core import mail\n\nconnection = mail.get_connection() # Use default email connection\nmessages = get_notification_email()\nconnection.send_messages(messages)\nIn this example, the call to send_messages() opens a connection on the\nbackend, sends the list of messages, and then closes the connection again.
The second approach is to use the open() and close() methods on the\nemail backend to manually control the connection. send_messages() will not\nmanually open or close the connection if it is already open, so if you\nmanually open the connection, you can control when it is closed. For example:
from django.core import mail\n\nconnection = mail.get_connection()\n\n# Manually open the connection\nconnection.open()\n\n# Construct an email message that uses the connection\nemail1 = mail.EmailMessage(\n "Hello",\n "Body goes here",\n "from@example.com",\n ["to1@example.com"],\n connection=connection,\n)\nemail1.send() # Send the email\n\n# Construct two more messages\nemail2 = mail.EmailMessage(\n "Hello",\n "Body goes here",\n "from@example.com",\n ["to2@example.com"],\n)\nemail3 = mail.EmailMessage(\n "Hello",\n "Body goes here",\n "from@example.com",\n ["to3@example.com"],\n)\n\n# Send the two emails in a single call -\nconnection.send_messages([email2, email3])\n# The connection was already open so send_messages() doesn't close it.\n# We need to manually close the connection.\nconnection.close()\nThere are times when you do not want Django to send emails at\nall. For example, while developing a website, you probably don’t want\nto send out thousands of emails – but you may want to validate that\nemails will be sent to the right people under the right conditions,\nand that those emails will contain the correct content.
\nThe easiest way to configure email for local development is to use the\nconsole email backend. This backend\nredirects all email to stdout, allowing you to inspect the content of mail.
The file email backend can also be useful\nduring development – this backend dumps the contents of every SMTP connection\nto a file that can be inspected at your leisure.
\nAnother approach is to use a «dumb» SMTP server that receives the emails\nlocally and displays them to the terminal, but does not actually send\nanything. The aiosmtpd package provides a way to accomplish this:
\npython -m pip install aiosmtpd\n\npython -m aiosmtpd -n -l localhost:8025\nThis command will start a minimal SMTP server listening on port 8025 of\nlocalhost. This server prints to standard output all email headers and the\nemail body. You then only need to set the EMAIL_HOST and\nEMAIL_PORT accordingly. For a more detailed discussion of SMTP\nserver options, see the documentation of the aiosmtpd module.
For information about unit-testing the sending of emails in your application,\nsee the Email services section of the testing documentation.
\n