Mengirim surel

Meskipun Python membuat mengirim surel cenderung mudah melalui modul smtplib, Django menyediakan salinan ringan yang membungkusnya. Pembungkus ini disediakan untuk membuat pengiriman surel ekstra cepat, untuk membuatnya mudah mengirim surel selama pengembangan, dan untuk menyediakan dukungan untuk serambi yang tidak dapat menggunakan SMTP.

Kode tinggal dalam modul django.core.mail.

Contoh cepat

Dalam dua baris:

from django.core.mail import send_mail

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

Surat dikirim menggunakan rumah SMTP dan port ditentukan dalam pengaturan EMAIL_HOST dan EMAIL_PORT. Pengaturan EMAIL_HOST_USER dan EMAIL_HOST_PASSWORD settings, jika disetel, digunakan untuk mengotentifikasi pada peladen SMTP, dan pengaturan EMAIL_USE_TLS dan EMAIL_USE_SSL mengendalikan apakah hubungan aman digunakan.

Catatan

Kumpulan karakter dari surel dikirim dengan django.core.mail akan disetel ke nilai dari pengaturan DEFAULT_CHARSET anda.

send_mail()

send_mail(subject, message, from_email, recipient_list, fail_silently=False, auth_user=None, auth_password=None, connection=None, html_message=None)[sumber]

Cara termudah mengirim surel adalah menggunakan django.core.mail.send_mail().

Parameter subject, message, from_email dan recipient_list dibutuhkan.

  • subject: Sebuah string.
  • message: Sebuah string.
  • from_email: Sebuah string.
  • recipient_list: A list of strings, each an email address. Each member of recipient_list will see the other recipients in the "To:" field of the email message.
  • fail_silently: Sebuah boolean. Jika itu adalah False, send_mail akan memunculkan sebuah smtplib.SMTPException. Lihat dokumen smtplib untuk daftar kemungkinan pengecualian, semua yang merupakan subkelas-subkelas dari SMTPException.
  • auth_user: Pilihan nama pengguna untuk digunakan mengautentifikasi ke peladen SMTP. Jika ini tidak disediakan, Django akan menggunakan nilai dari pengaturan EMAIL_HOST_USER.
  • auth_password: Sandi pilihan digunakan untuk mengautentifikasi ke peladen SMTP. Jika ini tidak disediakan, Django akan menggunakan nilai dari pengaturan EMAIL_HOST_PASSWORD
  • connection: Backend surel pilihan digunakan untuk mengirim surat. Jika tidak ditentukan, sebuah instance dari backend awalan akan digunakan. Lihat dokumentasi pada Email backends 1 untuk rincian lebih.
  • html_message: Jika html_message disediakan, surel dihasilkan akan berupa surel multipart/alternative dengan message sebagai jenis isi text/plain dan html_message sebagai jenis isi text/html.

Nilai kembalian akan berupa angka dari pesan terkirim yang berhasil (yang dapat berupa 0 atau 1 sejak itu hanya daoat mengirim satu pesan).

send_mass_mail()

send_mass_mail(datatuple, fail_silently=False, auth_user=None, auth_password=None, connection=None)[sumber]

django.core.mail.send_mass_mail() diperuntukkan untuk menangani penyuratan elektronik masal.

datatuple adalah sebuah tuple yang setiap unsur adalah dalam bentuk ini:

(subject, message, from_email, recipient_list)

fail_silently, auth_user dan auth_password mempunyai fungsi sama seperti dalam send_mail().

Setiap unsur terpisah dari datatuple menghasilkan dalam pesan surel terpisah. Seperti dalam send_mail(), penerima dalam recipient_list sama akan semua melihat alamat-alamat lain dalam pesan surel' bidang "To:".

Sebagai contoh, kode berikut akan mengirim dua pesan berbeda pada dua kumpulan berbeda dari penerima; bagaimanapun, hanya satu hubungan ke peladen surat akan dibuka:

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)

Nilai kembalian akan berupa angka dari pesan terkirim berhasil.

send_mass_mail() x send_mail()

Perbedaan utama diantara send_mass_mail() dan send_mail() adalah bahwa send_mail() membuka sebuah hubungan ke peladen surel setiap itu dijalankan, selagi send_mass_mail() menggunakan hubungan tunggal untuk semua pesan-pesannya. Ini membuat send_mass_mail() sedikit lebih efesien.

mail_admins()

mail_admins(subject, message, fail_silently=False, connection=None, html_message=None)[sumber]

django.core.mail.mail_admins() adalah jalan pintas untuk mengirim sebuah surel pada admin situs, seperti ditentukan dalam pengaturan ADMINS.

mail_admins() mengawali subyek dengan nilai dari pengaturan EMAIL_SUBJECT_PREFIX, yaitu "[Django] " secara awalan.

Kepala "From:" dari surel akan berupa nilai dari pengaturan SERVER_EMAIL.

Metode ini ada untuk kenyamanan dan kesiapan.

Jika html_message disediakan, surel dihasilkan akan berupa surel multipart/alternative dengan message seperti jenis isi text/plain dan html_message seperti jenis isi text/html.

mail_managers()

mail_managers(subject, message, fail_silently=False, connection=None, html_message=None)[sumber]

django.core.mail.mail_managers() seperti mail_admins(), kecuali itu mengirim sebuah surel ke pengelola situs, seperti ditentukan dalam pengaturan MANAGERS.

Contoh

Ini mengirim surel tunggal kepada john@example.com dan jane@example.com, dengan keduanya mereka muncul dalam "To:":

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

Ini mengirim sebuah pesan ke john@example.com dan jane@example.com, dengan keduanya menerima surel terpisah:

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

Mencegah penyuntikan kepala

Header injection adalah memanfaatkan keamanan dimana seorang penyerang memasukkan kepala surel tambahan untuk mengendalikan "To:" dan "From:" dalam pesan-pesan surel yang tulisan-tulisan anda dibangkitkan.

Fungsi-fungsi surel Django diuraikan diatas semua dilindungi terhadap suntukan kepala dengan melarang baris baru dalam nilai kepala. Jika ada subject, from_email atau recepient_list mengandung sebuah baris baru (dalam salah satu gaya Unix, Windows, atau Mac), fungsi surel (sebagai contoh send_mail()) akan memunculkan django.core.mail.BadHeaderError (sebuah subkelas dari ValueError) dan, karenanya, tidak akan mengirim surel. Itu adalah tanggung jawab anda untuk mengesahkan semua data sebelum melewatkan itu ke fungsi-fungsi surel.

Jika sebuah message mengandung kepala-kepala pada awal dari string, kepala-kepala akan cukup dicetak sebagai bit pertama dari pesan surel.

Ini adalah sebuah contoh tampilan yang mengambil subject, message dan from_email dari data POST permintaan, mengirim itu ke admin@example.com dan mengalihkan ke "/contact/thanks/" ketika itu selesai:

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.')

Kelas 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.

Catatan

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 simple send() method for sending a single email. If you need to send multiple messages, the email backend API provides an alternative.

Obyek EmailMessage

class EmailMessage[sumber]

The EmailMessage class is initialized with the following parameters (in the given order, if positional arguments are used). All parameters are optional and can be set at any time prior to calling the send() method.

  • subject: Pokok baris dari surel.
  • body: Teks badan. Ini harus berupa pesan teks polos.
  • from_email: Alamat pengirim. Kedua bentuk fred@example.com dan Fred <fred@example.com> adalah sah. Jika dihilangkan, pengaturan DEFAULT_FROM_EMAIL digunakan.
  • to: Sebuah list atau tuple dari alamat-alamat penerima.
  • bcc: Sebuah list atau tuple dari alamat-alamat digunakan dalam kepala "Bcc" ketika mengirim surel.
  • connection: Sebuah instance backend surel. Gunakan parameter ini jika anda ingin menggunakan hubungan sama untuk banyak pesan-pesan. Jika dihilangkan, hubungan baru dibuat ketika send() dipanggil.
  • attachments: Sebuah list atau tuple dari lampiran-lampiran untuk ditaruh pada pesan. Ini dapat salah satu instance email.MIMEBase.MIMEBase`, atau ``(filename, content, mimetype) tiga kali lipat.
  • header: Sebuah dictionary dari kepala tambahan untuk menaruh pesan. Kunci-kunci adalah nama kepala, nilai-nilai adalah nilai-nilai kepala. Itu terserah pada pemanggil untuk memastikan nama=nama dan nilai-nilai dalam bentuk benar untuk pesan surel. Atribut sesuai adalah extra_headers.
  • cc: Sebuah list atau tuple dari alamat-alamat penerima digunakan dalam kepala "Cc" ketika mengirim surel.
  • reply_to: Sebuah list atau tuple dari alamat-alamat penerima dalam kepala "Reply-To" ketika mengirim surel.

Sebagai contoh:

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

Kelas mempunyai cara berikut:

  • 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.

  • message() constructs a django.core.mail.SafeMIMEText object (a subclass of Python's email.MIMEText.MIMEText class) or a django.core.mail.SafeMIMEMultipart object holding the message to be sent. If you ever need to extend the EmailMessage class, you'll probably want to override this method to put the content you want into the MIME object.

  • 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() membuat lampiran berkas baru dan menambahkan itu ke pesan. Ada dua cara memanggil attach():

    • Anda dapat melewatkan itu sebuah argumen tunggal yaitu sebuah instance email.MIMEBase.MIMEBase. Ini akan dimasukkan langsung kedalam hasil pesan.

    • Alternatively, you can pass attach() 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.

      Sebagai contoh:

      message.attach('design.png', img_data, 'image/png')

      Jika anda menentukan mimetype dari message/rfc822, itu juga akan menerima django.core.mail.EmailMessage dan email.message.Message.

      Untuk mimetype dimulai dengan text/, konteks diharapkan berupa string. Data biner akan disandikan menggunakan UTF-8, dan jka itu gagal, jenis MIME akan dirubah menjadi application/octet-stream dan data akan dilampirkan tidak berubah.

      Sebagai tambahan, lampiran-lampiran message/rfc822 tidak lama lagi berupa disandi-base64 dalam pelanggaran dari RFC 2046#section-5.2.1, yang dapat menyebabkan masalah-masalah dengan menampilkan lampiran dalam Evolution dan Thunderbird.

  • attach_file() 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. The simplest use would be:

    message.attach_file('/images/weather_map.png')

    Untuk jenis-jenis MIME dimulai dengan text/, data biner ditangani dalam attach().

Changed in Django 1.11:

Added the fallback to MIME type application/octet-stream when binary data for a text/* attachment cannot be decoded.

Mengirim pilihan lain jenis isi

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. This subclass of EmailMessage has an attach_alternative() method for including extra versions of the message body in the email. All the other methods (including the class initialization) are inherited directly from EmailMessage.

Untuk mengirim perpaduan teks dan HTML, anda dapat menulis:

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

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

Backend email

Pengiriman sebenarnya dari sebuah surel ditangani oleh backend email.

Kelas backend surel mempunyai metode-metode berikut:

  • open() instantiates a long-lived email-sending connection.
  • close() menutup hubungan mengirim-surel saat ini.
  • 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 afterwards. If the connection is already open, it will be left open after mail has been sent.

Itu dapat juga digunakan sebagai pengelola konteks, yang akan otomatis memanggil open() dan close() sesuai kebutuhan:

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

Mengambil sebuah instance dari sebuah backend surel.

Fungsi get_connection() dalam django.core.mail mengembalikan sebuah instance dari backend surel yang anda dapat gunakan.

get_connection(backend=None, fail_silently=False, *args, **kwargs)[sumber]

By default, a call to get_connection() will return an instance of the email backend specified in EMAIL_BACKEND. If you specify the backend argument, an instance of that backend will be instantiated.

The 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.

Semua argumen lain dilewatkan langsung ke pembangun dari backend surel.

Django ships with several email sending backends. With the exception of the SMTP backend (which is the default), these backends are only useful during testing and development. If you have special email sending requirements, you can write your own email backend.

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

Ini adalah backend awalan. Surel akan dikirim melalui peladen SMTP.

Nilai untuk setiap argumen diambil dari pencocokan pengaturan jika argumen adalah None:

Backend SMTP adalah konfigurasi awalan diwarisi oleh Django. Jika anda ingin menentukan itu secara jelas, taruh berikut dalam pengaturan anda:

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

Backend konsol

Instead of sending out real emails the console backend just writes the emails that would be sent to the standard output. By default, the console backend writes to stdout. You can use a different stream-like object by providing the stream keyword argument when constructing the connection.

Untuk menentukan backend ini, taruh berikut dalam pengaturan anda:

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

Backend ini tidak diperuntukkan untuk penggunaan dalam produksi -- itu disediakan sebagai kenyamanan yang dapat digunakan selama pengembangan.

Backend berkas

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

Untuk menentukan backend ini, taruh berikut dalam pengaturan anda:

EMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'
EMAIL_FILE_PATH = '/tmp/app-messages' # change this to a proper location

Backend ini tidak diperuntukkan untuk penggunaan dalam produksi -- itu disediakan sebagai kenyamanan yang dapat digunakan selama pengembangan.

In-memory backend

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.

Untuk menentukan backend ini, taruh berikut dalam pengaturan anda:

EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'

This backend is not intended for use in production -- it is provided as a convenience that can be used during development and testing.

Backend tiruan

As the name suggests the dummy backend does nothing with your messages. To specify this backend, put the following in your settings:

EMAIL_BACKEND = 'django.core.mail.backends.dummy.EmailBackend'

Backend ini tidak diperuntukkan untuk penggunaan dalam produksi -- itu disediakan sebagai kenyamanan yang dapat digunakan selama pengembangan.

Menentukan penyesuaian backend surel

If you need to change how emails are sent you can write your own email backend. The EMAIL_BACKEND setting in your settings file is then the Python import path for your backend class.

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.

Mengirim banyak surel

Establishing and closing an SMTP connection (or any other network connection, for that matter) is an expensive process. If you have a lot of emails to send, it makes sense to reuse an SMTP connection, rather than creating and destroying a connection every time you want to send an email.

Ada dua cara memberitahu sebuah backend surel untuk menggunakan kembali sebuah hubungan.

Firstly, you can use the send_messages() method. send_messages() takes a list of EmailMessage instances (or subclasses), and sends them all using a single 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)

Dalam contoh ini, panggilan pada send_messages() membuka hubungan pada backend, mengirim daftar pesan-pesan, dan kemudian menutup hubungan kembali.

The second approach is to use the open() and close() methods on the email backend to manually control the connection. send_messages() will not manually open or close the connection if it is already open, so if you manually open the connection, you can control when it is closed. For example:

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

Konfigurasi surel untuk pengembangan

There are times when you do not want Django to send emails at all. For example, while developing a website, you probably don't want to send out thousands of emails -- but you may want to validate that emails will be sent to the right people under the right conditions, and that those emails will contain the correct content.

The easiest way to configure email for local development is to use the console email backend. This backend redirects all email to stdout, allowing you to inspect the content of mail.

The file email backend can also be useful during development -- this backend dumps the contents of every SMTP connection to a file that can be inspected at your leisure.

Another approach is to use a "dumb" SMTP server that receives the emails locally and displays them to the terminal, but does not actually send anything. Python has a built-in way to accomplish this with a single command:

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

This command will start a simple SMTP server listening on port 1025 of localhost. This server simply prints to standard output all email headers and the email body. You then only need to set the EMAIL_HOST and EMAIL_PORT accordingly. For a more detailed discussion of SMTP server options, see the Python documentation for the smtpd module.

For information about unit-testing the sending of emails in your application, see the Layanan surel section of the testing documentation.

Back to Top