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.
Dalam dua baris:
\nfrom django.core.mail import send_mail\n\nsend_mail(\n 'Subject here',\n 'Here is the message.',\n 'from@example.com',\n ['to@example.com'],\n fail_silently=False,\n)\nSurat 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.
send_mail()Link to this heading#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\nmember of recipient_list will see the other recipients in the "To:"\nfield 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()Link to this heading#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)\nfail_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:
\nmessage1 = ('Subject here', 'Here is the message', 'from@example.com', ['first@example.com', 'other@example.com'])\nmessage2 = ('Another Subject', 'Here is another message', 'from@example.com', ['second@test.com'])\nsend_mass_mail((message1, message2), fail_silently=False)\nNilai kembalian akan berupa angka dari pesan terkirim berhasil.
\nsend_mass_mail() x send_mail()Link to this heading#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()Link to this heading#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.
\nJika 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()Link to this heading#django.core.mail.mail_managers() seperti mail_admins(), kecuali itu mengirim sebuah surel ke pengelola situs, seperti ditentukan dalam pengaturan MANAGERS.
Ini mengirim surel tunggal kepada john@example.com dan jane@example.com, dengan keduanya mereka muncul dalam "To:":
\nsend_mail(\n 'Subject',\n 'Message.',\n 'from@example.com',\n ['john@example.com', 'jane@example.com'],\n)\nIni mengirim sebuah pesan ke john@example.com dan jane@example.com, dengan keduanya menerima surel terpisah:
\ndatatuple = (\n ('Subject', 'Message.', 'from@example.com', ['john@example.com']),\n ('Subject', 'Message.', 'from@example.com', ['jane@example.com']),\n)\nsend_mass_mail(datatuple)\nHeader 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.
\nFungsi-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\nfrom django.http import HttpResponse, HttpResponseRedirect\n\ndef send_email(request):\n subject = request.POST.get('subject', '')\n message = request.POST.get('message', '')\n from_email = request.POST.get('from_email', '')\n if subject and message and from_email:\n try:\n send_mail(subject, message, from_email, ['admin@example.com'])\n except BadHeaderError:\n return HttpResponse('Invalid header found.')\n return HttpResponseRedirect('/contact/thanks/')\n else:\n # In reality we'd use a form class\n # to get proper validation errors.\n return HttpResponse('Make sure all fields are entered and valid.')\nEmailMessageLink to this heading#Django's send_mail() and\nsend_mass_mail() functions are actually thin\nwrappers that make use of the EmailMessage class.
Not all features of the EmailMessage class are\navailable through the send_mail() and related\nwrapper functions. If you wish to use advanced features, such as BCC'ed\nrecipients, file attachments, or multi-part email, you'll need to create\nEmailMessage instances directly.
EmailMessage is responsible for creating the email\nmessage itself. The email backend is then\nresponsible for sending the email.
For convenience, EmailMessage provides a simple\nsend() method for sending a single email. If you need to send multiple\nmessages, the email backend API provides an alternative.
EmailMessageLink to this heading#The EmailMessage class is initialized with the\nfollowing parameters (in the given order, if positional arguments are used).\nAll parameters are optional and can be set at any time prior to calling the\nsend() 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:
\nfrom django.core.mail import EmailMessage\n\nemail = EmailMessage(\n 'Hello',\n 'Body goes here',\n 'from@example.com',\n ['to1@example.com', 'to2@example.com'],\n ['bcc@example.com'],\n reply_to=['another@example.com'],\n headers={'Message-ID': 'foo'},\n)\nKelas mempunyai cara berikut:
\nsend(fail_silently=False) sends the message. If a connection was\nspecified when the email was constructed, that connection will be used.\nOtherwise, an instance of the default backend will be instantiated and\nused. If the keyword argument fail_silently is True, exceptions\nraised while sending the message will be quashed. An empty list of\nrecipients will not raise an exception.
message() constructs a django.core.mail.SafeMIMEText object (a\nsubclass of Python's email.MIMEText.MIMEText class) or a\ndjango.core.mail.SafeMIMEMultipart object holding the message to be\nsent. If you ever need to extend the\nEmailMessage class, you'll probably want to\noverride this method to put the content you want into the MIME object.
recipients() returns a list of all the recipients of the message,\nwhether they're recorded in the to, cc or bcc attributes. This\nis another method you might need to override when subclassing, because the\nSMTP server needs to be told the full list of recipients when the message\nis sent. If you add another way to specify recipients in your class, they\nneed 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:\nfilename, content and mimetype. filename is the name\nof the file attachment as it will appear in the email, content is\nthe data that will be contained inside the attachment and\nmimetype is the optional MIME type for the attachment. If you\nomit mimetype, the MIME content type will be guessed from the\nfilename of the attachment.
Sebagai contoh:
\nmessage.attach('design.png', img_data, 'image/png')\nJika 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\nfilesystem. Call it with the path of the file to attach and, optionally,\nthe MIME type to use for the attachment. If the MIME type is omitted, it\nwill be guessed from the filename. The simplest use would be:
message.attach_file('/images/weather_map.png')\nUntuk jenis-jenis MIME dimulai dengan text/, data biner ditangani dalam attach().
It can be useful to include multiple versions of the content in an email; the\nclassic example is to send both text and HTML versions of a message. With\nDjango's email library, you can do this using the EmailMultiAlternatives\nclass. This subclass of EmailMessage has an\nattach_alternative() method for including extra versions of the message\nbody in the email. All the other methods (including the class initialization)\nare inherited directly from EmailMessage.
Untuk mengirim perpaduan teks dan HTML, anda dapat menulis:
\nfrom django.core.mail import EmailMultiAlternatives\n\nsubject, from_email, to = 'hello', 'from@example.com', 'to@example.com'\ntext_content = 'This is an important message.'\nhtml_content = '<p>This is an <strong>important</strong> message.</p>'\nmsg = EmailMultiAlternatives(subject, text_content, from_email, [to])\nmsg.attach_alternative(html_content, "text/html")\nmsg.send()\nBy default, the MIME type of the body parameter in an\nEmailMessage is "text/plain". It is good\npractice to leave this alone, because it guarantees that any recipient will be\nable to read the email, regardless of their mail client. However, if you are\nconfident that your recipients can handle an alternative content type, you can\nuse the content_subtype attribute on the\nEmailMessage class to change the main content type.\nThe major type will always be "text", but you can change the\nsubtype. For example:
msg = EmailMessage(subject, html_content, from_email, [to])\nmsg.content_subtype = "html" # Main content is now text/html\nmsg.send()\nPengiriman sebenarnya dari sebuah surel ditangani oleh backend email.
\nKelas backend surel mempunyai metode-metode berikut:
\nopen() instantiates a long-lived email-sending connection.
close() menutup hubungan mengirim-surel saat ini.
send_messages(email_messages) sends a list of\nEmailMessage objects. If the connection is\nnot open, this call will implicitly open the connection, and close the\nconnection afterwards. If the connection is already open, it will be\nleft 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\n\nwith mail.get_connection() as connection:\n mail.EmailMessage(\n subject1, body1, from1, [to1],\n connection=connection,\n ).send()\n mail.EmailMessage(\n subject2, body2, from2, [to2],\n connection=connection,\n ).send()\nFungsi get_connection() dalam django.core.mail mengembalikan sebuah instance dari backend surel yang anda dapat gunakan.
By default, a call to get_connection() will return an instance of the\nemail backend specified in EMAIL_BACKEND. If you specify the\nbackend argument, an instance of that backend will be instantiated.
The fail_silently argument controls how the backend should handle errors.\nIf fail_silently is True, exceptions during the email sending process\nwill be silently ignored.
Semua argumen lain dilewatkan langsung ke pembangun dari backend surel.
\nDjango ships with several email sending backends. With the exception of the\nSMTP backend (which is the default), these backends are only useful during\ntesting and development. If you have special email sending requirements, you\ncan write your own email backend.
\nIni adalah backend awalan. Surel akan dikirim melalui peladen SMTP.
\nNilai untuk setiap argumen diambil dari pencocokan pengaturan jika argumen adalah None:
host: EMAIL_HOST
port: EMAIL_PORT
username: EMAIL_HOST_USER
password: EMAIL_HOST_PASSWORD
use_tls: EMAIL_USE_TLS
use_ssl: EMAIL_USE_SSL
timeout: EMAIL_TIMEOUT
ssl_keyfile: EMAIL_SSL_KEYFILE
ssl_certfile: EMAIL_SSL_CERTFILE
Backend SMTP adalah konfigurasi awalan diwarisi oleh Django. Jika anda ingin menentukan itu secara jelas, taruh berikut dalam pengaturan anda:
\nEMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'\nIf unspecified, the default timeout will be the one provided by\nsocket.getdefaulttimeout(), which defaults to None (no timeout).
Instead of sending out real emails the console backend just writes the\nemails that would be sent to the standard output. By default, the console\nbackend writes to stdout. You can use a different stream-like object by\nproviding the stream keyword argument when constructing the connection.
Untuk menentukan backend ini, taruh berikut dalam pengaturan anda:
\nEMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'\nBackend ini tidak diperuntukkan untuk penggunaan dalam produksi -- itu disediakan sebagai kenyamanan yang dapat digunakan selama pengembangan.
\nThe file backend writes emails to a file. A new file is created for each new\nsession that is opened on this backend. The directory to which the files are\nwritten is either taken from the EMAIL_FILE_PATH setting or from\nthe file_path keyword when creating a connection with\nget_connection().
Untuk menentukan backend ini, taruh berikut dalam pengaturan anda:
\nEMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'\nEMAIL_FILE_PATH = '/tmp/app-messages' # change this to a proper location\nBackend ini tidak diperuntukkan untuk penggunaan dalam produksi -- itu disediakan sebagai kenyamanan yang dapat digunakan selama pengembangan.
\nThe 'locmem' backend stores messages in a special attribute of the\ndjango.core.mail module. The outbox attribute is created when the\nfirst message is sent. It's a list with an\nEmailMessage instance for each message that would\nbe sent.
Untuk menentukan backend ini, taruh berikut dalam pengaturan anda:
\nEMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'\nThis backend is not intended for use in production -- it is provided as a\nconvenience that can be used during development and testing.
\nAs the name suggests the dummy backend does nothing with your messages. To\nspecify this backend, put the following in your settings:
\nEMAIL_BACKEND = 'django.core.mail.backends.dummy.EmailBackend'\nBackend ini tidak diperuntukkan untuk penggunaan dalam produksi -- itu disediakan sebagai kenyamanan yang dapat digunakan selama pengembangan.
\nIf you need to change how emails are sent you can write your own email\nbackend. The EMAIL_BACKEND setting in your settings file is then\nthe Python import path for your backend class.
Custom email backends should subclass BaseEmailBackend that is located in\nthe django.core.mail.backends.base module. A custom email backend must\nimplement the send_messages(email_messages) method. This method receives a\nlist of EmailMessage instances and returns the\nnumber of successfully delivered messages. If your backend has any concept of\na persistent session or connection, you should also implement the open()\nand close() methods. Refer to smtp.EmailBackend for a reference\nimplementation.
Establishing and closing an SMTP connection (or any other network connection,\nfor that matter) is an expensive process. If you have a lot of emails to send,\nit makes sense to reuse an SMTP connection, rather than creating and\ndestroying a connection every time you want to send an email.
\nAda dua cara memberitahu sebuah backend surel untuk menggunakan kembali sebuah hubungan.
\nFirstly, you can use the send_messages() method. send_messages() takes\na list of EmailMessage instances (or subclasses),\nand sends them all using a single connection.
For example, if you have a function called get_notification_email() that\nreturns a list of EmailMessage objects representing\nsome periodic email you wish to send out, you could send these emails using\na single call to send_messages:
from django.core import mail\nconnection = mail.get_connection() # Use default email connection\nmessages = get_notification_email()\nconnection.send_messages(messages)\nDalam 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\nemail backend to manually control the connection. send_messages() will not\nmanually open or close the connection if it is already open, so if you\nmanually open the connection, you can control when it is closed. For example:
from django.core import mail\nconnection = mail.get_connection()\n\n# Manually open the connection\nconnection.open()\n\n# Construct an email message that uses the connection\nemail1 = mail.EmailMessage(\n 'Hello',\n 'Body goes here',\n 'from@example.com',\n ['to1@example.com'],\n connection=connection,\n)\nemail1.send() # Send the email\n\n# Construct two more messages\nemail2 = mail.EmailMessage(\n 'Hello',\n 'Body goes here',\n 'from@example.com',\n ['to2@example.com'],\n)\nemail3 = mail.EmailMessage(\n 'Hello',\n 'Body goes here',\n 'from@example.com',\n ['to3@example.com'],\n)\n\n# Send the two emails in a single call -\nconnection.send_messages([email2, email3])\n# The connection was already open so send_messages() doesn't close it.\n# We need to manually close the connection.\nconnection.close()\nThere are times when you do not want Django to send emails at\nall. For example, while developing a website, you probably don't want\nto send out thousands of emails -- but you may want to validate that\nemails will be sent to the right people under the right conditions,\nand that those emails will contain the correct content.
\nThe easiest way to configure email for local development is to use the\nconsole email backend. This backend\nredirects all email to stdout, allowing you to inspect the content of mail.
\nThe file email backend can also be useful\nduring development -- this backend dumps the contents of every SMTP connection\nto a file that can be inspected at your leisure.
\nAnother approach is to use a "dumb" SMTP server that receives the emails\nlocally and displays them to the terminal, but does not actually send\nanything. Python has a built-in way to accomplish this with a single command:
\npython -m smtpd -n -c DebuggingServer localhost:1025\nThis command will start a simple SMTP server listening on port 1025 of\nlocalhost. This server simply prints to standard output all email headers and\nthe email body. You then only need to set the EMAIL_HOST and\nEMAIL_PORT accordingly. For a more detailed discussion of SMTP\nserver options, see the Python documentation for the smtpd module.
For information about unit-testing the sending of emails in your application,\nsee the Layanan surel section of the testing documentation.
\n