or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

imap-hooks.mdimap-sensors.mdindex.md
tile.json

tessl/pypi-apache-airflow-providers-imap

Apache Airflow provider package for IMAP email server integration and attachment processing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/apache-airflow-providers-imap@3.9.x

To install, run

npx @tessl/cli install tessl/pypi-apache-airflow-providers-imap@3.9.0

index.mddocs/

Apache Airflow IMAP Provider

Apache Airflow provider package for IMAP (Internet Message Access Protocol) integration, enabling workflows to connect to mail servers, search for emails with specific attachments, and download them for processing within Airflow DAGs.

Package Information

  • Package Name: apache-airflow-providers-imap
  • Language: Python
  • Installation: pip install apache-airflow-providers-imap
  • Airflow Version: Requires Apache Airflow >=2.10.0

Core Imports

Main classes and functionality:

from airflow.providers.imap.hooks.imap import ImapHook
from airflow.providers.imap.sensors.imap_attachment import ImapAttachmentSensor

Package version information:

from airflow.providers.imap import __version__

Basic Usage

from airflow.providers.imap.hooks.imap import ImapHook
from airflow.providers.imap.sensors.imap_attachment import ImapAttachmentSensor
from airflow import DAG
from datetime import datetime

# Using ImapHook to download attachments
def download_email_attachments():
    with ImapHook(imap_conn_id="my_imap_conn") as hook:
        # Check if attachment exists
        has_attachment = hook.has_mail_attachment(
            name="report.csv",
            mail_folder="INBOX"
        )
        
        if has_attachment:
            # Download attachments to local directory
            hook.download_mail_attachments(
                name="report.csv",
                local_output_directory="/tmp/downloads"
            )

# Using ImapAttachmentSensor to wait for attachments
dag = DAG('email_processing', start_date=datetime(2024, 1, 1))

sensor = ImapAttachmentSensor(
    task_id="wait_for_report",
    attachment_name="daily_report.xlsx",
    check_regex=False,
    mail_folder="INBOX",
    conn_id="imap_default",
    dag=dag
)

Architecture

The IMAP provider follows Airflow's standard provider architecture:

  • Hooks: Low-level interfaces for interacting with external systems (IMAP servers)
  • Sensors: Operators that wait for specific conditions (email attachments)
  • Connection Management: Secure connection handling with SSL/TLS support
  • Version Compatibility: Seamless integration across Airflow 2.x and 3.x versions

Capabilities

IMAP Connection and Email Operations

Provides comprehensive IMAP server connectivity with SSL/TLS support, email searching, attachment detection, and secure file downloads with path traversal protection.

class ImapHook:
    def __init__(self, imap_conn_id: str = "imap_default") -> None: ...
    def get_conn(self) -> ImapHook: ...
    def has_mail_attachment(
        self, 
        name: str, 
        *, 
        check_regex: bool = False, 
        mail_folder: str = "INBOX", 
        mail_filter: str = "All"
    ) -> bool: ...
    def retrieve_mail_attachments(
        self,
        name: str,
        *,
        check_regex: bool = False,
        latest_only: bool = False,
        mail_folder: str = "INBOX",
        mail_filter: str = "All",
        not_found_mode: str = "raise",
    ) -> list[tuple]: ...
    def download_mail_attachments(
        self,
        name: str,
        local_output_directory: str,
        *,
        check_regex: bool = False,
        latest_only: bool = False,
        mail_folder: str = "INBOX",
        mail_filter: str = "All",
        not_found_mode: str = "raise",
    ) -> None: ...

IMAP Hooks

Email Attachment Monitoring

Sensor operators that monitor email mailboxes for specific attachments, enabling event-driven workflows triggered by incoming emails.

class ImapAttachmentSensor:
    def __init__(
        self,
        *,
        attachment_name,
        check_regex=False,
        mail_folder="INBOX",
        mail_filter="All",
        conn_id="imap_default",
        **kwargs,
    ) -> None: ...
    def poke(self, context) -> bool: ...

IMAP Sensors

Connection Configuration

The IMAP provider uses Airflow connections with the connection type imap:

  • Host: IMAP server hostname (e.g., imap.gmail.com)
  • Port: Server port (optional, defaults to standard IMAP ports)
  • Login: Username for authentication
  • Password: Password for authentication
  • Extra: JSON configuration for additional options

SSL Configuration

{
  "use_ssl": true,
  "ssl_context": "default"
}
  • use_ssl (bool): Enable SSL/TLS connection (default: true)
  • ssl_context (str): SSL context setting ("default" or "none")

Error Handling

The provider includes comprehensive error handling:

  • AirflowException: Raised when attachments are not found (configurable)
  • RuntimeError: Raised for SSL configuration errors or connection issues
  • Path Security: Automatic protection against directory traversal attacks
  • File Security: Symlink detection and blocking for downloaded files

Error Modes

Attachment operations support configurable error handling:

  • "raise": Raise AirflowException if attachment not found
  • "warn": Log warning message if attachment not found
  • "ignore": Silent operation if attachment not found