imaplib --- کلاینت پروتکل IMAP4

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

این ماژول سه کلاس IMAP4، IMAP4_SSL و IMAP4_stream را تعریف می‌کند، که اتصال به یک سرور IMAP4 را کپسوله می‌کنند و زیرمجموعه‌ی بزرگی از پروتکل کلاینت IMAP4rev1 را، همان‌طور که در RFC 3501 تعریف شده است، پیاده‌سازی می‌کنند. این ماژول با سرورهای IMAP4 (RFC 1730) سازگاری رو به عقب دارد، اما توجه داشته باشید که دستور STATUS در IMAP4 پشتیبانی نمی‌شود.

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

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

ماژول imaplib سه کلاس را ارائه می‌دهد، IMAP4 کلاس پایه است:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)

این کلاس پروتکل واقعی IMAP4 را پیاده‌سازی می‌کند. هنگام مقداردهی اولیه‌ی نمونه، اتصال ایجاد می‌شود و نسخه‌ی پروتکل (IMAP4 یا IMAP4rev1) تعیین می‌شود. اگر host مشخص نشده باشد، '' (میزبان محلی) استفاده می‌شود. اگر port ذکر نشود، پورت استاندارد IMAP4 (۱۴۳) استفاده می‌شود. پارامتر اختیاری timeout، مهلت زمانی را به ثانیه برای تلاش اتصال مشخص می‌کند. اگر مهلت داده نشود یا None باشد، مهلت پیش‌فرض سراسری سوکت استفاده می‌شود.

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

>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

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

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

سه استثنا به‌عنوان ویژگی‌هایی از کلاس IMAP4 تعریف شده‌اند:

exception IMAP4.error

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

exception IMAP4.abort

خطاهای سرور IMAP4 باعث پرتاب این استثنا می‌شوند. این یک زیرکلاس از IMAP4.error است. توجه داشته باشید که بستن نمونه و ایجاد یک نمونه جدید معمولاً امکان بازیابی از این استثنا را فراهم می‌کند.

exception IMAP4.readonly

این استثنا زمانی پرتاب می‌شود که وضعیت یک صندوق پستی قابل‌نوشتن توسط سرور تغییر کند. این استثنا زیرکلاسی از IMAP4.error است. اکنون کلاینت دیگری اجازه‌ی نوشتن دارد و برای به دست آوردن دوباره‌ی اجازه‌ی نوشتن، باید صندوق پستی دوباره باز شود.

همچنین یک زیرکلاس برای اتصالات امن وجود دارد:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)

این یک زیرکلاس مشتق‌شده از IMAP4 است که از طریق یک سوکت رمزنگاری‌شده با SSL متصل می‌شود (برای استفاده از این کلاس، به یک ماژول socket نیاز دارید که با پشتیبانی از SSL کامپایل شده باشد). اگر host مشخص نشده باشد، از '' (میزبان محلی) استفاده می‌شود. اگر port حذف شده باشد، از پورت استاندارد IMAP4-over-SSL (۹۹۳) استفاده می‌شود. ssl_context یک شیء ssl.SSLContext است که امکان تجمیع گزینه‌های پیکربندی SSL، گواهی‌ها و کلیدهای خصوصی را در یک ساختار واحد (که ممکن است طولانی‌مدت باشد) فراهم می‌کند. لطفاً برای بهترین شیوه‌ها، ملاحظات امنیتی را مطالعه کنید.

توجه

با ssl_context پیش‌فرض، اتصال رمزگذاری شده است، اما گواهی سرور و نام میزبان تأیید نمی‌شوند. برای تأیید آن‌ها، یک زمینه ایجادشده توسط ssl.create_default_context() را ارسال کنید.

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

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

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

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

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

دومین زیرکلاس امکان اتصال‌هایی را که توسط یک فرآیند فرزند ایجاد شده‌اند، فراهم می‌کند:

class imaplib.IMAP4_stream(command)

این زیرکلاسی مشتق‌شده از IMAP4 است که به توصیف‌گرهای پرونده stdin/stdout ایجادشده از طریق ارسال command به subprocess.Popen() متصل می‌شود.

توابع ابزار زیر تعریف شده‌اند:

imaplib.Internaldate2tuple(resp)

یک bytes-like object حاوی پاسخ IMAP4 INTERNALDATE را تجزیه می‌کند و زمان محلی متناظر را برمی‌گرداند. مقدار بازگشتی یک تاپل time.struct_time یا None است اگر ورودی قالب نادرستی داشته باشد.

imaplib.Int2AP(num)

یک عدد صحیح را با استفاده از نویسه‌های مجموعه‌ی [A .. P] به یک نمایش بایتی تبدیل می‌کند.

imaplib.ParseFlags(resp)

یک bytes-like object حاوی پاسخ FLAGS IMAP4 را به یک تاپل از پرچم‌های جداگانه به‌صورت bytes تبدیل می‌کند. اگر ورودی قالب نادرستی داشته باشد، مقدار بازگشتی یک تاپل خالی است.

imaplib.Time2Internaldate(date_time)

date_time را به نمایش INTERNALDATE در IMAP4 تبدیل می‌کند. مقدار بازگشتی یک رشته به شکل: "DD-Mmm-YYYY HH:MM:SS +HHMM" (شامل علامت‌های نقل‌قول دوتایی) است. آرگومان date_time می‌تواند یک عدد (int یا float) باشد که ثانیه‌های سپری‌شده از مبدأ زمان را نشان می‌دهد (مانند آنچه time.time() بازمی‌گرداند)، یک تاپل ۹تایی که زمان محلی را نشان می‌دهد، یک نمونه از time.struct_time (مانند آنچه time.localtime() بازمی‌گرداند)، یک نمونه آگاه از datetime.datetime، یا یک رشته‌ی دارای علامت‌های نقل‌قول دوتایی باشد. در آخرین حالت، فرض می‌شود که از قبل در قالب صحیح باشد.

توجه داشته باشید که شماره‌های پیام IMAP4 با تغییر صندوق پستی تغییر می‌کنند؛ به‌ویژه، پس از اینکه دستور EXPUNGE حذف‌ها را انجام داد، پیام‌های باقی‌مانده دوباره شماره‌گذاری می‌شوند. بنابراین بسیار توصیه می‌شود که به‌جای آن‌ها از UIDها، همراه با دستور UID استفاده کنید.

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

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

اسناد توصیف‌کننده پروتکل، کدهای منبع سرورهایی که آن را پیاده‌سازی می‌کنند، تهیه‌شده توسط مرکز اطلاعات IMAP دانشگاه واشینگتن، همگی در (کد منبع) https://github.com/uw-imap/imap (نگه‌داری نمی‌شود) یافت می‌شوند.

اشیای IMAP4

تمام دستورات IMAP4rev1 با متدهایی به همان نام، چه با حروف بزرگ و چه با حروف کوچک، بازنمایی می‌شوند.

همه آرگومان‌های دستورات به رشته تبدیل می‌شوند، به‌جز AUTHENTICATE و آخرین آرگومان APPEND که به‌صورت یک IMAP4 literal ارسال می‌شود. در صورت لزوم (وقتی رشته شامل نویسه‌های حساس به پروتکل IMAP4 باشد و با هیچ‌کدام از پرانتز یا علامت نقل‌قول دوتایی محصور نشده باشد)، هر رشته داخل علامت نقل‌قول قرار می‌گیرد. با این حال، آرگومان password برای دستور LOGIN همیشه داخل علامت نقل‌قول قرار می‌گیرد. اگر می‌خواهید از قرار گرفتن یک آرگومان رشته‌ای داخل علامت نقل‌قول جلوگیری کنید (مثلاً آرگومان flags برای STORE)، آن رشته را داخل پرانتز قرار دهید (مثلاً r'(\Deleted)'). به‌طور کلی، آرگومان‌ها را بدون علامت نقل‌قول ارسال کنید و بگذارید ماژول در صورت نیاز آن‌ها را داخل علامت نقل‌قول قرار دهد. آرگومانی که از قبل داخل علامت نقل‌قول دوتایی محصور شده باشد، بدون تغییر باقی می‌ماند، تا کدی که خودش آرگومان‌ها را داخل علامت نقل‌قول قرار می‌دهد همچنان به کار خود ادامه دهد.

بیشتر دستورها یک تاپلبرمی‌گردانند: (type, [data, ...]) که در آن type معمولاً 'OK' یا 'NO' است، و data یا متن پاسخ دستور است، یا نتایج الزامی دستور. هر data یا یک bytes است، یا یک تاپل. اگر یک تاپل باشد، بخش اول سرآیند پاسخ است، و بخش دوم شامل داده است (یعنی مقدار 'literal').

گزینه‌ی message_set برای دستورات زیر، رشته‌ای است که یک یا چند پیامِ مورد عمل را مشخص می‌کند. این رشته ممکن است یک شماره‌ی پیام ساده ('1')، یک بازه از شماره‌های پیام ('2:4')، یا گروهی از بازه‌های ناپیوسته باشد که با کاما از هم جدا شده‌اند ('1:3,6:9'). یک بازه می‌تواند شامل یک ستاره برای نشان دادن کران بالای بی‌نهایت باشد ('3:*').

یک نمونه از IMAP4 دارای متدهای زیر است:

IMAP4.append(mailbox, flags, date_time, message)

message را به صندوق پستی نام‌گذاری‌شده می‌افزاید.

flags می‌تواند None یا رشته‌ای از توکن‌های پرچم IMAP باشد. پرچم‌های متعدد با فاصله از یکدیگر جدا می‌شوند، برای مثال r'\Seen \Answered'. اگر flags از قبل در پرانتز قرار نداشته باشد، پرانتزها به‌طور خودکار اضافه می‌شوند.

IMAP4.authenticate(mechanism, authobject)

فرمان احراز هویت --- به پردازش پاسخ نیاز دارد.

mechanism مشخص می‌کند که کدام سازوکار احراز هویت باید استفاده شود؛ این سازوکار باید در متغیر نمونه capabilities به شکل AUTH=mechanism ظاهر شود.

authobject باید یک شیء فراخوانی‌پذیر باشد:

data = authobject(response)

برای پردازش پاسخ‌های ادامه‌ی سرور فراخوانی خواهد شد؛ آرگومان response که به آن داده می‌شود، bytes خواهد بود. باید data از نوع bytes را برگرداند که به‌صورت base64 کدگذاری و به سرور ارسال خواهد شد. اگر به‌جای آن باید پاسخ لغو کلاینت * ارسال شود، باید None برگرداند.

تغییر یافته در نسخه‌ی 3.5: نام‌های کاربری و گذرواژه‌های رشته‌ای اکنون به‌جای محدود بودن به ASCII، به utf-8 کدگذاری می‌شوند.

IMAP4.check()

نقطه بازرسی صندوق پستی را روی سرور ایجاد کنید.

IMAP4.close()

صندوق پستی انتخاب‌شده‌ی فعلی را می‌بندد. پیام‌های حذف‌شده از صندوق پستی قابل‌نوشتن حذف می‌شوند. این فرمان توصیه‌شده پیش از LOGOUT است.

IMAP4.copy(message_set, new_mailbox)

پیام‌های message_set را به انتهای new_mailbox کپی کنید.

IMAP4.create(mailbox)

صندوق پستی جدیدی با نام mailbox ایجاد کنید.

IMAP4.delete(mailbox)

صندوق پستی قدیمی به نام mailbox را حذف کنید.

IMAP4.deleteacl(mailbox, who)

فهرست‌های کنترل دسترسی (ACLs) تنظیم‌شده برای who بر روی mailbox را حذف کنید (هرگونه حقی را بردارید).

IMAP4.enable(capability)

فعال‌سازی capability (ببینید RFC 5161). بیشتر قابلیت‌ها نیازی به فعال‌سازی ندارند. در حال حاضر فقط قابلیت UTF8=ACCEPT پشتیبانی می‌شود (ببینید RFC 6855).

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

IMAP4.expunge()

آیتم‌های حذف‌شده را به‌طور دائم از صندوق پستی انتخاب‌شده حذف می‌کند. برای هر پیام حذف‌شده یک پاسخ EXPUNGE تولید می‌کند. داده بازگشتی شامل فهرستی از شماره پیام‌های EXPUNGE به ترتیب دریافت است.

IMAP4.fetch(message_set, message_parts)

(بخش‌هایی از) پیام‌ها را واکشی کنید. message_parts باید رشته‌ای از نام‌های بخش پیام باشد که داخل پرانتز قرار گرفته است، مثلاً: "(UID BODY[TEXT])". داده‌های بازگشتی، تاپل‌هایی از پاکت (envelope) و داده‌ی بخش پیام هستند.

IMAP4.getacl(mailbox)

ACLs برای mailbox را دریافت کنید. این متد غیراستاندارد است، اما توسط سرور Cyrus پشتیبانی می‌شود.

IMAP4.getannotation(mailbox, entry, attribute)

ANNOTATIONs مشخص‌شده برای mailbox را بازیابی می‌کند. این متد غیراستاندارد است، اما توسط سرور Cyrus پشتیبانی می‌شود.

IMAP4.getquota(root)

میزان استفاده از منابع و محدودیت‌های quota root را دریافت کنید. این متد بخشی از افزونه‌ی QUOTA در IMAP4 است که در rfc2087 تعریف‌شده است.

IMAP4.getquotaroot(mailbox)

فهرست quota roots برای mailbox مشخص‌شده را دریافت کنید. این متد بخشی از افزونه IMAP4 QUOTA تعریف‌شده در rfc2087 است.

IMAP4.idle(duration=None)

یک Idler برمی‌گرداند: یک مدیر زمینه پیمایش‌پذیر که دستور IDLE در IMAP4 را همان‌طور که در RFC 2177 تعریف شده است، پیاده‌سازی می‌کند.

شیء برگردانده‌شده هنگامی که با دستور with فعال می‌شود، فرمان IDLE را ارسال می‌کند، پاسخ‌های بدون برچسب IMAP را از طریق پروتکل iterator تولید می‌کند و هنگام خروج از زمینه، DONE را ارسال می‌کند.

تمام پاسخ‌های بدون برچسبی که پس از ارسال دستور IDLE می‌رسند (از جمله هر پاسخی که پیش از تأیید دستور توسط سرور می‌رسد) از طریق تکرار در دسترس خواهند بود. همه پاسخ‌های باقی‌مانده (آن‌هایی که در زمینه with تکرار نشده‌اند) را می‌توان پس از پایان IDLE به روش معمول با استفاده از IMAP4.response() بازیابی کرد.

پاسخ‌ها به‌صورت تاپل‌های (type, [data, ...]) نمایش داده می‌شوند، همان‌طور که در اشیاء IMAP4 توضیح داده شده است.

آرگومان duration حداکثر مدت‌زمان (به ثانیه) را برای بی‌کار ماندن تنظیم می‌کند؛ پس از آن، هر تکرار جاری متوقف خواهد شد. این آرگومان می‌تواند یک int یا float باشد، یا برای نداشتن محدودیت زمانی، None باشد. فراخوان‌کنندگانی که می‌خواهند از مهلت‌های زمانی بی‌کاری در سرورهایی که آن‌ها را اعمال می‌کنند اجتناب کنند، باید آن را حداکثر ۲۹ دقیقه (۱۷۴۰ ثانیه) نگه دارند. به یک اتصال سوکت نیاز دارد؛ در اتصال‌های IMAP4_stream، duration باید None باشد.

>>> with M.idle(duration=29 * 60) as idler:
...     for typ, data in idler:
...         print(typ, data)
...
EXISTS [b'1']
RECENT [b'1']
Idler.burst(interval=0.1)

یک رگبار از پاسخ‌ها را با فاصله‌ای حداکثر interval ثانیه از یکدیگر تولید کنید (که به‌صورت یک int یا float بیان می‌شود).

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

به یک اتصال سوکت نیاز دارد؛ با اتصال‌های IMAP4_stream کار نمی‌کند.

>>> with M.idle() as idler:
...     # get a response and any others following by < 0.1 seconds
...     batch = list(idler.burst())
...     print(f'processing {len(batch)} responses...')
...     print(batch)
...
processing 3 responses...
[('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]

نکته

حداکثر مدت‌زمان زمینه‌ی IDLE، همان‌طور که به IMAP4.idle() ارسال می‌شود، هنگام انتظار برای نخستین پاسخ در یک رگبار رعایت می‌شود. بنابراین، یک Idler منقضی‌شده باعث می‌شود این تولیدگر بلافاصله بدون تولید هیچ چیزی بازگشت کند. فراخوانی‌کنندگان باید در صورت استفاده از آن در یک حلقه، این را در نظر بگیرند.

توجه

پیمایش‌گر بازگردانده‌شده توسط IMAP4.idle() فقط درون یک دستور with قابل استفاده است. پیش یا پس از آن زمینه، پاسخ‌های درخواست‌نشده هر زمان که یک فرمان به پایان برسد، به‌صورت داخلی جمع‌آوری می‌شوند و می‌توانند با IMAP4.response() بازیابی شوند.

توجه

نام و ساختار کلاس Idler رابط‌های داخلی هستند و ممکن است تغییر کنند. کد فراخوان می‌تواند بر پایدار ماندن مدیریت زمینه، تکرار و متد عمومی آن اتکا کند، اما نباید از این کلاس زیرکلاس بسازد، آن را نمونه‌سازی کند، آن را مقایسه کند یا به هر شکل دیگری مستقیماً به آن ارجاع دهد.

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

IMAP4.list(directory='', pattern='*')

نام صندوق‌های پستی در directory را که با pattern مطابقت دارند، فهرست می‌کند. مقدار پیش‌فرض directory، پوشه پستی سطح بالا است و pattern به‌طور پیش‌فرض با هر چیزی مطابقت دارد. داده بازگشتی شامل فهرستی از پاسخ‌های LIST است.

IMAP4.login(user, password)

کلاینت را با استفاده از یک گذرواژه‌ی متن‌آشکار شناسایی کنید. password داخل علامت نقل‌قول قرار خواهد گرفت.

IMAP4.login_cram_md5(user, password)

اجبار به استفاده از احراز هویت CRAM-MD5 هنگام شناسایی کلاینت، برای محافظت از گذرواژه. تنها زمانی کار می‌کند که پاسخ CAPABILITY سرور شامل عبارت AUTH=CRAM-MD5 باشد.

تغییر یافته در نسخه‌ی 3.14: اگر پشتیبانی از MD5 در دسترس نباشد، یک IMAP4.error پرتاب می‌شود.

IMAP4.logout()

اتصال به سرور را خاموش می‌کند. پاسخ BYE سرور را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.8: این متد دیگر استثناهای دلخواه را به‌صورت خاموش نادیده نمی‌گیرد.

IMAP4.lsub(directory='', pattern='*')

نام‌های صندوق پستی مشترک‌شده در پوشه را که با الگو مطابقت دارند، فهرست می‌کند. directory به‌طور پیش‌فرض پوشه سطح بالا است و pattern به‌طور پیش‌فرض با هر صندوق پستی مطابقت دارد. داده‌های بازگشتی، تاپل‌هایی از پاکت و داده‌ی بخش پیام هستند.

IMAP4.myrights(mailbox)

نمایش فهرست‌های کنترل دسترسی (ACL) من برای یک صندوق پستی (یعنی حقوقی که من روی صندوق پستی دارم).

IMAP4.namespace()

فضای نام های IMAP را، همان‌طور که در RFC 2342 تعریف شده است، بازمی‌گرداند.

IMAP4.noop()

NOOP را به سرور ارسال کنید.

IMAP4.open(host, port, timeout=None)

سوکتی را به port در host باز می‌کند. پارامتر اختیاری timeout مهلت زمانی‌ای را بر حسب ثانیه برای تلاش برای اتصال مشخص می‌کند. اگر timeout داده نشود یا None باشد، از مهلت زمانی پیش‌فرض سراسری سوکت استفاده می‌شود. همچنین توجه داشته باشید که اگر پارامتر timeout برابر صفر تنظیم شده باشد، برای رد کردن ایجاد یک سوکت غیرمسدود، یک ValueError پرتاب می‌شود. این متد به‌طور ضمنی توسط سازنده‌ی IMAP4 فراخوانی می‌شود. اشیای اتصال برقرارشده توسط این متد در متدهای IMAP4.read()، IMAP4.readline()، IMAP4.send() و IMAP4.shutdown() استفاده خواهند شد. شما می‌توانید این متد را بازنویسی کنید.

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

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

IMAP4.partial(message_num, message_part, start, length)

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

IMAP4.proxyauth(user)

احراز هویت به‌عنوان user را فرض کنید. به یک مدیر مجاز اجازه می‌دهد تا به‌صورت پراکسیبه صندوق پستی هر کاربری دسترسی یابد.

IMAP4.read(size)

size بایت را از سرور راه‌دور می‌خواند. شما می‌توانید این متد را بازنویسی کنید.

IMAP4.readline()

یک خط را از سرور راه دور می‌خواند. شما می‌توانید این متد را بازنویسی کنید.

IMAP4.recent()

برای به‌روزرسانی از سرور درخواست کنید. اگر پیام جدیدی وجود نداشته باشد، داده‌ی بازگشتی None است، در غیر این صورت مقدار پاسخ RECENT است.

IMAP4.rename(oldmailbox, newmailbox)

تغییر نام صندوق پستی با نام oldmailbox به newmailbox.

IMAP4.response(code)

داده‌ها برای code پاسخ را در صورت دریافت برمی‌گرداند، یا None. کد داده‌شده را به‌جای نوع معمول برمی‌گرداند.

IMAP4.search(charset, criterion[, ...])

صندوق پستی را برای پیام‌های منطبق جستجو می‌کند. charset می‌تواند None باشد، که در این صورت هیچ CHARSET در درخواست به سرور مشخص نخواهد شد. پروتکل IMAP ایجاب می‌کند که حداقل یک معیار مشخص شود؛ هنگامی که سرور خطایی بازگرداند، یک استثنا پرتاب خواهد شد. اگر قابلیت UTF8=ACCEPT با استفاده از دستور enable() فعال شده باشد، charset باید None باشد.

مثال:

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')
IMAP4.select(mailbox='INBOX', readonly=False)

یک صندوق پستی را انتخاب کنید. داده‌ی بازگشتی، تعداد پیام‌های موجود در mailbox است (پاسخ EXISTS). مقدار پیش‌فرض mailbox برابر 'INBOX' است. اگر پرچم readonly تنظیم شده باشد، تغییرات در صندوق پستی مجاز نیست.

IMAP4.send(data)

data را به سرور راه دور ارسال می‌کند. شما می‌توانید این متد را بازنویسی کنید.

یک رویداد حسابرسی imaplib.send را با آرگومان‌های self و data پرتاب می‌کند.

IMAP4.setacl(mailbox, who, what)

یک ACL برای mailbox تنظیم کنید. این متد استاندارد نیست، اما توسط سرور Cyrus پشتیبانی می‌شود.

IMAP4.setannotation(mailbox, entry, attribute[, ...])

ANNOTATIONs را برای mailbox تنظیم می‌کند. این متد غیراستاندارد است، اما توسط سرور Cyrus پشتیبانی می‌شود.

IMAP4.setquota(root, limits)

محدودیت‌های منبع limits برای quota root را تنظیم می‌کند. این متد بخشی از افزونه‌ی IMAP4 QUOTA تعریف‌شده در rfc2087 است.

IMAP4.shutdown()

اتصال برقرارشده در open را می‌بندد. این متد به‌طور ضمنی توسط IMAP4.logout() فراخوانی می‌شود. شما می‌توانید این متد را بازنویسی کنید.

IMAP4.socket()

نمونه سوکت استفاده‌شده برای اتصال به سرور را برمی‌گرداند.

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

دستور sort گونه‌ای از search با معناشناسی مرتب‌سازی برای نتایج است. داده‌ی بازگشتی شامل فهرستی جداشده با فاصله از شماره‌های پیام منطبق است.

Sort دو آرگومان پیش از آرگومان(های) search_criterion دارد؛ فهرستی داخل پرانتز از sort_criteria و charset جستجو. توجه داشته باشید که برخلاف search، آرگومان charset جستجو الزامی است. همچنین دستور uid sort نیز وجود دارد که معادل sort است، همان‌طور که uid search معادل search است. دستور sort ابتدا صندوق پستی را برای پیام‌هایی که با معیارهای جستجوی داده‌شده مطابقت دارند، جستجو می‌کند و از آرگومان charset برای تفسیر رشته‌های موجود در معیارهای جستجو استفاده می‌کند. سپس شماره‌های پیام‌های منطبق را برمی‌گرداند.

این یک دستور توسعه‌ای IMAP4rev1 است.

IMAP4.starttls(ssl_context=None)

فرمان STARTTLS را ارسال کنید. آرگومان ssl_context اختیاری است و باید یک شیء ssl.SSLContext باشد. این کار رمزنگاری را در اتصال IMAP فعال می‌کند. لطفاً برای بهترین شیوه‌ها، ملاحظات امنیتی را مطالعه کنید.

توجه

با ssl_context پیش‌فرض، اتصال رمزگذاری شده است، اما گواهی سرور و نام میزبان تأیید نمی‌شوند. برای تأیید آن‌ها، یک زمینه ایجادشده توسط ssl.create_default_context() را ارسال کنید.

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

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

IMAP4.status(mailbox, names)

شرایط وضعیت نام‌گذاری‌شده برای mailbox را درخواست کنید.

IMAP4.store(message_set, command, flag_list)

وضعیت پرچم‌ها را برای پیام‌های صندوق پستی تغییر می‌دهد. command در بخش 6.4.6 از RFC 3501 به‌عنوان یکی از مقادیر "FLAGS"، "+FLAGS" یا "-FLAGS" مشخص شده است، که به‌صورت اختیاری می‌تواند پسوند ".SILENT" داشته باشد.

برای مثال، برای تنظیم پرچم حذف روی همه‌ی پیام‌ها:

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()

توجه

ایجاد پرچم‌های حاوی ']' (برای مثال: "[test]") RFC 3501 (پروتکل IMAP) را نقض می‌کند. با این حال، imaplib از نظر تاریخی اجازه‌ی ایجاد چنین پرچم‌هایی را می‌داده است و سرورهای IMAP محبوب، مانند Gmail، چنین پرچم‌هایی را می‌پذیرند و تولید می‌کنند. برنامه‌هایی غیر از پایتون نیز وجود دارند که چنین پرچم‌هایی را ایجاد می‌کنند. اگرچه این یک نقض RFC است و انتظار می‌رود کلاینت‌ها و سرورهای IMAP سخت‌گیر باشند، imaplib همچنان به دلایل سازگاری با نسخه‌های پیشین اجازه می‌دهد چنین پرچم‌هایی ایجاد شوند، و از پایتون 3.6، اگر از سرور ارسال شوند، آن‌ها را مدیریت می‌کند، زیرا این کار سازگاری در دنیای واقعی را بهبود می‌بخشد.

IMAP4.subscribe(mailbox)

اشتراک در صندوق پستی جدید.

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

دستور thread گونه‌ای از search با معنای نخ‌بندی برای نتایج است. داده‌های بازگشتی شامل فهرستی جداشده با فاصله از اعضای نخ هستند.

اعضای نخ شامل صفر یا چند شماره پیام هستند که با فاصله از هم جدا شده‌اند و والد و فرزند متوالی را نشان می‌دهند.

Thread دو آرگومان پیش از آرگومان یا آرگومان‌های search_criterion دارد؛ یک threading_algorithm و charset جستجو. توجه داشته باشید که برخلاف search، آرگومان charset جستجو الزامی است. هم‌چنین یک دستور uid thread وجود دارد که متناظر با thread است، همان‌طور که uid search متناظر با search است. دستور thread ابتدا صندوق پستی را برای یافتن پیام‌هایی که با معیارهای جستجوی داده‌شده مطابقت دارند، جستجو می‌کند و از آرگومان charset برای تفسیر رشته‌های موجود در معیارهای جستجو استفاده می‌کند. سپس پیام‌های منطبق را به‌صورت نخ‌بندی‌شده بر اساس الگوریتم نخ‌بندی مشخص‌شده بازمی‌گرداند.

این یک دستور توسعه‌ای IMAP4rev1 است.

IMAP4.uid(command, arg[, ...])

دستور را با آرگومان‌هایی برای پیام‌های شناسایی‌شده با UID، به‌جای شماره پیام، اجرا می‌کند. پاسخ متناسب با دستور را برمی‌گرداند. دست‌کم یک آرگومان باید ارائه شود؛ اگر هیچ آرگومانی ارائه نشود، سرور خطایی برمی‌گرداند و استثنایی پرتاب خواهد شد.

IMAP4.unsubscribe(mailbox)

اشتراک خود را از صندوق پستی قدیمی لغو کنید.

IMAP4.unselect()

imaplib.IMAP4.unselect() منابع سرور مرتبط با صندوق پستی انتخاب‌شده را آزاد می‌کند و سرور را به وضعیت احراز هویت‌شده بازمی‌گرداند. این دستور همان اقداماتی را انجام می‌دهد که imaplib.IMAP4.close() انجام می‌دهد، با این تفاوت که هیچ پیامی به‌طور دائم از صندوق پستی انتخاب‌شده‌ی فعلی حذف نمی‌شود.

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

IMAP4.xatom(name[, ...])

اجازه دادن به دستورات توسعه‌ای ساده که توسط سرور در پاسخ CAPABILITY اعلام می‌شوند.

ویژگی‌های زیر برای نمونه‌های IMAP4 تعریف شده‌اند:

IMAP4.capabilities

A tuple of the capabilities advertised by the server, in upper case.

It is set when the connection is established, and refreshed after a successful login(), authenticate() or starttls(), because the server can advertise different capabilities in different connection states.

تغییر یافته در نسخه‌ی 3.14.7: Refreshed after login() and authenticate().

IMAP4.PROTOCOL_VERSION

جدیدترین پروتکل پشتیبانی‌شده در پاسخ CAPABILITY از سرور.

IMAP4.debug

مقدار عدد صحیح برای کنترل خروجی اشکال‌زدایی. مقدار اولیه از متغیر ماژول Debug گرفته می‌شود. مقادیر بزرگ‌تر از ۳ هر دستور را ردگیری می‌کنند.

IMAP4.utf8_enabled

مقدار بولی که معمولاً False است، اما اگر دستور enable() برای قابلیت UTF8=ACCEPT با موفقیت صادر شود، به True تنظیم می‌شود.

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

مثال IMAP4

در اینجا یک مثال حداقلی (بدون بررسی خطا) آمده است که یک صندوق پستی را باز می‌کند و تمام پیام‌ها را دریافت و چاپ می‌کند:

import getpass, imaplib

M = imaplib.IMAP4(host='example.org')
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()

توجه

یک پاسخ FETCH ممکن است حاوی داده‌های اضافی یا درخواست‌نشده باشد (به RFC 3501، بخش 7.4.2 مراجعه کنید)، بنابراین کد محصول باید به‌جای اتکا به data[0][1]، کل پاسخ را بررسی کند.