Although Python provides a mail sending interface via the smtplib\nmodule, Django provides a couple of light wrappers over it. These wrappers are\nprovided to make sending email extra quick, to help test email sending during\ndevelopment, and to provide support for platforms that can't use 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#Dalam kebanyakan kasus, anda dapat mengirim surel 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: Sebuah daftar dari string, setiap alamat surel. Setiap anggota dari recipient_list akan melihat penerima lain dalam bidang "To:" dari pesan surel.
fail_silently: A boolean. When it's False, send_mail() will raise\nan smtplib.SMTPException if an error occurs. See the smtplib\ndocs for a list of possible exceptions, all of which are subclasses of\nSMTPException.
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.
If a message contains headers at the start of the string, the headers will\nbe printed as the first bit of the email message.
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 BadHeaderError, send_mail\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#Fungsi-fungsi send_mail() dan send_mass_mail() sebenarnya pembungkus kecil yang memanfaatkan dari kelas EmailMessage.
Tidak semua fitur dari kelas EmailMessage tersedia melalui send_mail() dan fungsi-fungsi pembungkus terkait. Jika anda menginginkan menggunakan fitur-fitur lanjutan, seperti penerima BCC, lampiran berkas, atau banyak-bagian surel, anda akan butuh membuat instance EmailMessage langsung.
EmailMessage bertanggungjawab untuk membuat pesan surel itu sendiri. email backend 1 kemudian bertanggungjawab untuk mengirim surel.
For convenience, EmailMessage provides a send()\nmethod for sending a single email. If you need to send multiple messages, the\nemail backend API provides an alternative.
EmailMessageLink to this heading#Kelas EmailMessage diawalkan dengan parameter-parameter berikut (dalam urutan diberikan, jika penempatan argumen-argumen digunakan). Semua parameter adalah pilihan dan dapat disetel pada waktu kapanpun sebelum memanggil metode send().
subject: Pokok baris dari surel.
body: Teks badan. Ini harus berupa pesan teks polos.
from_email: The sender's address. Both fred@example.com and\n"Fred" <fred@example.com> forms are legal. If omitted, the\nDEFAULT_FROM_EMAIL setting is used.
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: A list of attachments to put on the message. These can\nbe either MIMEBase instances, or (filename,\ncontent, mimetype) triples.
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) mengirim pesan. Jika hubungan telah ditentukan ketika surel dibangun, hubungan itu akan digunakan. Sebalinya, sebuah instance dari backend awalan akan diinstasiasikan dan digunakan. Jika argumen kata kunci fail_silently adalah True, pengecualian dimunculkan ketika mengirim pesan akan dibatalkan. Sebuah daftar kosong dari penerima tidak akan memunculkan sebuah pengecualian.
message() constructs a django.core.mail.SafeMIMEText object (a\nsubclass of Python's 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() mengembalikan daftar dari semua penerima dari pesan, apakah mereka adalah terekam dalam atribut to, cc atau bcc. Ini adalah metode lain anda mungkin butuh untuk menimpa ketika mensubkelaskan, karena peladen SMTP butuh diberitahu daftar penuh dari penerima ketika pesan dikirim. Jika anda menambah cara lain untuk menentukan penerima dalam kelas anda, mereka butuh dikembalikan dari metode ini juga.
attach() membuat lampiran berkas baru dan menambahkan itu ke pesan. Ada dua cara memanggil attach():
You can pass it a single argument that is a\nMIMEBase instance. This will be inserted directly\ninto the resulting message.
Kalau tidak, anda dapat melewatkan tiga argumen attach(): filename, content dan mimetype. filename adalah nama dari lampiran berkas ketika itu muncul dalam surel, content adalah data yang akan di isi didalam lampiran dan mimetype adalah jenis MIME untuk lampiran. Jika anda menghilangkan mimetype, jenis isi MIME akan ditebak dari nama berkas dari lampiran.
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. You can use it like this:
message.attach_file('/images/weather_map.png')\nUntuk jenis-jenis MIME dimulai dengan text/, data biner ditangani dalam attach().
Itu dapat sangat berguna untuk menyertakan banyak versi dari isi dalam sebuah surel; contoh klasik adalah mengirimkan kedua versi teks dan HTML dari pesan. Dengan pustaka surel Django, anda dapat melakukan ini menggunakan kelas EmailMultiAlternatives. Subkelas ini dari EmailMessage mempunyai sebuah metode attach_alternative() untuk meneyrtakan versi tambahan dari badan pesan dalam surel. Semua metode lainnya (termasuk pengawalan kelas) diwariskan langsung dari 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()\nSecara awalan, jenis MIME dari parameter body dalam sebuah EmailMessage adalah "text/plain". Itu adalah praktik bagus untuk meninggalkan ini sendiri, karena itu menjamin penerima manapun akan dapat membaca surel, tidak peduli dari surat klien mereka. Bagaimanapun, jika anda sedang percaya diri bahwa penerima anda dapat menangani sebuah jenis isi lain, anda dapat menggunakan atribut content_subtype pada kelas EmailMessage untuk merubah jenis isi utama. Jenis utama akan selalu "text", tetapi anda dapat merubah subjenis. Sebagai contoh:
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) mengirim daftar dari obyek EmailMessage. Jika hubungan tidak terbuka, panggilan ini tidak langsung membuka hubungan, dan menutup hubungan setelah itu. Jika hubungan sudah terbuka, itu akan dibiarkan terbuka setelah surat dikirim.
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.
Secara awalan, sebuah panggilan pada get_connection() akan mengembalikan sebuah instance dari backend surel ditentukan dalam EMAIL_BACKEND. Jika anda menentukan argumen backend, sebuah instance dari backend itu akan diinstasiasikan.
Argumen fail_silently mengendalikan bagaimana backend harus menangani kesalahan. Jika fail_silently adalah True, pengecualian selama pengolahan mengirim surel akan secara diam diabaikan.
Semua argumen lain dilewatkan langsung ke pembangun dari backend surel.
\nDjango dikirim dengan beberapa backend pengiriman surel. Dengan pengecualian dari backend SMTP (yaitu awalan), backend ini hanya berguna selama percobaan dan pengembangan. Jika anda mempunyai persyaratan mengirim surel khusus, anda dapat 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'\nJika tidak ditentukan, timeout awalan akan berupa satu disediakan oleh socket.getdefaulttimeout(), yang awalan pada None (tidak ada waktu habis).
Daripada mengirim keluar surel asli backend konsol hanya menulis surel yang akan dikirim ke keluaran standar. Secara awalan, backend konsol menulis ke stdout. Anda dapat menggunakan obyek aliran-seperti berbeda dengan menyediakan argumen katakunci stream ketika membangun hubungan.
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.
\nBackend berkas menulis surel pada sebuah berkas. Sebuah berkas baru dibuat untuk setiap sesi baru yang terbuka pada backend ini. Direktori dimana berkas-berkas ditulis adalah baik diambil dari pengaturan EMAIL_FILE_PATH atau dari katakunci file_path ketika membuat sebuah hubungan dengan get_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.
\nBackend 'locmem' menyimpan pesan-pesan dalam atribut khusus dari modul django.core.mail. Atribut outbox dibuat ketika pesan pertama dikirim. Itu adalah daftar dalam sebuah instance EmailMessage untuk setiap pesan yang akan dikirim.
Untuk menentukan backend ini, taruh berikut dalam pengaturan anda:
\nEMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'\nBackend ini tidak dimaksudkan untuk digunakan dalam produksi -- itu disediakan sebagai kenyamanan yang dapat digunakan selama pengembangan dan percobaan.
\nDjango's test runner automatically uses this backend for testing.
\nKetika nama menganjurkan backend tiruan tidak melakukan apapun dengan pesan-pesan anda. Untuk menentukan backend ini, taruh berikut dalam pengaturan anda:
\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.
\nJika anda butuh merubah bagaimana surel dikirim anda dapat menulis backend surel anda sendiri. Pengaturan EMAIL_BACKEND dalam berkas pengaturan anda adalah kemudian Pythn mengimpor jalur untuk kelas backend anda.
Backend surel penyesuaian harus subkelas BaseEmailBackend yaitu bertempat dalam modul django.core.mail.backends.base. Sebuah backend surel penyesuaian harus menerapkan metode send_messages(email_messages). Metode ini menerima daftar dari instance EmailMessage dan mengembalikan sejumlah dari pesan-pesan terkirim. Jika backend anda mempunyai konsep apapun dari sesi atau hubungan yang gigih, anda harus juga menerapkan metode open() dan close(). Mengacu pada smtp.EmailBackend untuk penerapan acuan.
Membangun dan menutup hubungan SMTP (atau hubungan jaringan lain, untuk masalah itu) adalah sebuah pengolahan yang mahal. Jika anda mempunyai banyak surel untuk dikirim, itu masuk akal menggunakan kembali hubungan SMTP, daripada membuat dan manghancurkan hubungan setiap kali anda ingin mengirim surel.
\nAda dua cara memberitahu sebuah backend surel untuk menggunakan kembali sebuah hubungan.
\nPertama-tama, anda dapat menggunakan metode send_messages(). send_messages() mengambil daftar dari instance EmailMessage (atau subkelas), dan mengirim mereka semua menggunakan hubungan tunggal.
Sebagai contoh, jika anda mempunyai sebuah fungsi dipanggil get_notification_email() yang mengembalikan daftar dari obyek EmailMessage mewakili beberapa surel berkala anda ingin kirimkan, anda dapat mengirim surel ini menggunakan panggilan tunggal untuk 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.
Pendekatan kedua adalah menggunakan metode open() dan close() pada backend surel untuk secara manual mengendalikan hubungan. send_messages() tidak akan secara manual membuka atau menutup hubungan jika itu sudah terbuka, jadi jika anda membuka secara munual hubungan, anda dapat mengendalikan ketika itu tertutup. Sebagai contoh:
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()\nAda saatnya ketika anda tidak ingn Django mengirim surel sama sekali. Sebagai contoh, selagi mengembangkan sebuah situs jaringan, anda mungkin tidak ingin mengirim ribuan surel -- tetapi anda mungkin ingin mensahkan surel akan dikirim ke orang benar dibawah suasana yang benar, dan surel itu akan mengandung isi benar.
\nCara terbaik untuk mengkonfigurasi surel untuk pengembangan lokal adalah menggunakan console backend surel. Backend ini mengalihkan semua surel ke stdout, mengizinkan anda memeriksa isi dari surel.
\nBackend surel file dapat berguna selama pengembangan -- backend ini membuang isi dari setiap hubungan SMTP ke sebuah berkas yang dapat diperiksa pada waktu luang anda.
\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 minimal SMTP server listening on port 1025 of\nlocalhost. This server prints to standard output all email headers and the\nemail 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