core.utils.fetchers.IMAP4Fetcher module

Module with the IMAP4Fetcher class.

class core.utils.fetchers.IMAP4Fetcher.IMAP4Fetcher(account)[source]

Bases: BaseFetcher, SafeIMAPMixin

Maintains a connection to the IMAP server and fetches data using imaplib.

Opens a connection to the IMAP server on construction and is preferably used in a ‘with’ environment. Allows fetching of mails and mailboxes from an account on an IMAP host.

Parameters:

account (Account)

PROTOCOL = 'IMAP'

Name of the used protocol, refers to MailFetchingProtocols.IMAP.

AVAILABLE_FETCHING_CRITERIA: tuple[str, ...] = (EmailFetchingCriterionChoices.ALL, EmailFetchingCriterionChoices.UNSEEN, EmailFetchingCriterionChoices.SEEN, EmailFetchingCriterionChoices.RECENT, EmailFetchingCriterionChoices.NEW, EmailFetchingCriterionChoices.OLD, EmailFetchingCriterionChoices.FLAGGED, EmailFetchingCriterionChoices.UNFLAGGED, EmailFetchingCriterionChoices.DRAFT, EmailFetchingCriterionChoices.UNDRAFT, EmailFetchingCriterionChoices.ANSWERED, EmailFetchingCriterionChoices.UNANSWERED, EmailFetchingCriterionChoices.DELETED, EmailFetchingCriterionChoices.UNDELETED, EmailFetchingCriterionChoices.DAILY, EmailFetchingCriterionChoices.WEEKLY, EmailFetchingCriterionChoices.MONTHLY, EmailFetchingCriterionChoices.ANNUALLY, EmailFetchingCriterionChoices.SENTSINCE, EmailFetchingCriterionChoices.SUBJECT, EmailFetchingCriterionChoices.BODY, EmailFetchingCriterionChoices.FROM, EmailFetchingCriterionChoices.KEYWORD, EmailFetchingCriterionChoices.UNKEYWORD, EmailFetchingCriterionChoices.LARGER, EmailFetchingCriterionChoices.SMALLER)

Tuple of all criteria available for fetching. Refers to MailFetchingCriteria. Must be immutable! IMAP4 does not accept time lookups, only date based. For a list of all existing IMAP criteria see https://datatracker.ietf.org/doc/html/rfc3501.html#section-6.4.4.

EMAIL_FETCH_BATCH_SIZE = 100
__init__(account)[source]

Constructor, starts the IMAP connection and logs into the account.

Parameters:

account (Account) – The model of the account to be fetched from.

Return type:

None

connect_to_host()[source]

Opens the connection to the IMAP server using the credentials from account.

Raises:

MailAccountError – If an error occurs or a bad response is returned.

Return type:

None

test(mailbox=None)[source]

Tests the connection to the mailserver and, if a mailbox is provided, whether it can be opened and listed.

Parameters:

mailbox (Mailbox | None) – The mailbox to be tested. Default is None.

Raises:

  • ValueError – If the mailbox does not belong to self.account.

  • MailAccountError – If the account test fails because an error occurs or a bad response is returned.

  • MailboxError – If the mailbox test fails because an error occurs or a bad response is returned testing the mailbox.

Return type:

None

fetch_emails(mailbox, criterion=<core.utils.FetchingCriterion.FetchingCriterion object>)[source]

Fetches and returns maildata from a mailbox based on a given criterion.

Parameters:

  • mailbox (Mailbox) – Database model of the mailbox to fetch data from.

  • criterion (FetchingCriterion) – Formatted criterion to filter mails in the IMAP request. Defaults to eonvelope.MailFetchingCriteria.ALL.

Yields:

Mails in the mailbox matching the criterion as bytes.

Raises:
Return type:

Generator[bytes]

fetch_mailboxes()[source]

Retrieves and returns the data of the mailboxes in the account.

Todo

Rewrite this into a generator.

Return type:

list[tuple[str, str]]

Returns:

List of data of all mailboxes in the account. Empty if none are found.

Raises:

MailAccountError – If an error occurs or a bad response is returned.

restore(email)[source]

Places an email in its mailbox.

Parameters:

email (Email) – The email to restore.

Raises:

  • ValueError – If the emails mailbox is not in this fetchers account.

  • FileNotFoundError – If the email has no eml file in storage.

  • MailboxError – If uploading the email to the mailserver fails or returns a bad response.

Return type:

None

close()[source]

Logs out of the account and closes the connection to the IMAP server if it is open.

Return type:

None