快速範例¶

使用 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)[原始碼]¶

在大多數情況下，您可以使用 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] "。

電子郵件的「From:」標頭將會是 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，他們都會出現在「To:」中。

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)

防止標頭注入¶

標頭注入 是一種安全漏洞，攻擊者會插入額外的電子郵件標頭，以控制您的腳本產生的電子郵件訊息中的「To:」和「From:」。

上述的 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 伺服器，監聽 localhost 的 8025 連接埠。此伺服器會將所有電子郵件標頭和電子郵件內容列印到標準輸出。您只需相應地設定 EMAIL_HOST 和 EMAIL_PORT 即可。如需更詳細的 SMTP 伺服器選項討論，請參閱 aiosmtpd 模組的文件。

有關在您的應用程式中進行電子郵件發送單元測試的資訊，請參閱測試文件的 電子郵件服務 章節。