---
title: "发送邮件"
version: 6.0
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/6.0/topics/email/
canonical: https://djangodocs.dev/zh-hans/6.0/topics/email/
---
# 发送邮件

虽然 Python 通过 [`smtplib`](https://docs.python.org/3/library/smtplib.html#module-smtplib) 模块提供了邮件发送的接口，但是 Django 在其基础上提供了更简化的支持。这些封装意在加快邮件发送，在开发时测试发送邮件，在不支持 SMTP 的平台上支持发送邮件。

这些代码位于 `django.core.mail` 模块。

## 快速示例

使用 [`send_mail()`](#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`](#django.core.mail.EmailMessage) 或 [`EmailMultiAlternatives`](#django.core.mail.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`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST) 和 [`EMAIL_PORT`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_PORT) 指定。如果配置了 [`EMAIL_HOST_USER`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST_USER) 和 [`EMAIL_HOST_PASSWORD`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST_PASSWORD) ，那么它们将被用来验证  SMTP 服务器。配置项 [`EMAIL_USE_TLS`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_USE_TLS) 和 [`EMAIL_USE_SSL`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_USE_SSL) 控制是否使用安全连接。

> **Note**
>
> 通过 `django.core.mail` 发送的邮件的字符编码由 [`DEFAULT_CHARSET`](/zh-hans/6.0/ref/settings/#std-setting-DEFAULT_CHARSET) 设置项指定。

## `send_mail()`

#### `send_mail(subject, message, from_email, recipient_list, * (Keyword-only parameters separator (PEP 3102)), 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`](/zh-hans/6.0/ref/settings/#std-setting-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`](https://docs.python.org/3/library/smtplib.html#smtplib.SMTPException) 。可在 [`smtplib`](https://docs.python.org/3/library/smtplib.html#module-smtplib) 文档找到一系列可能的异常，它们都是 [`SMTPException`](https://docs.python.org/3/library/smtplib.html#smtplib.SMTPException) 的子类。
- `auth_user`: 可选的用户名，用于验证登陆 SMTP 服务器。 若未提供，Django 会使用 [`EMAIL_HOST_USER`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST_USER) 指定的值。
- `auth_password`: 可选的密码，用于验证登陆 SMTP 服务器。若未提供， Django 会使用 [`EMAIL_HOST_PASSWORD`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST_PASSWORD) 指定的值。
- `connection`: 可选参数，发送邮件使用的后端。若未指定，则使用默认的后端。查询 [邮件后端](#topic-email-backends) 文档获取更多细节。
- `html_message`: 若提供了 `html_message`，会使邮件成为 `multipart/alternative` 的实例， `message` 的内容类型则是 `text/plain` ，并且 `html_message` 的内容类型是 `text/html` 。

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

> **Deprecated since Django 6.0**
>
> Deprecated since version 6.0: Passing `fail_silently` and later parameters as positional arguments is
> deprecated.

## `send_mass_mail()`

#### `send_mass_mail(datatuple, * (Keyword-only parameters separator (PEP 3102)), 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` and `connection` have the
same functions as in [`send_mail()`](#django.core.mail.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()`](#django.core.mail.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 Django 6.0**
>
> 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()`](#django.core.mail.send_mass_mail) and [`send_mail()`](#django.core.mail.send_mail) is
that [`send_mail()`](#django.core.mail.send_mail) opens a connection to the mail server each time it's
executed, while [`send_mass_mail()`](#django.core.mail.send_mass_mail) uses a single connection for all of its
messages. This makes [`send_mass_mail()`](#django.core.mail.send_mass_mail) slightly more efficient.

## `mail_admins()`

#### `mail_admins(subject, message, * (Keyword-only parameters separator (PEP 3102)), fail_silently=False, connection=None, html_message=None)`

`django.core.mail.mail_admins()` 是定义在 [`ADMINS`](/zh-hans/6.0/ref/settings/#std-setting-ADMINS) 配置项中，用于向网站所有者快速发送邮件。

`mail_admins()` 在主题前面添加 [`EMAIL_SUBJECT_PREFIX`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_SUBJECT_PREFIX) 指定的前缀，默认是 `"[Django] "` 。

邮件头的 "发件人:" 由 [`SERVER_EMAIL`](/zh-hans/6.0/ref/settings/#std-setting-SERVER_EMAIL) 配置项指定。

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

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

> **Deprecated since Django 6.0**
>
> Deprecated since version 6.0: Passing `fail_silently` and later parameters as positional arguments is
> deprecated.

## `mail_managers()`

#### `mail_managers(subject, message, * (Keyword-only parameters separator (PEP 3102)), fail_silently=False, connection=None, html_message=None)`

`django.core.mail.mail_managers()` 类似 `mail_admins()`，但它向 [`MANAGERS`](/zh-hans/6.0/ref/settings/#std-setting-MANAGERS) 指定的管理员们发送邮件。

> **Deprecated since Django 6.0**
>
> Deprecated since version 6.0: Passing `fail_silently` and later parameters as positional arguments is
> deprecated.

## 示例

以下发送了一封邮件给 [john@example.com](mailto:john@example.com) 和 [jane@example.com](mailto: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](http://www.nyphp.org/phundamentals/8_Preventing-Email-Header-Injection.html) 是一个开发漏洞，攻击者可以利用它在邮件头插入额外信息，以控制脚本生成的邮件中的  "收件人:" 和 "发件人:" 内容。

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()`](#django.core.mail.send_mail)) will raise [`ValueError`](https://docs.python.org/3/library/exceptions.html#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.")
```

> **Changed in Django 6.0**
>
> Older versions raised `django.core.mail.BadHeaderError` for some
> invalid headers. This has been replaced with `ValueError`.

## `EmailMessage` 类

Django's [`send_mail()`](#django.core.mail.send_mail) and [`send_mass_mail()`](#django.core.mail.send_mass_mail) functions are actually
thin wrappers that make use of the [`EmailMessage`](#django.core.mail.EmailMessage) class.

Not all features of the [`EmailMessage`](#django.core.mail.EmailMessage) class are available through the
[`send_mail()`](#django.core.mail.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`](#django.core.mail.EmailMessage) instances directly.

> **Note**
>
> This is a design feature. [`send_mail()`](#django.core.mail.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`](#django.core.mail.EmailMessage) is responsible for creating the email message itself. The
[email backend](#topic-email-backends) is then responsible for sending the
email.

For convenience, [`EmailMessage`](#django.core.mail.EmailMessage) provides a [`send()`](#django.core.mail.EmailMessage.send)
method for sending a single email. If you need to send multiple messages, the
email backend API [provides an alternative](#topics-sending-multiple-emails).

### `EmailMessage` 对象

#### `class 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()`](#django.core.mail.EmailMessage.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`](/zh-hans/6.0/ref/settings/#std-setting-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`](https://docs.python.org/3/library/email.message.html#email.message.MIMEPart) or
  [`EmailAttachment`](#django.core.mail.EmailAttachment), or a tuple with attributes
  `(filename, content, mimetype)`.

  > **Changed in Django 5.2**
  >
  > Support for [`EmailAttachment`](#django.core.mail.EmailAttachment) items of `attachments` was
  > added.

  > **Changed in Django 6.0**
  >
  > Support for [`MIMEPart`](https://docs.python.org/3/library/email.message.html#email.message.MIMEPart) objects in the
  > `attachments` list was added.

  > **Deprecated since Django 6.0**
  >
  > Deprecated since version 6.0: Support for Python's legacy [`MIMEBase`](https://docs.python.org/3/library/email.mime.html#email.mime.base.MIMEBase)
  > objects in `attachments` is deprecated. Use
  > [`MIMEPart`](https://docs.python.org/3/library/email.message.html#email.message.MIMEPart) instead.
- `headers`: 一个字典，包含邮件中额外的头信息。字典的关键字是头的名称，值为头的值。需要由调用者确保头名和值的正确性。对应的属性是 `extra_headers` 。
- `connection`: An [email backend](#topic-email-backends) instance.
  Use this parameter if you are sending the `EmailMessage` via
  [`send()`](#django.core.mail.EmailMessage.send) and you want to use the same connection for multiple
  messages. If omitted, a new connection is created when [`send()`](#django.core.mail.EmailMessage.send) is
  called. This parameter is ignored when using
  [send\_messages()](#topics-sending-multiple-emails).

> **Deprecated since Django 6.0**
>
> 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"},
)
```

这个类拥有以下方法：

#### `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. It will return `1` if the message was sent
successfully, otherwise `0`.

#### `message(* (Keyword-only parameters separator (PEP 3102)), policy=email.policy.default)`

Constructs and returns a Python [`email.message.EmailMessage`](https://docs.python.org/3/library/email.message.html#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`](https://docs.python.org/3/library/email.policy.html#module-email.policy) object. Defaults to
[`email.policy.default`](https://docs.python.org/3/library/email.policy.html#email.policy.default). In certain cases you may want to use
[`SMTP`](https://docs.python.org/3/library/email.policy.html#email.policy.SMTP), [`SMTPUTF8`](https://docs.python.org/3/library/email.policy.html#email.policy.SMTPUTF8) or a custom
policy. For example,
[`django.core.mail.backends.smtp.EmailBackend`](#django.core.mail.backends.smtp.EmailBackend) uses the
[`SMTP`](https://docs.python.org/3/library/email.policy.html#email.policy.SMTP) policy to ensure `\r\n` line endings as
required by the SMTP protocol.

If you ever need to extend Django's [`EmailMessage`](#django.core.mail.EmailMessage) class,
you'll probably want to override this method to put the content you
want into the Python EmailMessage object.

> **Changed in Django 6.0**
>
> The `policy` keyword argument was added and the return type was
> updated to an instance of [`EmailMessage`](https://docs.python.org/3/library/email.message.html#email.message.EmailMessage).

#### `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(filename, content, mimetype)`

#### `attach(mimepart)`

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`](#django.core.mail.EmailMessage) or
  Python's [`email.message.EmailMessage`](https://docs.python.org/3/library/email.message.html#email.message.EmailMessage) or
  [`email.message.Message`](https://docs.python.org/3/library/email.compat32-message.html#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`](https://docs.python.org/3/library/email.message.html#email.message.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()`](https://docs.python.org/3/library/email.contentmanager.html#email.contentmanager.set_content) documentation
  describes the supported arguments for `MIMEPart.set_content()`.

  > **Changed in Django 6.0**
  >
  > Support for [`MIMEPart`](https://docs.python.org/3/library/email.message.html#email.message.MIMEPart) attachments was
  > added.

  > **Deprecated since Django 6.0**
  >
  > Deprecated since version 6.0: Support for [`email.mime.base.MIMEBase`](https://docs.python.org/3/library/email.mime.html#email.mime.base.MIMEBase) attachments is
  > deprecated. Use [`MIMEPart`](https://docs.python.org/3/library/email.message.html#email.message.MIMEPart) instead.

#### `attach_file(path, mimetype=None)`

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()`](#django.core.mail.EmailMessage.attach).

#### `class EmailAttachment`

> **New in Django 5.2**

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`](#django.core.mail.EmailMultiAlternatives) class.

#### `class EmailMultiAlternatives`

A subclass of [`EmailMessage`](#django.core.mail.EmailMessage) that allows additional versions of the
message body in the email via the [`attach_alternative()`](#django.core.mail.EmailMultiAlternatives.attach_alternative) method. This
directly inherits all methods (including the class initialization) from
[`EmailMessage`](#django.core.mail.EmailMessage).

#### `alternatives`

A list of [`EmailAlternative`](#django.core.mail.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()`](#django.core.mail.EmailMultiAlternatives.attach_alternative)
method, or passed to the constructor.

> **Changed in Django 5.2**
>
> In older versions, `alternatives` was a list of regular tuples,
> as opposed to [`EmailAlternative`](#django.core.mail.EmailAlternative) named tuples.

#### `attach_alternative(content, mimetype)`

在电子邮件中附加消息正文的替代表示。

例如，要发送文本和 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()
```

#### `body_contains(text)`

> **New in Django 5.2**

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

#### `class EmailAlternative`

> **New in Django 5.2**

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`](#django.core.mail.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`](#django.core.mail.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`](#django.core.mail.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()`](#django.core.mail.get_connection) function in `django.core.mail` returns an
instance of the email backend that you can use.

#### `get_connection(backend=None, * (Keyword-only parameters separator (PEP 3102)), fail_silently=False, **kwargs)`

默认情况下，调用 `get_connection()` 会返回配置项 [`EMAIL_BACKEND`](/zh-hans/6.0/ref/settings/#std-setting-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 后端（默认值）外，这些后端应仅在开发和测试阶段使用。如果对发送邮件有特殊的需求，你可以 [编写自定义后端](#topic-custom-email-backend)。

> **Deprecated since Django 6.0**
>
> Deprecated since version 6.0: Passing `fail_silently` as positional argument is deprecated.

#### SMTP 后端

#### `class backends.smtp.EmailBackend(host=None, port=None, username=None, password=None, use_tls=None, fail_silently=False, use_ssl=None, timeout=None, ssl_keyfile=None, ssl_certfile=None, **kwargs)`

这是默认的后端。邮件将会通过 SMTP 服务器发送。

若以下某个参数值为 `None`，则会从匹配的设置项中读取：

- `host`: [`EMAIL_HOST`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST)
- `port`: [`EMAIL_PORT`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_PORT)
- `username`: [`EMAIL_HOST_USER`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST_USER)
- `password`: [`EMAIL_HOST_PASSWORD`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST_PASSWORD)
- `use_tls`: [`EMAIL_USE_TLS`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_USE_TLS)
- `use_ssl`: [`EMAIL_USE_SSL`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_USE_SSL)
- `timeout`: [`EMAIL_TIMEOUT`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_TIMEOUT)
- `ssl_keyfile`: [`EMAIL_SSL_KEYFILE`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_SSL_KEYFILE)
- `ssl_certfile`: [`EMAIL_SSL_CERTFILE`](/zh-hans/6.0/ref/settings/#std-setting-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()`](https://docs.python.org/3/library/socket.html#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`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_FILE_PATH) setting or from the
`file_path` keyword when creating a connection with [`get_connection()`](#django.core.mail.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`](#django.core.mail.EmailMessage) instance for each
message that would be sent.

为了使用该后端，将以下代码加入你的配置中：

```
EMAIL_BACKEND = "django.core.mail.backends.locmem.EmailBackend"
```

该后端不是为了在生产环境使用的——出于方便的目的，让你在开发阶段使用。

Django 的测试器 [自动为测试使用这个后端](/zh-hans/6.0/topics/testing/tools/#topics-testing-email)。

#### 虚拟后端

就像该后端的名字表示的一样，该后端对你发送的消息什么也不做。指定该后端，将以下代码加入你的配置中：

```
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](https://www.djangoproject.com/community/ecosystem/#email-and-notifications) page. The Django Packages
> [Email grid](https://djangopackages.org/grids/g/email/) has even more options for you!

### 自定义邮件后端

若你需要修改邮件发送的方式，你可以编写自定义的邮件后端。后面要在 [`EMAIL_BACKEND`](/zh-hans/6.0/ref/settings/#std-setting-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`](#django.core.mail.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``](#django.core.mail.EmailMessage) 都会被忽略。

For example, if you have a function called `get_notification_email()` that
returns a list of [`EmailMessage`](#django.core.mail.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](#topic-email-console-backend) 电子邮件后端。该后端将所有电子邮件重定向到 `stdout`，允许您查看邮件的内容。

[文件](#topic-email-file-backend) 邮件后端在开发时也很有用——这个后端将每次 SMTP 连接的内容输出至一个文件，你可以在你闲暇时查看这个文件。

另一种方法是使用一个“哑”SMTP 服务器，它在本地接收电子邮件并将其显示到终端，但实际上并不发送任何内容。[aiosmtpd](https://pypi.org/project/aiosmtpd/) 包提供了一种实现此目的的方法：

```shell
python -m pip install "aiosmtpd >= 1.4.5"

python -m aiosmtpd -n -l localhost:8025
```

这个命令将启动一个最小的 SMTP 服务器，监听在 localhost 的 8025 端口上。该服务器将打印所有电子邮件头和电子邮件正文到标准输出。然后，您只需要相应地设置 [`EMAIL_HOST`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_HOST) 和 [`EMAIL_PORT`](/zh-hans/6.0/ref/settings/#std-setting-EMAIL_PORT)。有关 SMTP 服务器选项的更详细讨论，请参阅 [aiosmtpd](https://aiosmtpd.readthedocs.io/en/latest/) 模块的文档。

关于发送邮件的单元测试资料，参见测试文档中 [邮件服务](/zh-hans/6.0/topics/testing/tools/#topics-testing-email) 章节。