Django2.0手册:Sending email

send_mass_mail() vs. send_mail()¶

The main difference between send_mass_mail() and
send_mail() is that
send_mail() opens a connection to the mail server
each time it’s executed, while send_mass_mail() uses
a single connection for all of its messages. This makes
send_mass_mail() slightly more efficient.

EmailMessage Objects¶

class EmailMessage[source]¶

The EmailMessage 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
send() 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
  Fred <fred@example.com> forms are legal. If omitted, the
  DEFAULT_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
  sending the email.
• connection: 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 send() is called.
• attachments: A list of attachments to put on the message. These can
  be either MIMEBase instances, or (filename,
content, mimetype) triples.
• headers: 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 extra_headers.
• cc: A list or tuple of recipient addresses used in the “Cc” header
  when sending the email.
• reply_to: A list or tuple of recipient addresses used in the “Reply-To”
  header when sending the email.

例如:

from django.core.mail import EmailMessage

email = EmailMessage(
    'Hello',
    'Body goes here',
    'from@example.com',
    ['to1@example.com', 'to2@example.com'],
    ['bcc@example.com'],
    reply_to=['another@example.com'],
    headers={'Message-ID': 'foo'},
)

The class has the following methods:

• send(fail_silently=False) 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 fail_silently is True, exceptions
  raised while sending the message will be quashed. An empty list of
  recipients will not raise an exception.

• message() constructs a django.core.mail.SafeMIMEText object (a
  subclass of Python’s MIMEText class) or a
  django.core.mail.SafeMIMEMultipart object holding the message to be
  sent. If you ever need to extend the
  EmailMessage class, you’ll probably want to
  override this method to put the content you want into the MIME object.

• recipients() returns a list of all the recipients of the message,
  whether they’re recorded in the to, cc or bcc 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.

• attach() creates a new file attachment and adds it to the message.
  There are two ways to call attach():

  • You can pass it a single argument that is a
    MIMEBase instance. This will be inserted directly
    into the resulting message.

  • Alternatively, you can pass attach() three arguments:
    filename, content and mimetype. filename is the name
    of the file attachment as it will appear in the email, content is
    the data that will be contained inside the attachment and
    mimetype is the optional MIME type for the attachment. If you
    omit mimetype, the MIME content type will be guessed from the
    filename of the attachment.

    例如:

    message.attach('design.png', img_data, 'image/png')
    

    If you specify a mimetype of message/rfc822, it will also accept
    django.core.mail.EmailMessage and email.message.Message.

    For a mimetype starting with text/, content is expected to be a
    string. Binary data will be decoded using UTF-8, and if that fails, the
    MIME type will be changed to application/octet-stream and the data will
    be attached unchanged.

    In addition, message/rfc822 attachments will no longer be
    base64-encoded in violation of RFC 2046#section-5.2.1, which can cause
    issues with displaying the attachments in Evolution and Thunderbird.

• attach_file() 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:

  message.attach_file('/images/weather_map.png')
  

  For MIME types starting with text/, binary data is handled as in
  attach().

from django.core.mail import EmailMultiAlternatives

subject, from_email, to = 'hello', 'from@example.com', 'to@example.com'
text_content = 'This is an important message.'
html_content = '<p>This is an <strong>important</strong> message.</p>'
msg = EmailMultiAlternatives(subject, text_content, from_email, [to])
msg.attach_alternative(html_content, "text/html")
msg.send()

msg = EmailMessage(subject, html_content, from_email, [to])
msg.content_subtype = "html"  # Main content is now text/html
msg.send()

Obtaining an instance of an email backend¶

The get_connection() function in django.core.mail returns an
instance of the email backend that you can use.

get_connection(backend=None, fail_silently=False, *args, **kwargs)[source]¶

By default, a call to get_connection() will return an instance of the
email backend specified in EMAIL_BACKEND. If you specify the
backend argument, an instance of that backend will be instantiated.

The fail_silently argument controls how the backend should handle errors.
If fail_silently is True, exceptions during the email sending process
will be silently ignored.

All other arguments are passed directly to the constructor of the
email backend.

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 write your own email backend.

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

EMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'
EMAIL_FILE_PATH = '/tmp/app-messages' # change this to a proper location

EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'

EMAIL_BACKEND = 'django.core.mail.backends.dummy.EmailBackend'

Defining a custom email backend¶

If you need to change how emails are sent you can write your own email
backend. The EMAIL_BACKEND setting in your settings file is then
the Python import path for your backend class.

Custom email backends should subclass BaseEmailBackend that is located in
the django.core.mail.backends.base module. A custom email backend must
implement the send_messages(email_messages) method. This method receives a
list of EmailMessage 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 open()
and close() methods. Refer to smtp.EmailBackend for a reference
implementation.

Sending multiple emails¶

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.

There are two ways you tell an email backend to reuse a connection.

Firstly, you can use the send_messages() method. send_messages() takes
a list of EmailMessage instances (or subclasses),
and sends them all using a single connection.

For example, if you have a function called get_notification_email() that
returns a list of EmailMessage objects representing
some periodic email you wish to send out, you could send these emails using
a single call to send_messages:

from django.core import mail
connection = mail.get_connection()   # Use default email connection
messages = get_notification_email()
connection.send_messages(messages)

In this example, the call to send_messages() opens a connection on the
backend, sends the list of messages, and then closes the connection again.

The second approach is to use the open() and close() methods on the
email backend to manually control the connection. send_messages() 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:

from django.core import mail
connection = mail.get_connection()

# Manually open the connection
connection.open()

# Construct an email message that uses the connection
email1 = mail.EmailMessage(
    'Hello',
    'Body goes here',
    'from@example.com',
    ['to1@example.com'],
    connection=connection,
)
email1.send() # Send the email

# Construct two more messages
email2 = mail.EmailMessage(
    'Hello',
    'Body goes here',
    'from@example.com',
    ['to2@example.com'],
)
email3 = mail.EmailMessage(
    'Hello',
    'Body goes here',
    'from@example.com',
    ['to3@example.com'],
)

# Send the two emails in a single call -
connection.send_messages([email2, email3])
# The connection was already open so send_messages() doesn't close it.
# We need to manually close the connection.
connection.close()