{"id":1327,"library":"apache-airflow-providers-imap","title":"Apache Airflow IMAP Provider","description":"The Apache Airflow IMAP Provider enables Airflow to interact with IMAP email servers. It provides hooks and operators for tasks such as retrieving email attachments. The current version is 3.11.1 and it follows the release cadence of Apache Airflow providers, which are released regularly to support new Airflow features and address bug fixes.","status":"active","version":"3.11.1","language":"en","source_language":"en","source_url":"https://github.com/apache/airflow/tree/main/airflow/providers/imap","tags":["airflow","provider","imap","email","smtp"],"install":[{"cmd":"pip install apache-airflow-providers-imap","lang":"bash","label":"Install IMAP Provider"}],"dependencies":[{"reason":"This is an Airflow provider package and requires an existing Apache Airflow installation to function.","package":"apache-airflow","optional":false}],"imports":[{"symbol":"IMAPHook","correct":"from airflow.providers.imap.hooks.imap import IMAPHook"},{"symbol":"IMAPRetrieveAttachmentOperator","correct":"from airflow.providers.imap.operators.imap import IMAPRetrieveAttachmentOperator"}],"quickstart":{"code":"import pendulum\nimport os\nfrom airflow.models.dag import DAG\nfrom airflow.providers.imap.operators.imap import IMAPRetrieveAttachmentOperator\nfrom airflow.utils.dates import days_ago\n\n# IMPORTANT: In a real Airflow deployment, you must configure an IMAP connection\n# via the Airflow UI (Admin -> Connections) with a 'Conn Id', e.g., 'imap_default'.\n# This connection should include Host, Port, Login (Username), Password, and\n# potentially Extra parameters (e.g., 'ssl': True) for SSL/TLS if needed.\n\n# For this example, we assume 'imap_default' is configured or will be.\n# Using os.environ.get for sensitivity, though connection details are best in Airflow secrets backend.\nIMAP_CONN_ID = os.environ.get(\"AIRFLOW_IMAP_CONN_ID\", \"imap_default\")\nTARGET_ATTACHMENT_DIRECTORY = os.environ.get(\"AIRFLOW_IMAP_TARGET_DIR\", \"/tmp/airflow_imap_attachments\")\n\nwith DAG(\n    dag_id=\"example_imap_retrieve_attachment\",\n    start_date=days_ago(1),\n    schedule=None,\n    catchup=False,\n    tags=[\"imap\", \"email\", \"provider\"],\n) as dag:\n    # Task to retrieve a specific PDF attachment from an IMAP server\n    retrieve_monthly_report = IMAPRetrieveAttachmentOperator(\n        task_id=\"retrieve_monthly_report_attachment\",\n        imap_conn_id=IMAP_CONN_ID,\n        email_filter={\n            \"FROM\": \"reports@company.com\",\n            \"SUBJECT\": \"Monthly Report\",\n            \"UNSEEN\": True, # Only process unseen emails\n        },\n        attachment_name=\"report_.*\\\\.pdf\", # Use regex to match files like 'report_2023_01.pdf'\n        target_directory=TARGET_ATTACHMENT_DIRECTORY,\n        check_regex=True, # Enable regex matching for attachment_name\n        # delete_after_fetch=True, # Uncomment to delete emails after successful retrieval\n    )\n","lang":"python","description":"This example demonstrates how to use the `IMAPRetrieveAttachmentOperator` to fetch a PDF attachment from an IMAP email server. It assumes an Airflow connection named 'imap_default' is configured with the necessary IMAP server credentials. The operator filters emails by sender, subject, and retrieves only unseen emails matching a regex pattern for the attachment name, saving it to a specified directory."},"warnings":[{"fix":"Verify all IMAP connection parameters in the Airflow UI. Ensure the IMAP server is accessible from Airflow workers and SSL/TLS settings match the server requirements.","message":"Incorrect Airflow IMAP Connection setup: The `imap_conn_id` must refer to a correctly configured Airflow connection (Admin -> Connections). Common errors include wrong host, port, login, password, or misconfigured SSL/TLS settings (often set in the 'Extra' field for 'ssl': true/false).","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure the target directory exists on the Airflow worker's filesystem and has appropriate write permissions. You may need a preceding task to create the directory (`mkdir -p`) if it's not guaranteed to exist.","message":"File system permissions for `target_directory`: The directory specified in `target_directory` for saving attachments must exist and be writable by the Airflow worker process executing the task. Failure to do so will result in permission errors.","severity":"gotcha","affected_versions":"All"},{"fix":"Carefully test your `email_filter` (e.g., FROM, SUBJECT, UNSEEN) and `attachment_name` regex with known test emails. Start with simple filters and gradually increase complexity. Use `check_regex=True` when `attachment_name` is a regex.","message":"Ineffective email filtering or attachment matching: Using overly broad or incorrect `email_filter` parameters or `attachment_name` regex can lead to not finding the desired emails/attachments, or unintended retrieval.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}