快速示例¶

两行代码

from django.core.mail import send_mail

send_mail(
    "Subject here",
    "Here is the message.",
    "[email protected]",
    ["[email protected]"],
    fail_silently=False,
)

邮件使用 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)¶

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

subject、message、from_email 和 recipient_list 参数是必需的。

• subject：一个字符串。
• message：一个字符串。
• from_email：一个字符串。如果为 None，Django 将使用 DEFAULT_FROM_EMAIL 设置的值。
• 收件人列表：一个字符串列表，每个字符串都是一个电子邮件地址。 收件人列表 的每个成员都将在电子邮件消息的“收件人：”字段中看到其他收件人。
• 静默失败：一个布尔值。当它为 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",
    "[email protected]",
    ["[email protected]", "[email protected]"],
)
message2 = (
    "Another Subject",
    "Here is another message",
    "[email protected]",
    ["[email protected]"],
)
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.",
    "[email protected]",
    ["[email protected]", "[email protected]"],
)

这会向 john@example.com 和 jane@example.com 发送一封消息，他们都会收到一封单独的电子邮件

datatuple = (
    ("Subject", "Message.", "[email protected]", ["[email protected]"]),
    ("Subject", "Message.", "[email protected]", ["[email protected]"]),
)
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, ["[email protected]"])
        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",
    "[email protected]",
    ["[email protected]", "[email protected]"],
    ["[email protected]"],
    reply_to=["[email protected]"],
    headers={"Message-ID": "foo"},
)

from django.core.mail import EmailMultiAlternatives

subject, from_email, to = "hello", "[email protected]", "[email protected]"
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()

电子邮件后端¶

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

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

• 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",
    "[email protected]",
    ["[email protected]"],
    connection=connection,
)
email1.send()  # Send the email

# Construct two more messages
email2 = mail.EmailMessage(
    "Hello",
    "Body goes here",
    "[email protected]",
    ["[email protected]"],
)
email3 = mail.EmailMessage(
    "Hello",
    "Body goes here",
    "[email protected]",
    ["[email protected]"],
)

# 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

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

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