IMAP4 物件¶

All IMAP4rev1 commands are represented by methods of the same name, eitheruppercase or lowercase.

All arguments to commands are converted to strings, except forAUTHENTICATE,and the last argument toAPPEND which is passed as an IMAP4 literal. Ifnecessary (the string contains IMAP4 protocol-sensitive characters and isn'tenclosed with either parentheses or double quotes) each string is quoted.However, thepassword argument to theLOGIN command is always quoted. Ifyou want to avoid having an argument string quoted (eg: theflags argument toSTORE) then enclose the string in parentheses (eg:r'(\Deleted)').

Most commands return a tuple:(type,[data,...]) wheretype is usually'OK' or'NO', anddata is either the text from the command response,or mandated results from the command. Eachdata is either abytes, or atuple. If a tuple, then the first part is the header of the response, and thesecond part contains the data (ie: 'literal' value).

Themessage_set options to commands below is a string specifying one or moremessages to be acted upon. It may be a simple message number ('1'), a rangeof message numbers ('2:4'), or a group of non-contiguous ranges separated bycommas ('1:3,6:9'). A range can contain an asterisk to indicate an infiniteupper bound ('3:*').

IMAP4 實例擁有以下方法：

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

Appendmessage to named mailbox.

IMAP4.authenticate(mechanism,authobject)¶

Authenticate command --- requires response processing.

mechanism specifies which authentication mechanism is to be used - it shouldappear in the instance variablecapabilities in the formAUTH=mechanism.

authobject must be a callable object:

data=authobject(response)

It will be called to process server continuation responses; theresponseargument it is passed will bebytes. It should returnbytesdatathat will be base64 encoded and sent to the server. It should returnNone if the client abort response* should be sent instead.

在 3.5 版的變更:string usernames and passwords are now encoded toutf-8 instead ofbeing limited to ASCII.

IMAP4.check()¶

Checkpoint mailbox on server.

IMAP4.close()¶

Close currently selected mailbox. Deleted messages are removed from writablemailbox. This is the recommended command beforeLOGOUT.

IMAP4.copy(message_set,new_mailbox)¶

Copymessage_set messages onto end ofnew_mailbox.

IMAP4.create(mailbox)¶

Create new mailbox namedmailbox.

IMAP4.delete(mailbox)¶

Delete old mailbox namedmailbox.

IMAP4.deleteacl(mailbox,who)¶

Delete the ACLs (remove any rights) set for who on mailbox.

IMAP4.enable(capability)¶

Enablecapability (seeRFC 5161). Most capabilities do not need to beenabled. Currently only theUTF8=ACCEPT capability is supported(seeRFC 6855).

在 3.5 版被加入:Theenable() method itself, andRFC 6855 support.

IMAP4.expunge()¶

Permanently remove deleted items from selected mailbox. Generates anEXPUNGEresponse for each deleted message. Returned data contains a list ofEXPUNGEmessage numbers in order received.

IMAP4.fetch(message_set,message_parts)¶

Fetch (parts of) messages.message_parts should be a string of message partnames enclosed within parentheses, eg:"(UIDBODY[TEXT])". Returned dataare tuples of message part envelope and data.

IMAP4.getacl(mailbox)¶

Get theACLs formailbox. The method is non-standard, but is supportedby theCyrus server.

IMAP4.getannotation(mailbox,entry,attribute)¶

Retrieve the specifiedANNOTATIONs formailbox. The method isnon-standard, but is supported by theCyrus server.

IMAP4.getquota(root)¶

Get thequotaroot's resource usage and limits. This method is part of theIMAP4 QUOTA extension defined in rfc2087.

IMAP4.getquotaroot(mailbox)¶

Get the list ofquotaroots for the namedmailbox. This method is partof the IMAP4 QUOTA extension defined in rfc2087.

IMAP4.idle(duration=None)¶

Return anIdler: an iterable context manager implementing theIMAP4IDLE command as defined inRFC 2177.

The returned object sends theIDLE command when activated by thewith statement, produces IMAP untagged responses via theiterator protocol, and sendsDONE upon context exit.

All untagged responses that arrive after sending theIDLE command(including any that arrive before the server acknowledges the command) willbe available via iteration. Any leftover responses (those not iterated inthewith context) can be retrieved in the usual way afterIDLE ends, usingIMAP4.response().

Responses are represented as(type,[data,...]) tuples, as describedinIMAP4 Objects.

Theduration argument sets a maximum duration (in seconds) to keep idling,after which any ongoing iteration will stop. It can be anint orfloat, orNone for no time limit.Callers wishing to avoid inactivity timeouts on servers that impose themshould keep this at most 29 minutes (1740 seconds).Requires a socket connection;duration must beNone onIMAP4_stream connections.

>>>withM.idle(duration=29*60)asidler:...fortyp,datainidler:...print(typ,data)...EXISTS [b'1']RECENT [b'1']

Idler.burst(interval=0.1)¶

Yield a burst of responses no more thaninterval seconds apart(expressed as anint orfloat).

Thisgenerator is an alternative to iterating one response at atime, intended to aid in efficient batch processing. It retrieves thenext response along with any immediately available subsequent responses.(For example, a rapid series ofEXPUNGE responses after a bulkdelete.)

Requires a socket connection; does not work onIMAP4_streamconnections.

>>>withM.idle()asidler:...# 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'])]

小訣竅

TheIDLE context's maximum duration, as passed toIMAP4.idle(), is respected when waiting for the first responsein a burst. Therefore, an expiredIdler will cause thisgenerator to return immediately without producing anything. Callersshould consider this if using it in a loop.

備註

The iterator returned byIMAP4.idle() is usable only within awith statement. Before or after that context, unsolicitedresponses are collected internally whenever a command finishes, and canbe retrieved withIMAP4.response().

備註

TheIdler class name and structure are internal interfaces,subject to change. Calling code can rely on its context management,iteration, and public method to remain stable, but should not subclass,instantiate, compare, or otherwise directly reference the class.

在 3.14 版被加入.

IMAP4.list([directory[,pattern]])¶

List mailbox names indirectory matchingpattern.directory defaults tothe top-level mail folder, andpattern defaults to match anything. Returneddata contains a list ofLIST responses.

IMAP4.login(user,password)¶

Identify the client using a plaintext password. Thepassword will be quoted.

IMAP4.login_cram_md5(user,password)¶

Force use ofCRAM-MD5 authentication when identifying the client to protectthe password. Will only work if the serverCAPABILITY response includes thephraseAUTH=CRAM-MD5.

在 3.14 版的變更:AnIMAP4.error is raised if MD5 support is not available.

IMAP4.logout()¶

Shutdown connection to server. Returns serverBYE response.

在 3.8 版的變更:The method no longer ignores silently arbitrary exceptions.

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

List subscribed mailbox names in directory matching pattern.directorydefaults to the top level directory andpattern defaults to match any mailbox.Returned data are tuples of message part envelope and data.

IMAP4.myrights(mailbox)¶

Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).

IMAP4.namespace()¶

Returns IMAP namespaces as defined inRFC 2342.

IMAP4.noop()¶

SendNOOP to server.

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

Opens socket toport athost. The optionaltimeout parameterspecifies a timeout in seconds for the connection attempt.If timeout is not given or isNone, the global default socket timeoutis used. Also note that if thetimeout parameter is set to be zero,it will raise aValueError to reject creating a non-blocking socket.This method is implicitly called by theIMAP4 constructor.The connection objects established by this method will be used intheIMAP4.read(),IMAP4.readline(),IMAP4.send(),andIMAP4.shutdown() methods. You may override this method.

引發一個附帶引數self、host、port 的稽核事件imaplib.open。

在 3.9 版的變更:新增timeout 參數。

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

Fetch truncated part of a message. Returned data is a tuple of message partenvelope and data.

IMAP4.proxyauth(user)¶

Assume authentication asuser. Allows an authorised administrator to proxyinto any user's mailbox.

IMAP4.read(size)¶

Readssize bytes from the remote server. You may override this method.

IMAP4.readline()¶

Reads one line from the remote server. You may override this method.

IMAP4.recent()¶

Prompt server for an update. Returned data isNone if no new messages, elsevalue ofRECENT response.

IMAP4.rename(oldmailbox,newmailbox)¶

Rename mailbox namedoldmailbox tonewmailbox.

IMAP4.response(code)¶

Return data for responsecode if received, orNone. Returns the givencode, instead of the usual type.

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

Search mailbox for matching messages.charset may beNone, in which casenoCHARSET will be specified in the request to the server. The IMAPprotocol requires that at least one criterion be specified; an exception will beraised when the server returns an error.charset must beNone iftheUTF8=ACCEPT capability was enabled using theenable()command.

範例：

# 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)¶

Select a mailbox. Returned data is the count of messages inmailbox(EXISTS response). The defaultmailbox is'INBOX'. If thereadonlyflag is set, modifications to the mailbox are not allowed.

IMAP4.send(data)¶

Sendsdata to the remote server. You may override this method.

引發一個附帶引數self、data 的稽核事件imaplib.send。

IMAP4.setacl(mailbox,who,what)¶

Set anACL formailbox. The method is non-standard, but is supported bytheCyrus server.

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

SetANNOTATIONs formailbox. The method is non-standard, but issupported by theCyrus server.

IMAP4.setquota(root,limits)¶

Set thequotaroot's resourcelimits. This method is part of the IMAP4QUOTA extension defined in rfc2087.

IMAP4.shutdown()¶

Close connection established inopen. This method is implicitlycalled byIMAP4.logout(). You may override this method.

IMAP4.socket()¶

Returns socket instance used to connect to server.

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

Thesort command is a variant ofsearch with sorting semantics for theresults. Returned data contains a space separated list of matching messagenumbers.

Sort has two arguments before thesearch_criterion argument(s); aparenthesized list ofsort_criteria, and the searchingcharset. Note thatunlikesearch, the searchingcharset argument is mandatory. There is alsoauidsort command which corresponds tosort the way thatuidsearchcorresponds tosearch. Thesort command first searches the mailbox formessages that match the given searching criteria using the charset argument forthe interpretation of strings in the searching criteria. It then returns thenumbers of matching messages.

This is anIMAP4rev1 extension command.

IMAP4.starttls(ssl_context=None)¶

Send aSTARTTLS command. Thessl_context argument is optionaland should be assl.SSLContext object. This will enableencryption on the IMAP connection. Please readSecurity considerations forbest practices.

在 3.2 版被加入.

在 3.4 版的變更:The method now supports hostname check withssl.SSLContext.check_hostname andServer Name Indication (seessl.HAS_SNI).

IMAP4.status(mailbox,names)¶

Request named status conditions formailbox.

IMAP4.store(message_set,command,flag_list)¶

Alters flag dispositions for messages in mailbox.command is specified bysection 6.4.6 ofRFC 2060 as being one of "FLAGS", "+FLAGS", or "-FLAGS",optionally with a suffix of ".SILENT".

For example, to set the delete flag on all messages:

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

備註

Creating flags containing ']' (for example: "[test]") violatesRFC 3501 (the IMAP protocol). However, imaplib has historicallyallowed creation of such tags, and popular IMAP servers, such as Gmail,accept and produce such flags. There are non-Python programs which alsocreate such tags. Although it is an RFC violation and IMAP clients andservers are supposed to be strict, imaplib still continues to allowsuch tags to be created for backward compatibility reasons, and as ofPython 3.6, handles them if they are sent from the server, since thisimproves real-world compatibility.

IMAP4.subscribe(mailbox)¶

Subscribe to new mailbox.

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

Thethread command is a variant ofsearch with threading semantics forthe results. Returned data contains a space separated list of thread members.

Thread members consist of zero or more messages numbers, delimited by spaces,indicating successive parent and child.

Thread has two arguments before thesearch_criterion argument(s); athreading_algorithm, and the searchingcharset. Note that unlikesearch, the searchingcharset argument is mandatory. There is also auidthread command which corresponds tothread the way thatuidsearch corresponds tosearch. Thethread command first searches themailbox for messages that match the given searching criteria using thecharsetargument for the interpretation of strings in the searching criteria. It thenreturns the matching messages threaded according to the specified threadingalgorithm.

This is anIMAP4rev1 extension command.

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

Execute command args with messages identified by UID, rather than messagenumber. Returns response appropriate to command. At least one argument must besupplied; if none are provided, the server will return an error and an exceptionwill be raised.

IMAP4.unsubscribe(mailbox)¶

Unsubscribe from old mailbox.

IMAP4.unselect()¶

imaplib.IMAP4.unselect() frees server's resources associated with theselected mailbox and returns the server to the authenticatedstate. This command performs the same actions asimaplib.IMAP4.close(), exceptthat no messages are permanently removed from the currentlyselected mailbox.

在 3.9 版被加入.

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

Allow simple extension commands notified by server inCAPABILITY response.

The following attributes are defined on instances ofIMAP4:

IMAP4.PROTOCOL_VERSION¶

The most recent supported protocol in theCAPABILITY response from theserver.

IMAP4.debug¶

Integer value to control debugging output. The initialize value is taken fromthe module variableDebug. Values greater than three trace each command.

IMAP4.utf8_enabled¶

Boolean value that is normallyFalse, but is set toTrue if anenable() command is successfully issued for theUTF8=ACCEPTcapability.

在 3.5 版被加入.

IMAP4 範例¶

Here is a minimal example (without error checking) that opens a mailbox andretrieves and prints all messages:

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