簡単な例¶

次の 2 文を書くことで、

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 の 4 つの引数は必須です。

• subject: 文字列。
• message: 文字列。
• from_email: 文字列。もし None なら、 Django は DEFAULT_FROM_EMAIL 設定の値を使います。
• recipient_list: メールアドレスを表す文字列のリスト。recipient_list の各メンバーは、メールメッセージの "To:" フィールドで他の受信者を見ることができます。
• 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 となり、text/plain コンテンツタイプを持つ message と text/html コンテンツタイプを持つ html_message を合わせ持つものになります。

返り値は、送信に成功したメッセージの数です (送信されるメッセージが 1 つだけの場合もあるため、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 はメッセージの集合を表すタプルです。タプル内の各要素は、それぞれ1種類のメッセージを表すタプルであり、次の形式を持ちます。

(subject, message, from_email, recipient_list)

fail_silently、auth_user、auth_password の 3 つは、send_mail() と同じように機能します。

datatuple に含まれる各要素は、最終的には別々のメールメッセージとなります。send_mail() における挙動と同じく、recipient_list 内の受信者は、メールメッセージの "To:" フィールドに書かれている他の受信者のアドレスを見ることができます。

たとえば、次のコードは異なる 2 つのメッセージを 異なる 2 つの受信者のセットに送信します。しかし、メールサーバーへのコネクションは 1 つしか開かれません。

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 設定で定義されているサイト管理者 (admin) に対してメールを送信するためのショートカットです。

mail_admins() は件名の前に EMAIL_SUBJECT_PREFIX 設定の値を付けますが、デフォルトでは "[Django] " です。

メールの "From: " ヘッダは SERVER_EMAIL 設定の値になります。

このメソッドは利便性と読みやすさのために存在します。

html_message が指定された場合、送信されるメールは multipart/alternative となり、text/plain コンテンツタイプを持つ message と text/html コンテンツタイプを持つ html_message を合わせ持つものになります。

mail_managers()¶

mail_managers(subject, message, fail_silently=False, connection=None, html_message=None)¶

django.core.mail.mail_managers() は、mail_admins() とほぼ同じで、MANAGERS 設定で定義されているサイト管理者 (manager) にメールを送信します。

例¶

以下の例は、john@example.com と jane@example.com に1つのメールを送信します。2人とも "To:" 内に宛先が見られます。

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)

ヘッダインジェクションを防止する¶

ヘッダインジェクション は、攻撃者が 、スクリプトで生成されたメールメッセージの "To:" と "From:" をコントロールするために、メールヘッダを挿入してしまうセキュリティ上の脆弱性です。

上述した Django のメール機能は、ヘッダー値の改行を禁止することによってヘッダインジェクションを防ぎます。 subject、from_email、recipient_list のいずれかに 改行 (Unix、Windows ないし Mac のスタイル) が含まれている場合、email 関数 (例えば 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() やその他のラッパーで使用可能というわけではありません。高度な機能を使いたい場合 (例えば BCC の利用、ファイル添付やマルチパートのメールなど) 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 に電子メールをまったく送信させたくない場合もあるでしょう。たとえば、ウェブサイトの開発中に数千通のメールを送信したくはないでしょう。しかし、適切な条件で適切な人々にメールが送信され、これらのメールが正しい内容を含んでいるか検証したいことがあるかもしれません。

ローカル開発用にメールを設定する最も簡単な方法は console メールバックエンドを使うことです。このバックエンドはすべてのメールを stdout にリダイレクトし、メールの内容を検査できるようにします。

ファイル メールバックエンドも開発に役立ちます。このバックエンドは全ての SMTP コネクションをファイルにダンプし、都合の良いときに調べられるようにします。

もう 1 つのアプローチは、"dumb" SMTP サーバを使うことです。これは、メールをローカルで受け取りターミナルに表示しますが、実際には何も送信しません。 aiosmtpd パッケージで、この方法を実現できます:

python -m pip install aiosmtpd

python -m aiosmtpd -n -l localhost:8025

このコマンドは、localhostのポート8025で待ち受ける最小限のSMTPサーバを起動します。このサーバはすべてのメールヘッダとメール本文を標準出力に出力します。あとは EMAIL_HOST と EMAIL_PORT を適宜設定するだけです。SMTPサーバのオプションについてのより詳細な議論については、 aiosmtpd モジュールのドキュメントを参照してください。

アプリケーションでのメール送信のユニットテストについては、テストのドキュメントの メールサービス セクションを参照してください。