虽然 Python 通过 smtplib 模块提供了邮件发送的接口，但是 Django 在其基础上提供了更简化的支持。这些封装意在加快邮件发送，在开发时测试发送邮件，在不支持 SMTP 的平台上支持发送邮件。
这些代码位于 django.core.mail 模块。
使用 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="Subject here",
body=text_content,
from_email="from@example.com",
to=["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()
邮件是通过 SMTP 主机和端口发送的，由配置项 EMAIL_HOST 和 EMAIL_PORT 指定。如果配置了 EMAIL_HOST_USER 和 EMAIL_HOST_PASSWORD ，那么它们将被用来验证 SMTP 服务器。配置项 EMAIL_USE_TLS 和 EMAIL_USE_SSL 控制是否使用安全连接。
Note
通过 django.core.mail 发送的邮件的字符编码由 DEFAULT_CHARSET 设置项指定。
send_mail()¶在大多数情况里，你可以使用 django.core.mail.send_mail() 来发送邮件。
参数 subject, message, from_email 和 recipient_list 是必须的。
subject: 一个字符串。
message: 一个字符串。
from_email ：字符串。如果为 None ，Django 将使用 DEFAULT_FROM_EMAIL 设置的值。
recipient_list: 一个字符串列表，每项都是一个邮箱地址。recipient_list 中的每个成员都可以在邮件的 "收件人:" 中看到其他的收件人。
The following parameters are optional, and must be given as keyword arguments if used.
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 ，因为同时只能发送一条消息）。
Deprecated since version 6.0: Passing fail_silently and later parameters as positional arguments is
deprecated.
send_mass_mail()¶django.core.mail.send_mass_mail() 用于批量发送邮件。
datatuple 是一个元组，形式如下:
(subject, message, from_email, recipient_list)
fail_silently, auth_user, auth_password and connection have the
same functions as in send_mail(). They must be given as keyword arguments
if used.
Each separate element of datatuple results in a separate email message.
As in send_mail(), recipients in the same recipient_list will all see
the other addresses in the email messages' "To:" field.
举个例子，以下代码会向两个不同的收件人列表发送两封不同的邮件，却复用了同一条连接:
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)
返回值是成功发送的消息的数量。
Deprecated since version 6.0: Passing fail_silently and later parameters as positional arguments is
deprecated.
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.
mail_admins()¶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 。
Deprecated since version 6.0: Passing fail_silently and later parameters as positional arguments is
deprecated.
mail_managers()¶django.core.mail.mail_managers() 类似 mail_admins()，但它向 MANAGERS 指定的管理员们发送邮件。
Deprecated since version 6.0: Passing fail_silently and later parameters as positional arguments is
deprecated.
以下发送了一封邮件给 john@example.com 和 jane@example.com，他们都出现在 "收件人:":
send_mail(
"Subject",
"Message.",
"from@example.com",
["john@example.com", "jane@example.com"],
)
This sends a message to john@example.com and jane@example.com, with
them both receiving a separate email:
datatuple = (
("Subject", "Message.", "from@example.com", ["john@example.com"]),
("Subject", "Message.", "from@example.com", ["jane@example.com"]),
)
send_mass_mail(datatuple)
Header injection 是一个开发漏洞，攻击者可以利用它在邮件头插入额外信息，以控制脚本生成的邮件中的 "收件人:" 和 "发件人:" 内容。
The Django email functions outlined above all protect against header injection
by forbidding newlines in header values. If any subject, from_email or
recipient_list contains a newline (in either Unix, Windows or Mac style),
the email function (e.g. send_mail()) will raise ValueError and,
hence, will not send the email. It's your responsibility to validate all data
before passing it to the email functions.
如果邮件的 内容 的开始部分包含了邮件头信息，这些头信息只会作为邮件内容原样打印。
Here's an example view that takes a subject, message and from_email
from the request's POST data, sends that to admin@example.com and redirects
to "/contact/thanks/" when it's done:
from django.core.mail import 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 ValueError:
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.")
Older versions raised django.core.mail.BadHeaderError for some
invalid headers. This has been replaced with ValueError.
EmailMessage 类¶Django's send_mail() and send_mass_mail() functions are actually
thin wrappers that make use of the EmailMessage class.
Not all features of the EmailMessage class are available through the
send_mail() and related wrapper functions. If you wish to use advanced
features, such as BCC'ed recipients, file attachments, or multi-part email,
you'll need to create EmailMessage instances directly.
Note
This is a design feature. send_mail() and related functions were
originally the only interface Django provided. However, the list of
parameters they accepted was slowly growing over time. It made sense to
move to a more object-oriented design for email messages and retain the
original functions only for backwards compatibility.
EmailMessage is responsible for creating the email message itself. The
email backend is then responsible for sending the
email.
For convenience, EmailMessage provides a send()
method for sending a single email. If you need to send multiple messages, the
email backend API provides an alternative.
EmailMessage 对象¶The EmailMessage class is initialized with the following
parameters. All parameters are optional and can be set at any time prior
to calling the send() method.
The first four parameters can be passed as positional or keyword arguments, but must be in the given order if positional arguments are used:
subject: 邮件的主题。
body: 邮件内容，需要为纯文本格式。
from_email: 发件人地址。 fred@example.com 和 Fred <fred@example.com> 形式都是合法的。若省略，则使用 DEFAULT_FROM_EMAIL 配置的值。
to: 一个包含收件人地址的列表或元组。
The following parameters must be given as keyword arguments if used:
cc: 一个包含收件人地址的列表或元组，指定“抄送”对象。
bcc: 一个包含地址的列表或元组，指定“密送”对象。
reply_to: 一个包含收件人地址的列表或元组，指定“回复”对象。
attachments: A list of attachments to put on the message. Each can
be an instance of MIMEPart or
EmailAttachment, or a tuple with attributes
(filename, content, mimetype).
Support for EmailAttachment items of attachments was
added.
Support for MIMEPart objects in the
attachments list was added.
headers: 一个字典，包含邮件中额外的头信息。字典的关键字是头的名称，值为头的值。需要由调用者确保头名和值的正确性。对应的属性是 extra_headers 。
connection: An email backend instance.
Use this parameter if you are sending the EmailMessage via
send() and you want to use the same connection for multiple
messages. If omitted, a new connection is created when send() is
called. This parameter is ignored when using
send_messages().
Deprecated since version 6.0: Passing all except the first four parameters as positional arguments is deprecated.
例如：
from django.core.mail import EmailMessage
email = EmailMessage(
subject="Hello",
body="Body goes here",
from_email="from@example.com",
to=["to1@example.com", "to2@example.com"],
bcc=["bcc@example.com"],
reply_to=["another@example.com"],
headers={"Message-ID": "foo"},
)
这个类拥有以下方法：
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. It will return 1 if the message was sent
successfully, otherwise 0.
Constructs and returns a Python email.message.EmailMessage
object representing the message to be sent.
The keyword argument policy allows specifying the set of rules for
updating and serializing the representation of the message. It must be
an email.policy.Policy object. Defaults to
email.policy.default. In certain cases you may want to use
SMTP, SMTPUTF8 or a custom
policy. For example,
django.core.mail.backends.smtp.EmailBackend uses the
SMTP policy to ensure \r\n line endings as
required by the SMTP protocol.
If you ever need to extend Django's EmailMessage class,
you'll probably want to override this method to put the content you
want into the Python EmailMessage object.
The policy keyword argument was added and the return type was
updated to an instance of EmailMessage.
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.
Creates a new attachment and adds it to the message. There are two ways
to call attach():
You can pass it 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,
content can be a django.core.mail.EmailMessage or
Python's email.message.EmailMessage or
email.message.Message.
对于以 text/ 开头的 mimetype 类型，其内容应该是字符串。二进制数据将尝试以 UTF-8 解码，如果失败了，MIME 类型会被改为 application/octet-stream ，并不会修改数据内容。
Or for attachments requiring additional headers or parameters, you
can pass attach() a single Python
MIMEPart object. This will be attached
directly to the resulting message. For example, to attach an inline
image with a Content-ID:
import email.utils
from email.message import MIMEPart
from django.core.mail import EmailMultiAlternatives
message = EmailMultiAlternatives(...)
image_data_bytes = ... # Load image as bytes
# Create a random Content-ID, including angle brackets
cid = email.utils.make_msgid()
inline_image = email.message.MIMEPart()
inline_image.set_content(
image_data_bytes,
maintype="image",
subtype="png", # or "jpeg", etc. depending on the image type
disposition="inline",
cid=cid,
)
message.attach(inline_image)
# Refer to Content-ID in HTML without angle brackets
message.attach_alternative(f'… <img src="cid:{cid[1:-1]}"> …', "text/html")
Python's email.contentmanager.set_content() documentation
describes the supported arguments for MIMEPart.set_content().
Support for MIMEPart attachments was
added.
Deprecated since version 6.0: Support for email.mime.base.MIMEBase attachments is
deprecated. Use MIMEPart instead.
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. You can use it like this:
message.attach_file("/images/weather_map.png")
For MIME types starting with text/, binary data is handled
as in attach().
A named tuple to store attachments to an email.
The named tuple has the following indexes:
filename
content
mimetype
It can be useful to include multiple versions of the content in an email; the
classic example is to send both text and HTML versions of a message. With
Django's email library, you can do this using the
EmailMultiAlternatives class.
A subclass of EmailMessage that allows additional versions of the
message body in the email via the attach_alternative() method. This
directly inherits all methods (including the class initialization) from
EmailMessage.
A list of EmailAlternative named tuples.
This is particularly useful in tests:
self.assertEqual(len(msg.alternatives), 1)
self.assertEqual(msg.alternatives[0].content, html_content)
self.assertEqual(msg.alternatives[0].mimetype, "text/html")
Alternatives should only be added using the attach_alternative()
method, or passed to the constructor.
In older versions, alternatives was a list of regular tuples,
as opposed to EmailAlternative named tuples.
在电子邮件中附加消息正文的替代表示。
例如，要发送文本和 HTML 组合，你可以这样写：
from django.core.mail import EmailMultiAlternatives
subject = "hello"
from_email = "from@example.com"
to = "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()
Returns a boolean indicating whether the provided text is
contained in the email body and in all attached MIME type
text/* alternatives.
This can be useful when testing emails. For example:
def test_contains_email_content(self):
subject = "Hello World"
from_email = "from@example.com"
to = "to@example.com"
msg = EmailMultiAlternatives(subject, "I am content.", from_email, [to])
msg.attach_alternative("<p>I am content.</p>", "text/html")
self.assertIs(msg.body_contains("I am content"), True)
self.assertIs(msg.body_contains("<p>I am content.</p>"), False)
A named tuple to store alternative versions of email content.
The named tuple has the following indexes:
content
mimetype
By default, the MIME type of the body parameter in an EmailMessage
is "text/plain". It is good practice to leave this alone, because it
guarantees that any recipient will be able to read the email, regardless of
their mail client. However, if you are confident that your recipients can
handle an alternative content type, you can use the content_subtype
attribute on the EmailMessage class to change the main content type.
The major type will always be "text", but you can change the subtype. For
example:
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) sends a list of EmailMessage
objects. If the connection is not open, this call will implicitly open the
connection, and close the connection afterward. If the connection is already
open, it will be left open after mail has been sent.
这也可以用作内容管理器，它会在需要的时候自动调用 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()
The get_connection() function in django.core.mail returns an
instance of the email backend that you can use.
默认情况下，调用 get_connection() 会返回配置项 EMAIL_BACKEND 指定的后端。如果你传入了 backend 参数，将会返回该后端的实例。
The keyword-only 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 keyword arguments are passed directly to the constructor of the email backend.
Django 自带了几种邮件后端。除了 SMTP 后端（默认值）外，这些后端应仅在开发和测试阶段使用。如果对发送邮件有特殊的需求，你可以 编写自定义后端。
Deprecated since version 6.0: Passing fail_silently as positional argument is deprecated.
这是默认的后端。邮件将会通过 SMTP 服务器发送。
若以下某个参数值为 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
SMTP 后端是 Django 默认配置的。如果你想显示的指定，将以下内容放入你的配置中：
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
If unspecified, the default timeout will be the one provided by
socket.getdefaulttimeout(), which defaults to None (no timeout).
控制台后端仅将邮件发送至标准输出，而不是真的发送。默认情况下，控制台后端输出至 stdout。在创建连接时，你可以提供 stream 关键字参数来使用另一个类似 stream 的对象。
为了使用该后端，将以下代码加入你的配置中：
EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
该后端不是为了在生产环境使用的——出于方便的目的，让你在开发阶段使用。
The file backend writes emails to a file. A new file is created for each new
session that is opened on this backend. The directory to which the files are
written is either taken from the EMAIL_FILE_PATH setting or from the
file_path keyword when creating a connection with get_connection().
为了使用该后端，将以下代码加入你的配置中：
EMAIL_BACKEND = "django.core.mail.backends.filebased.EmailBackend"
EMAIL_FILE_PATH = "/tmp/app-messages" # change this to a proper location
该后端不是为了在生产环境使用的——出于方便的目的，让你在开发阶段使用。
The 'locmem' backend stores messages in a special attribute of the
django.core.mail module. The outbox attribute is created when the first
message is sent. It's a list with an EmailMessage instance for each
message that would be sent.
为了使用该后端，将以下代码加入你的配置中：
EMAIL_BACKEND = "django.core.mail.backends.locmem.EmailBackend"
该后端不是为了在生产环境使用的——出于方便的目的，让你在开发阶段使用。
Django 的测试器 自动为测试使用这个后端。
就像该后端的名字表示的一样，该后端对你发送的消息什么也不做。指定该后端，将以下代码加入你的配置中：
EMAIL_BACKEND = "django.core.mail.backends.dummy.EmailBackend"
该后端不是为了在生产环境使用的——出于方便的目的，让你在开发阶段使用。
There are community-maintained solutions too!
Django has a vibrant ecosystem. There are email backends highlighted on the Community Ecosystem page. The Django Packages Email grid has even more options for you!
若你需要修改邮件发送的方式，你可以编写自定义的邮件后端。后面要在 EMAIL_BACKEND 配置项中指定你的后端类的路径。
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.
创建和关闭 SMTP 连接（或其它网络连接）是一项耗时的进程。如果你有很多封邮件要发送，复用连接就显得很有意义，而不是在每次发送邮件时创建和关闭连接。
有两种方式可以让邮件后端复用连接。
首先，你可以在连接上使用 send_messages() 方法。这需要一个 EmailMessage`（或其子类）实例的列表，并使用该单一连接发送它们。因此，在单个消息上设置的任何 :class:`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)
在该例子中，调用 send_messages() 在后端创建了一条连接，发送完邮件列表后，关闭了这条连接。
第二种方式是在后端使用 open() 和 close() 手动控制连接。send_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 真的发送邮件。举个例子，在开发网站时，你可能并不期望发送成千上万封邮件——但你想要确保这些邮件将会在正确的时间，包含正确的内容，发送给正确的人。
在本地开发中配置电子邮件的最简单方法是使用 console 电子邮件后端。该后端将所有电子邮件重定向到 stdout，允许您查看邮件的内容。
文件 邮件后端在开发时也很有用——这个后端将每次 SMTP 连接的内容输出至一个文件，你可以在你闲暇时查看这个文件。
另一种方法是使用一个“哑”SMTP 服务器，它在本地接收电子邮件并将其显示到终端，但实际上并不发送任何内容。aiosmtpd 包提供了一种实现此目的的方法：
python -m pip install "aiosmtpd >= 1.4.5"
python -m aiosmtpd -n -l localhost:8025
这个命令将启动一个最小的 SMTP 服务器，监听在 localhost 的 8025 端口上。该服务器将打印所有电子邮件头和电子邮件正文到标准输出。然后，您只需要相应地设置 EMAIL_HOST 和 EMAIL_PORT。有关 SMTP 服务器选项的更详细讨论，请参阅 aiosmtpd 模块的文档。
关于发送邮件的单元测试资料，参见测试文档中 邮件服务 章节。
12月 22, 2025