Package: easy-email-downloader
easy-email-downloader 📨easy-email-downloaderis a no nonsense and easy way to download emails from an IMAP server in Python with no
3rd party dependencies.UsesExtract data/logs etc. from email content for further parsing or saving to disk.Calculate general statistics from your inbox (who's sending me the most etc.)Get a list of all senders so you can identify who to unsubsribe from.Automatically download attachments (receipts/statements etc.) and save to disk.Archive content of emails for personal use.See the installation & examples below.Pull requests/ideas/suggestions are welcome 👍🏻InstallationPyPIpipinstalleasy-email-downloaderFrom SourceUsingPoetry👍🏻 recommendedClone the repository and run:poetryinstallsetuptoolsClone the repository and run in a virtual environment:pythonsetup.pyinstallUsageTo download emails from an IMAP server:fromeasy_email_downloaderimportEmailFilter,EmailConfig,download_emailsemail_config=EmailConfig(host="mail.example.com",email_address="example@example.com",password="somepassword",mailbox="INBOX",port=993,)# The EmailFilter itself and all of its fields are optional. Sensible defaults are chosen if left out.email_filter=EmailFilter(subject="daily report",# subject filtering is server specific - full string matches often won't worksender="someone@gmail.com",messages_to_download=1,# setting this to -1 will download all emailsoldest_first=False,# whether to retrive the oldest emails firstdelete_after_download=False,# be careful setting this to True - emails are permanently removed!)downloaded_emails=download_emails(email_config=email_config,email_filter=email_filter,)fordownloaded_emailindownloaded_emails:print(f"sender:{downloaded_email.sender}")print(f"date:{downloaded_email.date}")print(f"subject:{downloaded_email.subject}")print(f"content_type:{downloaded_email.content_type}")print(f"body:{downloaded_email.body[:50]}")forattachmentindownloaded_email.attachments:print(f"filename:{attachment.filename}")Which produces:sender: Daniel Tomlinson <dtomlinson@panaetius.co.uk>
date: Sat, 23 Apr 2022 20:55:31 +0100
subject: Download me using easy-email-sender
content_type: text/html
body: Successfully downloaded using easy-email-sender!
filename: hello.jpgSee below for more information onEmailFilter,EmailConfig,download_emailsor see the docstrings.EmailConfigCreate yourEmailConfiginstance:If you know the mailbox you want to download from:email_config=EmailConfig(host="mail.example.com",email_address="example@example.com",password="somepassword",mailbox="INBOX",port=993)If you don't know the mailbox to download from, useEmailConfig.list_mailboxesemail_config = EmailConfig(
    host="mail.example.com", email_address="example@example.com", password="somepassword", port=993
)
user_mailboxes = email_config.list_mailboxes()This will return a list of strings of all the mailboxes in the user's account.EmailConfigsupports the following arguments:Attributes:
    host (str): The host of the IMAP server.
    email_address (str): The email address to login as.
    password (str): The password.
    mailbox (str): The mailbox to download emails from.
    port (int): The IMAP port of the server.EmailFilterCreate anEmailFilterinstance:email_filter=EmailFilter(subject="daily report",sender="someone@gmail.com",messages_to_download=1,oldest_first=False,delete_after_download=False,)subjectandsenderare optional. Either both, one or none ofsubjectandsendercan be set. If neither are
provided all emails in the mailbox will be searched for.EmailFiltersupports the following arguments:Attributes:
    subject (str | None, optional): The subject to filter by. Defaults to None.
    sender (str | None, optional): The sender email address to filter by. Defaults to None.
    messages_to_download (int, optional): The number of emails to download. If -1 will download all. Defaults to -1.
    oldest_first (bool, optional): Whether to download emails starting with the oldest first. Defaults to False.
    delete_after_download (bool, optional): Whether to delete the emails after successfully downloading. Defaults to False.🚨 Be careful withdelete_after_download- be sure you want to delete the email before you run it. This callsimaplib.IMAP4_SSL.expungewhichpermanentlydeletes the email from the server.download_emailsDownload emails using theEmailConfigandEmailFilter:downloaded_emails=download_emails(email_config=email_config,email_filter=email_filter,)This returns a list ofEmailobjects.The available attributes on anEmailobject are:Attributes:
    sender (str): The sender in the form `first_name last_name <email_address>`.
    subject (str): The email subject.
    date (str): The date the email was sent.
    body (str): The content of the email. This is either in plaintext or as HTML.
    attachments (List[Optional[Attachment]]): A list of attachments as
        [Attachment][easy_email_downloader.models.Attachment] objects. If no attachments this is an empty list.
    content_type (str): The content type. Either `text/plain` or `text/html`.Attachments are stored asAttachmentobjects containing thefilenameandcontents(in bytes).These can be saved to disk:for attachment in downloaded_emails.attachments:
    with open(f"/some/path/{attachment.filename}", mode="wb") as attachment_contents:
        attachment_contents.write(attachment.contents)TODOExtend attatchment logic to get filename of attatchment on server.✅Useful to save attatchments to disk automatically without the user having to implementfile.open(mode="wb").✅CLI to download emails to json/csv etc.Should include a Dockerfile and an image published to Dockerhub.Tests 🥱.