发送邮件

快速上手

仅需两行代码:

from django.core.mail import send_mail

send_mail(
    'Subject here',
    'Here is the message.',
    'from@example.com',
    ['to@example.com'],
    fail_silently=False,
)

邮件是通过 SMTP 主机和端口发送的，由配置项 EMAIL_HOST 和 EMAIL_PORT 指定。如果配置了 EMAIL_HOST_USER 和 EMAIL_HOST_PASSWORD ，那么它们将被用来验证 SMTP 服务器。配置项 EMAIL_USE_TLS 和 EMAIL_USE_SSL 控制是否使用安全连接。

send_mail()

send_mail(subject, message, from_email, recipient_list, fail_silently=False, auth_user=None, auth_password=None, connection=None, html_message=None)[源代码]

在大多数情况里，你可以使用 django.core.mail.send_mail() 来发送邮件。

参数 subject, message, from_email 和 recipient_list 是必须的。

• subject: 一个字符串。
• message: 一个字符串。
• from_email ：字符串。如果为 None ，Django 将使用 DEFAULT_FROM_EMAIL 设置的值。
• recipient_list: 一个字符串列表，每项都是一个邮箱地址。recipient_list 中的每个成员都可以在邮件的 "收件人:" 中看到其他的收件人。
• fail_silently: 一个布尔值。若为 False， send_mail() 会在发生错误时抛出 smtplib.SMTPException 。可在 smtplib 文档找到一系列可能的异常，它们都是 SMTPException 的子类。
• auth_user: 可选的用户名，用于验证登陆 SMTP 服务器。 若未提供，Django 会使用 EMAIL_HOST_USER 指定的值。
• auth_password: 可选的密码，用于验证登陆 SMTP 服务器。若未提供， Django 会使用 EMAIL_HOST_PASSWORD 指定的值。
• connection: 可选参数，发送邮件使用的后端。若未指定，则使用默认的后端。查询 邮件后端 文档获取更多细节。
• html_message: 若提供了 html_message，会使邮件成为 multipart/alternative 的实例， message 的内容类型则是 text/plain ，并且 html_message 的内容类型是 text/html 。

返回值会是成功发送的信息的数量（只能是 0 或 1 ，因为同时只能发送一条消息）。

send_mass_mail()

send_mass_mail(datatuple, fail_silently=False, auth_user=None, auth_password=None, connection=None)[源代码]

django.core.mail.send_mass_mail() 用于批量发送邮件。

datatuple 是一个元组，形式如下:

(subject, message, from_email, recipient_list)

fail_silently， auth_user 和 auth_password 拥有在 send_mail() 中一样的功能。

datatuple 参数的每个元素会生成一份独立的邮件内容。就像 send_mail() 中的一样， recipient_list 中的每个收件人会在邮件的 "收件人:" 中看到其他收件人的地址一样。

举个例子，以下代码会向两个不同的收件人列表发送两封不同的邮件，却复用了同一条连接:

message1 = ('Subject here', 'Here is the message', 'from@example.com', ['first@example.com', 'other@example.com'])
message2 = ('Another Subject', 'Here is another message', 'from@example.com', ['second@test.com'])
send_mass_mail((message1, message2), fail_silently=False)

返回值是成功发送的消息的数量。

mail_admins()

mail_admins(subject, message, fail_silently=False, connection=None, html_message=None)[源代码]

django.core.mail.mail_admins() 是定义在 ADMINS 配置项中，用于向网站所有者快速发送邮件。

mail_admins() 在主题前面添加 EMAIL_SUBJECT_PREFIX 指定的前缀，默认是 "[Django] " 。

邮件头的 "发件人:" 由 SERVER_EMAIL 配置项指定。

创建这个方法是为了方便和可读性。

若提供了 html_message，会使邮件成为 multipart/alternative 的实例， message 的内容类型则是 text/plain ，并且 html_message 的内容类型是 text/html 。

mail_managers()

mail_managers(subject, message, fail_silently=False, connection=None, html_message=None)[源代码]

django.core.mail.mail_managers() 类似 mail_admins()，但它向 MANAGERS 指定的管理员们发送邮件。

示例

以下发送了一封邮件给 john@example.com 和 jane@example.com，他们都出现在 "收件人:":

send_mail(
    'Subject',
    'Message.',
    'from@example.com',
    ['john@example.com', 'jane@example.com'],
)

以下分别发送了一封邮件给 john@example.com 和 jane@example.com，他们收到了独立的邮件:

datatuple = (
    ('Subject', 'Message.', 'from@example.com', ['john@example.com']),
    ('Subject', 'Message.', 'from@example.com', ['jane@example.com']),
)
send_mass_mail(datatuple)

防止头注入

Header injection 是一个开发漏洞，攻击者可以利用它在邮件头插入额外信息，以控制脚本生成的邮件中的 "收件人:" 和 "发件人:" 内容。

Django 的邮件函数包含了以上所有的反头注入功能，通过在头中禁止新的行。如果 subject， from_email 或 recipient_list 包含了新行（不管是 Unix，Windows 或 Mac 格式中的哪一种），邮件函数（比如 send_mail() ）都会抛出一个 django.core.mail.BadHeaderError （ ValueError 的子类），这会中断邮件发送。你需要在将参数传给邮件函数前确保数据的有效性和合法性。

如果邮件的 内容 的开始部分包含了邮件头信息，这些头信息只会作为邮件内容原样打印。

以下是一个实例视图，从请求的 POST 数据中获取 subject， message 和 from_email，并将其发送至 admin@example.com ，成功后再重定向至 "/contact/thanks/"

from django.core.mail import BadHeaderError, send_mail
from django.http import HttpResponse, HttpResponseRedirect

def send_email(request):
    subject = request.POST.get('subject', '')
    message = request.POST.get('message', '')
    from_email = request.POST.get('from_email', '')
    if subject and message and from_email:
        try:
            send_mail(subject, message, from_email, ['admin@example.com'])
        except BadHeaderError:
            return HttpResponse('Invalid header found.')
        return HttpResponseRedirect('/contact/thanks/')
    else:
        # In reality we'd use a form class
        # to get proper validation errors.
        return HttpResponse('Make sure all fields are entered and valid.')

为了开发配置邮件

曾经有很多次，你并不想 Django 真的发送邮件。举个例子，在开发网站时，你可能并不期望发送成千上万封邮件——但你想要确保这些邮件将会在正确的时间，包含正确的内容，发送给正确的人。

The easiest way to configure email for local development is to use the console email backend. This backend redirects all email to stdout, allowing you to inspect the content of mail.

文件 邮件后端在开发时也很有用——这个后端将每次 SMTP 连接的内容输出至一个文件，你可以在你闲暇时查看这个文件。

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. The aiosmtpd package provides a way to accomplish this:

python -m pip install aiosmtpd

python -m aiosmtpd -n -l localhost:8025

This command will start a minimal SMTP server listening on port 8025 of localhost. This server prints to standard output all email headers and the email body. You then only need to set the EMAIL_HOST and EMAIL_PORT accordingly. For a more detailed discussion of SMTP server options, see the documentation of the aiosmtpd module.

关于发送邮件的单元测试资料，参见测试文档中 邮件服务 章节。