E メールを送信するLink to this heading#

簡単な例Link to this heading#

以下の 2 行にて:

from django.core.mail import send_mail

send_mail(
    'Subject here',
    'Here is the message.',
    'from@example.com',
    ['to@example.com'],
    fail_silently=False,
)

メールは、SMTP ホストと EMAIL_HOST と EMAIL_PORT 設定内で指定されたポートを使用して送信されます。EMAIL_HOST_USER と EMAIL_HOST_PASSWORD 設定がセットされている場合は、SMTP サーバーの認証に使われます。そして、EMAIL_USE_TLS と EMAIL_USE_SSL 設定はセキュアコネクションが使われるかどうかをコントロールします。

send_mail()Link to this heading#

send_mail(subject, message, from_email, recipient_list, fail_silently=False, auth_user=None, auth_password=None, connection=None, html_message=None)Link to this definition#

E メール送信のもっともシンプルな方法は、django.core.mail.send_mail() を使うことです。

subject、message、from_email、recipient_list の 4 つの引数は必須です。

• subject: 文字列です。

• message: 文字列です。

• from_email: 文字列です。

• recipient_list: 文字列のリストで、それぞれの E メールアドレスです。recipient_list の各メンバーは、E メールメッセージの "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: E メール送信のために使うバックエンドで、省略可能です。指定されなかった場合、デフォルトのバックエンドのインスタンスが使われます。詳しくは E メールのバックエンド を参照してください。

• html_message: html_message が指定された場合、送信される E メールは multipart/alternative となります。message は text/plain コンテンツタイプと html_message は text/html コンテンツタイプです。

戻り値は送信に成功したメッセージの数です (1 つだけメッセージを送信する場合もあるので、0 や 1 になることもあります)。

send_mass_mail()Link to this heading#

send_mass_mail(datatuple, fail_silently=False, auth_user=None, auth_password=None, connection=None)Link to this definition#

django.core.mail.send_mass_mail() は、大量の E メール送信を扱うために用意されています。

datatuple はタプルで、それぞれの要素は以下の形式で表されます:

(subject, message, from_email, recipient_list)

fail_silently、auth_user、auth_password の 3 つは、send_mail() と同じ機能です。

datatuple のそれぞれ分割された要素は、分割された E メールメッセージを作ります。send_mail() における挙動と同じく、recipient_list 内の受信者は E メールのメッセージにある "To:" フィールドの他の受信者のアドレスを見ることができます。

例えば、以下のコードは 2 つの異なるメッセージを、異なる受信者セットに送信します; しかし、メールサーバーへの接続は 1 つだけ開かれます:

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()Link to this heading#

mail_admins(subject, message, fail_silently=False, connection=None, html_message=None)Link to this definition#

django.core.mail.mail_admins() は、ADMINS 設定で定義されているサイト管理者 (admin) に対して E メールを送信するためのショートカットです。

mail_admins() prefixes the subject with the value of the EMAIL_SUBJECT_PREFIX setting, which is "[Django] " by default.

The "From:" header of the email will be the value of the SERVER_EMAIL setting.

This method exists for convenience and readability.

If html_message is provided, the resulting email will be a multipart/alternative email with message as the text/plain content type and html_message as the text/html content type.

mail_managers()Link to this heading#

mail_managers(subject, message, fail_silently=False, connection=None, html_message=None)Link to this definition#

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

例Link to this heading#

以下の例は、john@example.com と jane@example.com に単一の E メールを送信します。両方とも "To:" 内で見られます:

send_mail(
    'Subject',
    'Message.',
    'from@example.com',
    ['john@example.com', 'jane@example.com'],
)

以下の例は、john@example.com と jane@example.com に E メールを送信しますが、受信者はどちらも別々の E メールを受け取ります:

datatuple = (
    ('Subject', 'Message.', 'from@example.com', ['john@example.com']),
    ('Subject', 'Message.', 'from@example.com', ['jane@example.com']),
)
send_mass_mail(datatuple)

ヘッダインジェクションを防止するLink to this heading#

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

上述した Django の E メール機能は、ヘッダー値の改行を禁止することによってヘッダインジェクションを防ぎます。 subject、from_email、recipient_list のいずれかに 改行 (Unix、Windows ないし Mac のスタイル) が含まれている場合、email 関数 (例えば send_mail()) は django.core.mail.BadHeaderError (ValueError のサブクラス) 投げます。そして、それゆえに、E メールを送信しません。E メール関数にデータを渡す前に内容を検証しておくことは、開発者の責任となります。

message が文字列の最初にヘッダを含む場合、ヘッダは単に E メールメッセージの最初のビットとして表示されます。

以下は、リクエストの POST データから subject、message、from_email を取得し、それを admin@example.com に送信し、完了したら "/contact/thanks/" にリダイレクトする一例です:

from django.core.mail import send_mail, BadHeaderError
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 クラスLink to this heading#

Django の send_mail() と send_mass_mail() 関数は EmailMessage クラスを実際に使うための小さなラッパーです。

EmailMessage クラスの機能のすべてが send_mail() やその他のラッパーで使用可能というわけではありません。高度な機能を使いたい場合 (例えば BCC の利用、ファイル添付やマルチパートの E メールなど) EmailMessage のインスタンスを直接作成する必要があります。

EmailMessage は、 Eメールメッセージ自体を作成する義務があります。それから、E メールのバックエンド は、E メールを送信する義務があります。

For convenience, EmailMessage provides a simple send() method for sending a single email. If you need to send multiple messages, the email backend API provides an alternative.

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'},
)

from django.core.mail import EmailMultiAlternatives

subject, from_email, to = 'hello', 'from@example.com', '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()

msg = EmailMessage(subject, html_content, from_email, [to])
msg.content_subtype = "html"  # Main content is now text/html
msg.send()

E メールのバックエンドLink to this heading#

実際の E メール送信は、Eメールバックエンドによって処理されます。

E メールバックエンドのクラスには以下のメソッドがあります:

• open() は、長寿命の E メール送信の接続をインスタンス化します。

• close() は、現在の E メール送信の接続を閉じます。

• 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()

開発用に E メールを設定するLink to this heading#

Django に電子メールをまったく送信させたくない場合もあります。たとえば、ウェブサイトを開発しているときには、多くのメール送信などしたくないでしょう -- しかし、適切な条件で適切な人々にメールが送信され、これらの E メールが正しい内容を含むことを検証したいはずです。

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

ファイル E メールバックエンドも開発に役立ちます -- このバックエンドは全ての SMTP 接続をファイルにダンプし、都合の良いときに調べることができるようにします。

もう 1 つのアプローチは、"dumb" SMTP サーバを使うことです。これは、E メールをローカルで受け取りターミナルに表示しますが、実際には何も送信しません。Python には、単一のコマンドでこれを実行するビルトインの方法があります:

python -m smtpd -n -c DebuggingServer localhost:1025

このコマンドは、localhost の ポート 1025 でリッスンするシンプルな SMTP サーバを開始します。このサーバは、単にすべての E メールヘッダーと E メール本文を標準出力に出力します。 EMAIL_HOST と EMAIL_PORT をそれに応じて設定するだけで済みます。 SMTP サーバのオプションの詳細については、smtpd モジュールの Python ドキュメントを参照してください。

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