快速示例¶

对于简单的邮件发送，请使用 send_mail()。例如，要发送纯文本消息

from django.core.mail import send_mail

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

当需要额外的邮件发送功能时，请使用 EmailMessage 或 EmailMultiAlternatives。例如，要发送包含 HTML 和纯文本版本的邮件，并使用特定的模板和自定义头，可以使用以下方法

from django.core.mail import EmailMultiAlternatives
from django.template.loader import render_to_string

# First, render the plain text content.
text_content = render_to_string(
    "templates/emails/my_email.txt",
    context={"my_variable": 42},
)

# Secondly, render the HTML content.
html_content = render_to_string(
    "templates/emails/my_email.html",
    context={"my_variable": 42},
)

# Then, create a multipart email instance.
msg = EmailMultiAlternatives(
    "Subject here",
    text_content,
    "from@example.com",
    ["to@example.com"],
    headers={"List-Unsubscribe": "<mailto:unsub@example.com>"},
)

# Lastly, attach the HTML content to the email instance and send.
msg.attach_alternative(html_content, "text/html")
msg.send()

邮件使用在 EMAIL_HOST 和 EMAIL_PORT 设置中指定的 SMTP 主机和端口发送。如果设置了 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)[source]¶

在大多数情况下，您可以使用 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)[source]¶

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)[source]¶

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)[source]¶

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)

防止邮件头注入¶

邮件头注入 是一种安全漏洞，攻击者可以通过它插入额外的邮件头，从而控制脚本生成的邮件中的“收件人”和“发件人”。

上面概述的 Django 邮件函数都通过禁止邮件头值中的换行符来防止邮件头注入。如果任何 subject、from_email 或 recipient_list 包含换行符（Unix、Windows 或 Mac 风格），则邮件函数（例如 send_mail()）将引发 django.core.mail.BadHeaderError（ValueError 的子类），因此不会发送邮件。您有责任在将数据传递给邮件函数之前验证所有数据。

如果 message 在字符串开头包含邮件头，则这些邮件头将作为邮件内容的第一部分打印出来。

这是一个示例视图，它从请求的 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.")

EmailMessage 类¶

Django 的 send_mail() 和 send_mass_mail() 函数实际上是薄包装器，它们使用 EmailMessage 类。

并非所有 EmailMessage 类的功能都可通过 send_mail() 和相关的包装函数使用。如果您希望使用高级功能，例如密件抄送收件人、文件附件或多部分邮件，则需要直接创建 EmailMessage 实例。

EmailMessage 负责创建邮件消息本身。然后，邮件后端 负责发送邮件。

为了方便起见，EmailMessage 提供了一个 send() 方法来发送单个邮件。如果您需要发送多封邮件，则 邮件后端 API 提供了替代方案。

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"},
)

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

电子邮件后端¶

电子邮件的实际发送由电子邮件后端处理。

电子邮件后端类具有以下方法

• open() 实例化一个长期存在的电子邮件发送连接。

• close() 关闭当前的电子邮件发送连接。

• send_messages(email_messages) 发送 EmailMessage 对象列表。如果连接未打开，则此调用将隐式打开连接，并在邮件发送后关闭连接。如果连接已打开，则邮件发送后将保持打开状态。

它还可以用作上下文管理器，它将根据需要自动调用 open() 和 close()

from django.core import mail

with mail.get_connection() as connection:
    mail.EmailMessage(
        subject1,
        body1,
        from1,
        [to1],
        connection=connection,
    ).send()
    mail.EmailMessage(
        subject2,
        body2,
        from2,
        [to2],
        connection=connection,
    ).send()

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"

from django.core import mail

connection = mail.get_connection()  # Use default email connection
messages = get_notification_email()
connection.send_messages(messages)

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()

配置开发环境的电子邮件¶

有时您根本不希望 Django 发送电子邮件。例如，在开发网站时，您可能不希望发送数千封电子邮件 - 但您可能希望验证电子邮件是否会在正确的条件下发送给正确的人员，以及这些电子邮件是否包含正确的内容。

配置本地开发环境的电子邮件最简单的方法是使用 控制台 电子邮件后端。此后端将所有电子邮件重定向到 stdout，允许您检查邮件内容。

在开发过程中，文件 电子邮件后端也可能很有用 - 此后端将每个 SMTP 连接的内容转储到一个文件中，您可以随时检查该文件。

另一种方法是使用一个“哑”SMTP服务器，该服务器在本地接收电子邮件并将其显示到终端，但实际上并不发送任何内容。 aiosmtpd 包提供了一种实现此目的的方法。

python -m pip install aiosmtpd

python -m aiosmtpd -n -l localhost:8025

此命令将启动一个最小的 SMTP 服务器，侦听本地主机 8025 端口。此服务器将所有电子邮件标头和电子邮件正文打印到标准输出。然后，您只需相应地设置 EMAIL_HOST 和 EMAIL_PORT 即可。有关 SMTP 服务器选项的更详细讨论，请参阅 aiosmtpd 模块的文档。

有关在应用程序中对发送电子邮件进行单元测试的信息，请参阅测试文档的 电子邮件服务 部分。