Package: dvrd-imap
dvrd_imapObject oriented wrapper for the built-in imaplib.Examplefromdvrd_imapimportIMAPServer,IMAPFilter,IMAPMessagehost='imap.example.domain'port=993username='example@domain.com'password='examplePass123'withIMAPServer(host=host,port=port,username=username,password=password)asimap_server:filters=IMAPFilter(subject='Example subject')messages:list[IMAPMessage]=imap_server.fetch(filters=filters,limit=10)IMAPServerInstantiate this object to connect to the IMAP server and use the server for further actions. It is recommended to
useIMAPServeras a context manager to ensure the connection is closed properly.PropertiesPropTypeRequiredDescriptionhoststryesIMAP server hostportintyesIMAP server portusernamestryesUsed to login to the IMAP serverpasswordstryesUsed to login to the IMAP serversslboolnoIf True (default), uses IMAP4_SSL. If False, uses IMAP4read_onlyboolnoIf True, operate in readonly mode.  Mails are not marked as 'seen' in readonly mode.  Defaults to False.mailboxstrnoInitial mailbox to connect to, defaults to 'INBOX'default_message_partsstrnoParts of the email that are retrieved. Defaults to ('UID RFC822')auto_connectboolnoIf False, IMAPServer does not automatically login. For further actions, the 'connect()' function must be called to establish a connection.FunctionsFunctionParametersReturnsDescriptionconnectmailbox: str (optional)IMAPServerLogin to the IMAPServer and connect to the specified mailbox (default 'INBOX'). Use this function only with propertyauto_connect=False.select_mailboxmailbox: strread_only: bool (optional)IMAPServerConnect to the specified mailbox.  Use theread_onlyparameter to optionally override the class' default.fetch_uidslimit: int (optional)filters: str | IMAPFilter (optional)list[bytes]Fetches UID's from the server using the specified filters. Returns up tolimitUID's. Iffiltersis None, uses filter(ALL).fetchlimit: int (optional)filters: str | IMAPFilter (optional)include_raw_message: bool (optional)message_parts: str (optional)list[IMAPMessage]Fetches the specified message parts (see thedefault_message_partsprop) of up tolimitmails that match the specified filters. Useinclude_raw_message=Trueto include the original IMAP data in the returned objects.fetch_mailuid: bytesinclude_raw_message: bool (optional)message_parts: str (optional)IMAPMessageFetch a specific email from the server. Raises an IMAPException if the email does not exist.close--Closes the IMAP connection.IMAPMessageTheIMAPMessageclass is used to wrap the actual IMAP message's data. It gives easy access to header values,
attachments, and content. If the parameterinclude_raw_messagein any of the server methods isTrue, the original (
raw) data can be accessed using the propertyraw_content.FilteringFiltering can be done by usingIMAPFilterobjects. Multiple filter objects can be combined using the logical
'and' / 'or' (&/|) operators. See the table below for all possible filter fields. Using theIMAPFilterobject is
recommended, but not required. It is also possible to filter using a custom string.The generated IMAP filter can be inspected / debugged by using thebuild()function ofIMAPFilter. This is also
internally used by theIMAPServerto construct the filter string.Examplesfromdvrd_imapimportIMAPFilter# Get mails received on a specific date, specifying the date as ISO stringimap_filter=IMAPFilter(on_date='2024-02-15')# (ON "15-Feb-2024)# Get mails filtered on sender and send date, specifying the date as `date` objectfromdatetimeimportdateimap_filter=IMAPFilter(from_addr='exampe@domain.com',date_after=date.fromisoformat('2024-02-10'))# (FROM "exampe@domain.com" SINCE "10-Feb-2024")# Get mails from a list of sendersimap_filter=IMAPFilter(from_addr=['example1@domain.com','example2@domain2.com'])# ((OR FROM "example1@domain.com" FROM "example2@domain2.com"))# Get mails sent from a specific domainimap_filter=IMAPFilter(from_addr='domain.com')# (FROM "domain.com")# Combine filters, generates an OR constructimap_filter=IMAPFilter(from_addr='example@domain.com',date_after='2024-02-01')|IMAPFilter(from_addr='example@domain2.com',date_before='2024-02-01')# OR (FROM "example@domain.com" SINCE "01-Feb-2024") (FROM "example@domain2.com" BEFORE "01-Feb-2024")Filter fieldsAll filter fields are optional.FieldTypeDescriptionfrom_addrstr | list[str]Mails sent by given sender(s)not_from_addrstr | list[str]Mails not sent by given sender(s)subjectstrnot_subjectstrto_addrstr | list[str]Recipient(s)no_to_addrstr | list[str]date_beforestr | dateMails sent before given date, string must be in ISO formatdate_afterstr | dateMails sent after given date, string must be in ISO formaton_datestr | dateMails sent on given date, string must be in ISO formatbodystrSearch content of mailnot_bodystrccstr | list[str]Mails sent to CC address(es)not_ccstr | list[str]Mails not sent to CC address(es)bccstr | list[str]Mails sent to BCC address(es)not_bccstr | list[str]Mails not sent to BCC address(es)