email_to_xml/getmail.py

#!/usr/bin/env python3

"""
Developed by Greig McGill of Sense7.

This script is designed to poll an IMAP mailbox when run.
It will find any emails with attachments, marking them as read, and saving
the attachment to the 'attachments' directory for later processing.
It will respect the attachment filetype and extension.
Attachments are output named with the current date-time, and a semi-random
uid designed to crudely prevent namespace collisions. In a VERY high traffic
environment where many files may be created per second, this should be
re-implemented to be more robust.
No file locking is used, however files are written to a temporary directory
first and renamed upon completion, as renaming is an atomic operation at an
OS level.

Attachments will not be created if they have an identical hash to a
previously downloaded attachment. This is designed to prevent scenarios where
the same file has been accidentally sent multiple times. Note that this
identification is done based on file content, and the name of the file is
irrelevant.

Logging is fairly primitive and done to a log file in the same directory as
the script. This could be upgraded to syslog-style logging if required.

This is set up for simple IMAP SSL authentication using TLS with implied
STARTTLS. If manual STARTTLS is required, the MailBox method will need to be
altered to MailBoxTls. If Outlook or Gmail or similar are used, it will be
necessary to implement OAUTH2.

Authentication is configured in a .env file as described below in the code.
"""

# Standard libraries
import os
import sys
import ssl
import json
import hashlib
import logging
import tempfile
from os.path import join, dirname
from datetime import datetime

# Third party libraries
from dotenv import load_dotenv
from imap_tools import MailBox, AND

def setup_logging():
    """Initialize logging configuration."""
    logging.basicConfig(
        level=logging.DEBUG,
        format='%(asctime)s %(levelname)s %(message)s',
        filename='./getmail.log',
        filemode='a')
    logging.debug('%a started in %s', 'getmail.py', os.getcwd())

def load_environment_variables():
    """Load environment variables from .env file."""
    dotenv_path = join(dirname(__file__), ".env")
    try:
        with open(dotenv_path, 'r', encoding='utf-8') as env:
            logging.debug('success opening env file: %a', env)
        load_dotenv(dotenv_path)
    except FileNotFoundError:
        logging.error('config file %a is missing - unable to proceed', dotenv_path)
        sys.exit(1)
    except Exception as e:
        logging.error('An unexpected error occurred: %s', str(e))
        sys.exit(1)

def compute_hash(content):
    """Generate a simple file hash to determine uniqueness."""
    return hashlib.sha256(content).hexdigest()

def load_saved_hashes(hashes_file):
    """Load saved hashes from the file."""
    if os.path.exists(hashes_file):
        with open(hashes_file, 'r', encoding='utf-8') as f:
            return set(json.load(f))
    return set()

def save_hashes(hashes_file, hashes):
    """Save updated hashes to the file."""
    with open(hashes_file, 'w', encoding='utf-8') as f:
        json.dump(list(hashes), f)

def setup_ssl_context():
    """Set up the SSL context."""
    ssl_context = ssl.create_default_context()
    ssl_context.minimum_version = ssl.TLSVersion.TLSv1_3
    ssl_context.maximum_version = ssl.TLSVersion.TLSv1_3
    ssl_context.load_cert_chain(certfile="./one.crt", keyfile="./one.key")
    return ssl_context

def process_attachments(mailbox, attachment_path, saved_hashes):
    """Process and save email attachments."""
    for msg in mailbox.fetch(AND(seen=False), mark_seen=False):
        for att in msg.attachments:
            attachment_hash = compute_hash(att.payload)

            if attachment_hash not in saved_hashes:
                filename, file_ext = os.path.splitext(att.filename)
                logging.debug('found new attachment named %a', filename)
                current_datetime = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
                final_name = (
                    f"{current_datetime}_"
                    f"{attachment_hash[:8]}"
                    f"{file_ext}"
                )

                with tempfile.NamedTemporaryFile(delete=False, dir="temp") as temp_file:
                    temp_file.write(att.payload)
                    temp_path = temp_file.name
                    final_path = os.path.join(attachment_path, final_name)
                    os.rename(temp_path, final_path)  # Atomic move
                    logging.info("Saved attachment as: %s", final_path)
                    saved_hashes.add(attachment_hash)
            else:
                logging.info("Skipped duplicate attachment: %s", att.filename)
        mailbox.flag(msg.uid, '\\Seen', True)

def main():
    """Code entrypoint."""
    setup_logging()
    load_environment_variables()

    hashes_file = 'saved_hashes.json'
    saved_hashes = load_saved_hashes(hashes_file)

    username = os.environ.get("MBOX_USER")
    password = os.environ.get("MBOX_PASS")
    default_folder = os.environ.get("MBOX_FOLDER", "Inbox")
    host = os.environ.get("MAIL_HOST")
    port = os.environ.get("MAIL_PORT")

    if not username or not password:
        logging.error('Missing mailbox username or password in environment')
        sys.exit(1)

    attachment_path = join(dirname(__file__), "attachments")
    if not os.path.exists(attachment_path):
        os.makedirs(attachment_path)

    ssl_context = setup_ssl_context()

    with MailBox(host, port=port, ssl_context=ssl_context).login(
            username, password, default_folder) as mailbox:
        process_attachments(mailbox, attachment_path, saved_hashes)

    save_hashes(hashes_file, saved_hashes)

if __name__ == "__main__":
    main()