`smtplib` --- کلاینت پروتکل SMTP¶

کد منبع: Lib/smtplib.py

ماژول smtplib یک شیء نشست کلاینت SMTP را تعریف می‌کند که می‌توان از آن برای ارسال ایمیل به هر ماشین اینترنتی با دیمن شنونده SMTP یا ESMTP استفاده کرد. برای جزئیات عملکرد SMTP و ESMTP، به RFC 821 (پروتکل انتقال ساده‌ی ایمیل) و RFC 1869 (افزونه‌های سرویس SMTP) مراجعه کنید.

دسترس‌پذیری: not WASI.

این ماژول روی WebAssembly کار نمی‌کند یا در دسترس نیست. برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

class smtplib.SMTP(host='', port=0, local_hostname=None, [timeout, ]source_address=None)¶

یک نمونه از SMTP یک اتصال SMTP را در بر می‌گیرد. این کلاس متدهایی دارد که از مجموعه کاملی از عملیات SMTP و ESMTP پشتیبانی می‌کنند. اگر پارامترهای اختیاری host و port داده شوند، متد connect() SMTP در حین مقداردهی اولیه با آن پارامترها فراخوانی می‌شود. در صورت مشخص بودن، از local_hostname به‌عنوان FQDN میزبان محلی در دستور HELO/EHLO استفاده می‌شود. در غیر این صورت، نام میزبان محلی با استفاده از socket.getfqdn() یافت می‌شود. اگر فراخوانی connect() هر مقداری غیر از یک کد موفقیت برگرداند، استثنای SMTPConnectError پرتاب می‌شود. پارامتر اختیاری timeout مهلتی به ثانیه برای عملیات‌های مسدودکننده مانند تلاش برای اتصال مشخص می‌کند (اگر مشخص نشود، از تنظیم پیش‌فرض سراسری مهلت استفاده خواهد شد). اگر مهلت منقضی شود، استثنای TimeoutError پرتاب می‌شود. پارامتر اختیاری source_address امکان مقیدسازی به یک نشانی مبدأ خاص در ماشینی با چندین رابط شبکه و/یا به یک پورت TCP مبدأ خاص را فراهم می‌کند. این پارامتر یک تاپل دوتایی (host, port) را می‌گیرد تا سوکت پیش از اتصال، به‌عنوان نشانی مبدأ خود به آن مقید شود. در صورت حذف این پارامتر (یا اگر host یا port به ترتیب '' و/یا 0 باشند) از رفتار پیش‌فرض سیستم‌عامل استفاده خواهد شد.

برای استفاده‌ی عادی، تنها باید به متدهای راه‌اندازی/اتصال، sendmail() و SMTP.quit() نیاز داشته باشید. یک نمونه در زیر آمده است.

کلاس SMTP از دستور with پشتیبانی می‌کند. هنگامی که به این شکل استفاده شود، فرمان QUIT SMTP به‌طور خودکار در زمان خروج از دستور with صادر می‌شود. برای مثال:

>>> from smtplib import SMTP
>>> with SMTP("domain.org") as smtp:
...     smtp.noop()
...
(250, b'Ok')
>>>

تمام دستورات یک رویداد حسابرسی smtplib.SMTP.send را با آرگومان‌های self و data پرتاب می‌کنند، که data بایت‌هایی است که قرار است به میزبان راه دور ارسال شوند.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی از دستور with افزوده شد.

تغییر یافته در نسخه‌ی 3.3: آرگومان source_address اضافه شد.

اضافه شده در نسخه‌ی 3.5: افزونه‌ی SMTPUTF8 (RFC 6531) اکنون پشتیبانی می‌شود.

تغییر یافته در نسخه‌ی 3.9: اگر پارامتر timeout روی صفر تنظیم شود، یک ValueError پرتاب می‌شود تا از ایجاد یک سوکت غیرمسدودکننده جلوگیری شود.

class smtplib.SMTP_SSL(host='', port=0, local_hostname=None, *, [timeout, ]context=None, source_address=None)¶: یک نمونه از SMTP_SSL دقیقاً مانند نمونه‌های SMTP رفتار می‌کند. SMTP_SSL باید برای موقعیت‌هایی استفاده شود که SSL از ابتدای اتصال مورد نیاز باشد و استفاده از starttls() مناسب نباشد. اگر host مشخص نشده باشد، از میزبان محلی استفاده می‌شود. اگر port صفر باشد، از درگاه استاندارد SMTP-over-SSL (۴۶۵) استفاده می‌شود. آرگومان‌های اختیاری local_hostname، timeout و source_address همان معنایی را دارند که در کلاس SMTP دارند. context، که آن هم اختیاری است، می‌تواند شامل یک SSLContext باشد و به شما امکان می‌دهد که جنبه‌های مختلف اتصال امن را پیکربندی کنید. لطفاً برای بهترین شیوه‌ها، ملاحظات امنیتی را بخوانید.

تغییر یافته در نسخه‌ی 3.3: context اضافه شد.

تغییر یافته در نسخه‌ی 3.3: آرگومان source_address افزوده شد.

تغییر یافته در نسخه‌ی 3.4: این کلاس اکنون از بررسی نام میزبان با ssl.SSLContext.check_hostname و نشان‌دهی نام سرور (Server Name Indication) پشتیبانی می‌کند (ssl.HAS_SNI را ببینید).

تغییر یافته در نسخه‌ی 3.9: اگر پارامتر timeout برابر با صفر تنظیم شود، یک ValueError پرتاب می‌شود تا از ایجاد یک سوکت غیرمسدودکننده جلوگیری شود

تغییر یافته در نسخه‌ی 3.12: پارامترهای منسوخ keyfile و certfile حذف شده‌اند.

class smtplib.LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None[, timeout])¶

پروتکل LMTP، که بسیار شبیه به ESMTP است، تا حد زیادی مبتنی بر کلاینت SMTP استاندارد است. استفاده از سوکت‌های یونیکس برای LMTP رایج است، بنابراین متد connect() ما باید هم از آن و هم از یک سرور معمولی host:port پشتیبانی کند. آرگومان‌های اختیاری local_hostname و source_address همان معنایی را دارند که در کلاس SMTP دارند. برای مشخص کردن یک سوکت یونیکس، باید برای host از یک مسیر مطلق استفاده کنید که با '/' شروع می‌شود.

احراز هویت با استفاده از سازوکار معمول SMTP پشتیبانی می‌شود. هنگام استفاده از یک سوکت یونیکس، LMTP معمولاً از هیچ احراز هویتی پشتیبانی نمی‌کند یا به آن نیازی ندارد، اما ممکن است شرایط شما متفاوت باشد.

تغییر یافته در نسخه‌ی 3.9: پارامتر اختیاری timeout افزوده شد.

همچنین مجموعه‌ی مناسبی از استثناها تعریف شده است:

exception smtplib.SMTPException¶: زیرکلاسی از OSError که کلاس پایه‌ی استثنا برای تمام استثناهای دیگری است که توسط این ماژول ارائه می‌شوند.

تغییر یافته در نسخه‌ی 3.4: SMTPException به زیرکلاسی از OSError تبدیل شد

exception smtplib.SMTPServerDisconnected¶: این استثنا زمانی پرتاب می‌شود که سرور به‌طور غیرمنتظره‌ای قطع ارتباط کند، یا زمانی که تلاشی برای استفاده از نمونه‌ی SMTP پیش از اتصال آن به سرور صورت گیرد.

exception smtplib.SMTPResponseException¶

کلاس پایه برای همه استثناهایی که شامل یک کد خطای SMTP هستند. این استثناها در برخی موارد زمانی تولید می‌شوند که سرور SMTP یک کد خطا برمی‌گرداند.

smtp_code¶: کد خطا.

smtp_error¶: پیام خطا.

exception smtplib.SMTPSenderRefused¶: نشانی فرستنده رد شد. علاوه بر ویژگی‌هایی که روی همه‌ی استثناهای SMTPResponseException تنظیم شده‌اند، این استثنا 'sender' را برابر با رشته‌ای قرار می‌دهد که سرور SMTP آن را رد کرده است.

exception smtplib.SMTPRecipientsRefused¶

تمام نشانی‌های گیرنده رد شدند.

recipients¶: دیکشنری دقیقاً از همان نوعی که SMTP.sendmail() بازمی‌گرداند، شامل خطاهای هر گیرنده است.

exception smtplib.SMTPDataError¶: سرور SMTP از پذیرش داده‌های پیام خودداری کرد.

exception smtplib.SMTPConnectError¶: خطایی در هنگام برقراری اتصال با سرور رخ داد.

exception smtplib.SMTPHeloError¶: سرور پیام HELO ما را رد کرد.

exception smtplib.SMTPNotSupportedError¶: فرمان یا گزینه‌ی تلاش‌شده توسط سرور پشتیبانی نمی‌شود.

اضافه شده در نسخه‌ی 3.5.

exception smtplib.SMTPAuthenticationError¶: احراز هویت SMTP با مشکل مواجه شد. به احتمال زیاد سرور ترکیب نام کاربری/گذرواژه‌ی ارائه‌شده را نپذیرفت.

همچنین ملاحظه نمائید

RFC 821 - پروتکل انتقال نامه‌ی ساده (Simple Mail Transfer Protocol): تعریف پروتکل SMTP. این سند مدل، رویه عملیاتی و جزئیات پروتکل SMTP را پوشش می‌دهد.
RFC 1869 - افزونه‌های سرویس SMTP: تعریف افزونه‌های ESMTP برای SMTP. این متن چارچوبی را برای گسترش SMTP با دستورهای جدید توصیف می‌کند، از کشف پویای دستورهای ارائه‌شده توسط سرور پشتیبانی می‌کند و چند دستور اضافی را تعریف می‌کند.

اشیای SMTP¶

نمونه‌ای از SMTP دارای متدهای زیر است:

SMTP.set_debuglevel(level)¶: سطح خروجی اشکال‌زدایی را تنظیم کنید. مقدار ۱ یا True برای level منجر به پیام‌های اشکال‌زدایی برای اتصال و برای تمام پیام‌های ارسالی به سرور و دریافتی از سرور می‌شود. مقدار ۲ برای level باعث می‌شود این پیام‌ها دارای مهر زمانی شوند.

تغییر یافته در نسخه‌ی 3.5: debuglevel 2 افزوده شد.

SMTP.docmd(cmd, args='')¶

فرمان cmd را به سرور ارسال کنید. آرگومان اختیاری args به‌سادگی با یک فاصله به فرمان الحاق می‌شود.

این یک تاپل ۲تایی متشکل از یک کد پاسخ عددی و خط پاسخ واقعی را برمی‌گرداند (پاسخ‌های چندخطی به یک خط طولانی تبدیل می‌شوند).

در حالت عادی، نیازی به فراخوانی صریح این متد نیست. این متد برای پیاده‌سازی سایر متدها استفاده می‌شود و ممکن است برای آزمون افزونه‌های خصوصی مفید باشد.

اگر اتصال به سرور در حین انتظار برای پاسخ قطع شود، SMTPServerDisconnected پرتاب خواهد شد.

SMTP.connect(host='localhost', port=0)¶

به یک میزبان در یک پورت مشخص متصل می‌شود. پیش‌فرض این است که به میزبان محلی در پورت استاندارد SMTP (۲۵) متصل شود. اگر نام میزبان با یک دونقطه (':') و به دنبال آن یک عدد پایان یابد، آن پسوند حذف می‌شود و عدد به‌عنوان شماره پورتی که باید استفاده شود تفسیر می‌شود. اگر در هنگام نمونه‌سازی یک میزبان مشخص شده باشد، این متد به‌طور خودکار توسط سازنده فراخوانی می‌شود. یک تاپل ۲تایی شامل کد پاسخ و پیامی که سرور در پاسخ اتصال خود ارسال کرده است برمی‌گرداند.

یک رویداد حسابرسی smtplib.connect را با آرگومان‌های self، host، port پرتاب می‌کند.

SMTP.helo(name='')¶

با استفاده از HELO خود را به سرور SMTP معرفی کنید. آرگومان hostname به‌طور پیش‌فرض برابر با نام دامنه‌ی کامل میزبان محلی است. پیام برگردانده‌شده از سوی سرور، به‌عنوان ویژگی helo_resp شیء ذخیره می‌شود.

در عملکرد عادی، لازم نیست این متد را به‌طور صریح فراخوانی کنید. در صورت لزوم، این متد به‌طور ضمنی توسط sendmail() فراخوانی می‌شود.

SMTP.ehlo(name='')¶

با استفاده از EHLO، خود را به یک سرور ESMTP معرفی کنید. آرگومان hostname به‌طور پیش‌فرض برابر با نام دامنه‌ی کامل میزبان محلی (fully qualified domain name) است. پاسخ را از نظر گزینه‌های ESMTP بررسی کنید و آن‌ها را ذخیره کنید تا has_extn() از آن‌ها استفاده کند. همچنین چند ویژگی اطلاعاتی را تنظیم می‌کند: پیام برگردانده‌شده از سرور به‌عنوان ویژگی ehlo_resp ذخیره می‌شود، does_esmtp بسته به اینکه سرور از ESMTP پشتیبانی کند یا نه، روی True یا False تنظیم می‌شود، و esmtp_features یک دیکشنری حاوی نام افزونه‌های سرویس SMTP پشتیبانی‌شده توسط این سرور و پارامترهای آن‌ها (در صورت وجود) خواهد بود.

مگر اینکه بخواهید پیش از ارسال ایمیل از has_extn() استفاده کنید، نیازی به فراخوانی صریح این متد نیست. این متد در صورت لزوم به‌طور ضمنی توسط sendmail() فراخوانی می‌شود.

SMTP.ehlo_or_helo_if_needed()¶

این متد، ehlo() و/یا helo() را در صورتی فراخوانی می‌کند که پیش‌تر در این نشست دستور EHLO یا HELO وجود نداشته باشد. ابتدا ESMTP EHLO را امتحان می‌کند.

SMTPHeloError: سرور به‌درستی به سلام HELO پاسخ نداد.

SMTP.has_extn(name)¶: اگر name در مجموعه‌ی افزونه‌های سرویس SMTP برگردانده‌شده توسط سرور وجود داشته باشد، True و در غیر این صورت False برمی‌گرداند. بزرگی و کوچکی حروف نادیده گرفته می‌شود.

SMTP.verify(address)¶: صحت یک نشانی در این سرور را با استفاده از VRFY در SMTP بررسی می‌کند. اگر نشانی کاربر معتبر باشد، تاپلی شامل کد ۲۵۰ و یک نشانی کامل RFC 822 (شامل نام شخص) بازمی‌گرداند. در غیر این صورت، یک کد خطای SMTP با مقدار ۴۰۰ یا بیشتر و یک رشته خطا بازمی‌گرداند.

توجه

بسیاری از وب‌سایت‌ها SMTP VRFY را غیرفعال می‌کنند تا جلوی هرزنامه‌فرستندگان را بگیرند.

SMTP.login(user, password, *, initial_response_ok=True)¶

به یک سرور SMTP که نیازمند احراز هویت است، وارد شوید. آرگومان‌ها، نام کاربری و گذرواژه‌ای هستند که برای احراز هویت استفاده می‌شوند. اگر در این نشست هیچ دستور EHLO یا HELO پیشینی وجود نداشته باشد، این متد ابتدا ESMTP EHLO را امتحان می‌کند. این متد در صورت موفقیت‌آمیز بودن احراز هویت، به‌صورت عادی برمی‌گردد، یا ممکن است استثناهای زیر را پرتاب کند:

SMTPHeloError: سرور به‌درستی به سلام HELO پاسخ نداد.
SMTPAuthenticationError: سرور ترکیب نام‌کاربری/گذرواژه را نپذیرفت.
SMTPNotSupportedError: سرور از فرمان AUTH پشتیبانی نمی‌کند.
SMTPException: هیچ متد احراز هویت مناسبی یافت نشد.

هر یک از روش‌های احراز هویت پشتیبانی‌شده توسط smtplib، در صورتی که پشتیبانی از آن‌ها توسط سرور اعلام شده باشد، به‌ترتیب امتحان می‌شوند. برای مشاهده فهرستی از روش‌های احراز هویت پشتیبانی‌شده، auth() را ببینید. initial_response_ok به auth() منتقل می‌شود.

آرگومان کلیدواژه‌ای اختیاری initial_response_ok مشخص می‌کند که آیا، برای روش‌های احراز هویتی که از آن پشتیبانی می‌کنند، می‌توان یک «پاسخ اولیه» مطابق RFC 4954 را همراه با دستور AUTH ارسال کرد، به جای آنکه به چالش/پاسخ نیاز باشد.

تغییر یافته در نسخه‌ی 3.5: ممکن است SMTPNotSupportedError پرتاب شود، و پارامتر initial_response_ok افزوده شده است.

SMTP.auth(mechanism, authobject, *, initial_response_ok=True)¶

دستور SMTP AUTH را برای mechanism احراز هویت مشخص‌شده صادر کنید و پاسخ چالش را از طریق authobject مدیریت کنید.

mechanism مشخص می‌کند که کدام سازوکار احراز هویت باید به‌عنوان آرگومان فرمان AUTH استفاده شود؛ مقادیر معتبر، آن‌هایی هستند که در عنصر auth از esmtp_features فهرست شده‌اند.

authobject باید یک شیء فراخوانی‌پذیر باشد که یک آرگومان اختیاری می‌پذیرد:

data = authobject(challenge=None)

اگر آرگومان کلیدواژه‌ای اختیاری initial_response_ok درست باشد، authobject() ابتدا بدون آرگومان فراخوانی می‌شود. این تابع می‌تواند یک str ASCII «پاسخ اولیه» طبق RFC 4954 را برگرداند که کدگذاری شده و به‌صورت زیر همراه با دستور AUTH ارسال می‌شود. اگر authobject() از پاسخ اولیه پشتیبانی نمی‌کند (مثلاً به این دلیل که به یک چالش نیاز دارد)، باید هنگام فراخوانی با challenge=None مقدار None را برگرداند. اگر initial_response_ok نادرست باشد، آنگاه authobject() ابتدا با None فراخوانی نمی‌شود.

اگر بررسی پاسخ اولیه None برگرداند، یا اگر initial_response_ok نادرست باشد، authobject() فراخوانی خواهد شد تا پاسخ چالش سرور را پردازش کند؛ آرگومان challenge که به آن داده می‌شود یک bytes خواهد بود. باید data از نوع str ASCII را بازگرداند که کدگذاری base64 می‌شود و به سرور ارسال می‌شود.

کلاس SMTP، authobjects را برای سازوکارهای CRAM-MD5، PLAIN و LOGIN فراهم می‌کند؛ این موارد به‌ترتیب SMTP.auth_cram_md5، SMTP.auth_plain و SMTP.auth_login نام‌گذاری شده‌اند. همه‌ی آن‌ها نیاز دارند که ویژگی‌های user و password از نمونه‌ی SMTP روی مقادیر مناسب تنظیم شده باشند.

کد کاربر معمولاً نیازی ندارد auth را مستقیماً فراخوانی کند، بلکه می‌تواند در عوض متد login() را فراخوانی کند، که هر یک از سازوکارهای بالا را به‌نوبت و به ترتیب ذکرشده امتحان می‌کند. auth برای تسهیل پیاده‌سازی روش‌های احراز هویت که مستقیماً در smtplib پشتیبانی نمی‌شوند (یا هنوز پشتیبانی نمی‌شوند) در دسترس قرار گرفته است.

اضافه شده در نسخه‌ی 3.5.

SMTP.starttls(*, context=None)¶

اتصال SMTP را در حالت TLS (امنیت لایه‌ی انتقال) قرار دهید. تمام دستورات SMTP که در ادامه می‌آیند رمزگذاری خواهند شد. سپس باید ehlo() را دوباره فراخوانی کنید.

اگر keyfile و certfile ارائه شده باشند، از آن‌ها برای ایجاد یک ssl.SSLContext استفاده می‌شود.

پارامتر اختیاری context یک شیء ssl.SSLContext است؛ این یک جایگزین برای استفاده از keyfile و certfile است و در صورت مشخص شدن، هر دو keyfile و certfile باید None باشند.

اگر در این نشست هیچ دستور پیشین EHLO یا HELO وجود نداشته باشد، این متد ابتدا ESMTP EHLO را امتحان می‌کند.

تغییر یافته در نسخه‌ی 3.12: پارامترهای منسوخ keyfile و certfile حذف شده‌اند.

SMTPHeloError: سرور به‌درستی به سلام HELO پاسخ نداد.
SMTPNotSupportedError: سرور از افزونه STARTTLS پشتیبانی نمی‌کند.
RuntimeError: پشتیبانی از SSL/TLS در مفسر پایتون شما در دسترس نیست.

تغییر یافته در نسخه‌ی 3.3: context اضافه شد.

تغییر یافته در نسخه‌ی 3.4: این متد اکنون از بررسی نام میزبان با ssl.SSLContext.check_hostname و نشانگر نام سرور (Server Name Indicator) پشتیبانی می‌کند (نگاه کنید به HAS_SNI).

تغییر یافته در نسخه‌ی 3.5: خطایی که به دلیل فقدان پشتیبانی از STARTTLS پرتاب می‌شود، اکنون به جای کلاس پایه‌ی SMTPException، از زیرکلاس SMTPNotSupportedError است.

SMTP.sendmail(from_addr, to_addrs, msg, mail_options=(), rcpt_options=())¶

ارسال ایمیل. آرگومان‌های الزامی عبارت‌اند از: یک رشته‌ی آدرس فرستنده مطابق RFC 822، فهرستی از رشته‌های آدرس گیرنده مطابق RFC 822 (یک رشته‌ی ساده به‌عنوان فهرستی حاوی ۱ آدرس در نظر گرفته می‌شود)، و یک رشته‌ی پیام. فراخواننده می‌تواند فهرستی از گزینه‌های ESMTP (مانند "8bitmime") را برای استفاده در دستورات MAIL FROM به‌عنوان mail_options ارسال کند. گزینه‌های ESMTP (مانند دستورات DSN) را که باید با تمام دستورات RCPT استفاده شوند، می‌توان به‌عنوان rcpt_options ارسال کرد. هر گزینه باید به‌صورت رشته‌ای ارسال شود که حاوی متن کامل گزینه باشد، از جمله هر کلید احتمالی (برای مثال، "NOTIFY=SUCCESS,FAILURE"). (اگر نیاز دارید برای گیرندگان مختلف از گزینه‌های ESMTP متفاوت استفاده کنید، باید از متدهای سطح پایین مانند mail()، rcpt() و data() برای ارسال پیام استفاده کنید.)

توجه

پارامترهای from_addr و to_addrs برای ساخت پاکت پیام (message envelope) مورد استفاده‌ی عوامل انتقال به کار می‌روند. sendmail به هیچ وجه سرآیندهای پیام را تغییر نمی‌دهد.

msg ممکن است یک رشته حاوی نویسه‌های محدوده ASCII یا یک رشته بایتی باشد. یک رشته با استفاده از کدک ascii به بایت کدگذاری می‌شود و نویسه‌های منفرد \r و \n به نویسه‌های \r\n تبدیل می‌شوند. یک رشته بایتی تغییر نمی‌کند.

اگر در این نشست پیش‌تر دستور EHLO یا HELO ارسال نشده باشد، این متد ابتدا EHLO ESMTP را امتحان می‌کند. اگر سرور ESMTP را پشتیبانی کند، اندازه پیام و هر یک از گزینه‌های مشخص‌شده به آن ارسال می‌شوند (اگر گزینه در مجموعه قابلیت‌هایی باشد که سرور اعلام می‌کند). اگر EHLO ناموفق باشد، HELO امتحان می‌شود و گزینه‌های ESMTP حذف می‌شوند.

این متد در صورت پذیرفته شدن ایمیل برای حداقل یک گیرنده، به‌طور عادی برمی‌گردد. در غیر این صورت استثنایی پرتاب خواهد کرد. یعنی اگر این متد استثنایی پرتاب نکند، ایمیل شما باید به دست کسی برسد. اگر این متد استثنایی پرتاب نکند، یک دیکشنری برمی‌گرداند که برای هر گیرنده‌ای که رد شده باشد، یک آیتم دارد. هر آیتم شامل یک تاپل از کد خطای SMTP و پیام خطای همراه ارسال‌شده از سوی سرور است.

اگر SMTPUTF8 در mail_options گنجانده شده باشد و سرور از آن پشتیبانی کند، from_addr و to_addrs می‌توانند شامل نویسه‌های غیر ASCII باشند.

این متد ممکن است استثناهای زیر را پرتاب کند:

SMTPRecipientsRefused: همه‌ی گیرنده‌ها رد شدند. هیچ‌کس ایمیل را دریافت نکرد.
SMTPHeloError: سرور به‌درستی به سلام HELO پاسخ نداد.
SMTPSenderRefused: سرور from_addr را نپذیرفت.
SMTPDataError: سرور با کد خطای غیرمنتظره‌ای پاسخ داد (غیر از رد یک گیرنده).
SMTPNotSupportedError: SMTPUTF8 در mail_options داده شده است، اما سرور از آن پشتیبانی نمی‌کند.

مگر اینکه خلاف آن ذکر شده باشد، اتصال حتی پس از پرتاب شدن یک استثنا باز خواهد بود.

تغییر یافته در نسخه‌ی 3.2: ممکن است msg یک رشته بایتی باشد.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از SMTPUTF8 اضافه شد، و اگر SMTPUTF8 تعیین شده باشد اما سرور از آن پشتیبانی نکند، ممکن است SMTPNotSupportedError پرتاب شود.

SMTP.send_message(msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())¶

این یک متد سهولت‌بخش برای فراخوانی sendmail() با پیامی است که توسط یک شیء email.message.Message بازنمایی می‌شود. آرگومان‌ها همان معنای خود در sendmail() را دارند، به‌جز اینکه msg یک شیء Message است.

اگر from_addr برابر None یا to_addrs برابر None باشد، send_message آن آرگومان‌ها را با نشانی‌های استخراج‌شده از سرآیندهای msg پر می‌کند، همان‌طور که در RFC 5322: مشخص شده است، from_addr در صورت وجود به فیلد Sender و در غیر این صورت به فیلد From تنظیم می‌شود. to_addrs مقدارهای فیلدهای To، Cc و Bcc را (در صورت وجود) از msg با هم ترکیب می‌کند. اگر دقیقاً یک مجموعه از سرآیندهای Resent-* در پیام وجود داشته باشد، سرآیندهای معمولی نادیده گرفته می‌شوند و در عوض از سرآیندهای Resent-* استفاده می‌شود. اگر پیام شامل بیش از یک مجموعه از سرآیندهای Resent-* باشد، یک ValueError پرتاب می‌شود، زیرا هیچ راهی برای تشخیص بدون ابهام آخرین مجموعه از سرآیندهای Resent- وجود ندارد.

send_message msg را با استفاده از BytesGenerator با \r\n به‌عنوان linesep سریال‌سازی می‌کند و sendmail() را فراخوانی می‌کند تا پیام حاصل ارسال شود. صرف‌نظر از مقادیر from_addr و to_addrs، send_message هیچ‌یک از سرآیند‌های Bcc یا Resent-Bcc را که ممکن است در msg وجود داشته باشند، ارسال نمی‌کند. اگر هر یک از نشانی‌های موجود در from_addr و to_addrs حاوی نویسه‌های غیر ASCII باشد و سرور پشتیبانی از SMTPUTF8 را اعلام نکند، استثنای SMTPNotSupportedError پرتاب می‌شود. در غیر این صورت، Message با یک نسخه‌ی مشابه از policy خود سریال‌سازی می‌شود که در آن ویژگی utf8 روی True تنظیم شده است، و SMTPUTF8 و BODY=8BITMIME به mail_options افزوده می‌شوند.

اضافه شده در نسخه‌ی 3.2.

اضافه شده در نسخه‌ی 3.5: پشتیبانی از نشانی‌های بین‌المللی‌شده (SMTPUTF8).

SMTP.quit()¶: نشست SMTP را پایان می‌دهد و اتصال را می‌بندد. نتیجه‌ی دستور QUIT SMTP را برمی‌گرداند.

متدهای سطح پایینی که متناظر با فرمان‌های استاندارد SMTP/ESMTP یعنی HELP، RSET، NOOP، MAIL، RCPT و DATA هستند نیز پشتیبانی می‌شوند. معمولاً نیازی به فراخوانی مستقیم آن‌ها نیست، بنابراین در اینجا مستند نشده‌اند. برای جزئیات، به کد ماژول مراجعه کنید.

علاوه بر این، یک نمونه SMTP دارای ویژگی‌های زیر است:

SMTP.helo_resp¶: پاسخ به فرمان HELO، helo() را ببینید.

SMTP.ehlo_resp¶: پاسخ به دستور EHLO، ehlo() را ببینید.

SMTP.does_esmtp¶: مقدار بولی که نشان می‌دهد آیا سرور از ESMTP پشتیبانی می‌کند یا خیر؛ ehlo() را ببینید.

SMTP.esmtp_features¶: دیکشنری‌ای از نام‌های افزونه‌های سرویس SMTP پشتیبانی‌شده توسط سرور، ehlo() را ببینید.

مثال SMTP¶

این مثال از کاربر می‌خواهد که نشانی‌های مورد نیاز در پاکت پیام (نشانی‌های 'To' و 'From') و پیامی را که باید تحویل داده شود وارد کند. توجه داشته باشید که سرآیندهایی که باید همراه پیام باشند، باید به همان شکلی که وارد شده‌اند در پیام گنجانده شوند؛ این مثال هیچ پردازشی روی سرآیندهای RFC 822 انجام نمی‌دهد. به‌ویژه، نشانی‌های 'To' و 'From' باید به‌صراحت در سرآیندهای پیام گنجانده شوند:

import smtplib

def prompt(title):
    return input(title).strip()

from_addr = prompt("From: ")
to_addrs  = prompt("To: ").split()
print("Enter message, end with ^D (Unix) or ^Z (Windows):")

# Add the From: and To: headers at the start!
lines = [f"From: {from_addr}", f"To: {', '.join(to_addrs)}", ""]
while True:
    try:
        line = input()
    except EOFError:
        break
    else:
        lines.append(line)

msg = "\r\n".join(lines)
print("Message length is", len(msg))

server = smtplib.SMTP("localhost")
server.set_debuglevel(1)
server.sendmail(from_addr, to_addrs, msg)
server.quit()

توجه

به‌طور کلی، شما می‌خواهید از قابلیت‌های بسته‌ی email برای ساخت یک پیام ایمیل استفاده کنید، که سپس می‌توانید آن را از طریق send_message() ارسال کنید؛ email: مثال‌ها را ببینید.

`smtplib` --- کلاینت پروتکل SMTP¶

اشیای SMTP¶

مثال SMTP¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

smtplib --- کلاینت پروتکل SMTP¶

اشیای SMTP¶

مثال SMTP¶

`smtplib` --- کلاینت پروتکل SMTP¶