Apache Airflow SMTP Provider

2.4.4 · active · verified Sat Apr 11

The `apache-airflow-providers-smtp` package provides the SmtpHook, enabling Apache Airflow to send emails using SMTP. This is essential for features like email notifications in DAGs via the `EmailOperator`. The current version is 2.4.4, with releases typically synchronized with major Airflow releases or as needed for bug fixes and improvements.

Common errors

```
ModuleNotFoundError: No module named 'airflow.providers.smtp'
```
cause The 'apache-airflow-providers-smtp' package is not installed.

fix Install the package using 'pip install apache-airflow-providers-smtp'.
```
ImportError: cannot import name 'SmtpHook' from 'airflow.providers.smtp.hooks.smtp'
```
cause The 'SmtpHook' class is not found in the specified module, possibly due to an incorrect import path or version mismatch.

fix Ensure you are importing 'SmtpHook' correctly: 'from airflow.providers.smtp.hooks.smtp import SmtpHook'.
```
AttributeError: module 'airflow.providers.smtp' has no attribute 'SmtpHook'
```
cause Attempting to import 'SmtpHook' directly from 'airflow.providers.smtp' instead of its submodule.

fix Import 'SmtpHook' from its correct submodule: 'from airflow.providers.smtp.hooks.smtp import SmtpHook'.
```
ImportError: cannot import name 'EmailOperator' from 'airflow.operators.email_operator'
```
cause The 'EmailOperator' has been moved to the 'apache-airflow-providers-smtp' package in newer versions of Airflow.

fix Update your import statement to: 'from airflow.providers.smtp.operators.smtp import EmailOperator'.
```
AirflowException: You should provide 'from_email' or define it in the connection.
```
cause The 'from_email' parameter is not provided, and it's also not defined in the SMTP connection settings.

fix Provide the 'from_email' parameter in your 'EmailOperator' or define it in your SMTP connection settings.

Warnings

gotcha The `EmailOperator` (and other email features) critically depend on a properly configured `smtp_default` connection in Airflow. This connection must be set up in the Airflow UI (Admin -> Connections) or in `airflow.cfg` with the correct host, port, authentication, and TLS/SSL settings. Without it, email tasks will fail with connection errors.
Fix: Configure the 'smtp_default' connection in Airflow with valid SMTP server details. Ensure 'ssl_enable' or 'starttls_enable' are correctly set based on your SMTP server.
gotcha This provider package requires Python >= 3.10. Installing it in environments with older Python versions will lead to installation errors or runtime incompatibilities.
Fix: Ensure your Airflow environment is running on Python 3.10 or newer. Upgrade Python if necessary, or use a virtual environment with the correct Python version.
gotcha While the `EmailOperator` is part of Airflow core, its ability to send emails via SMTP relies entirely on the `apache-airflow-providers-smtp` package being installed. If the provider is missing, `EmailOperator` tasks will typically fail silently or with an error indicating a missing dependency or an inability to find a suitable hook.
Fix: Always ensure the `apache-airflow-providers-smtp` package is installed in your Airflow environment alongside Airflow core. Use `pip install apache-airflow-providers-smtp`.
breaking The `schedule_interval` argument for `DAG` instantiation has been removed in Airflow versions 2.4 and later. Using it will result in a `TypeError`. You must use the `schedule` argument instead.
Fix: Update your DAG definitions to use `schedule=...` instead of `schedule_interval=...`. For example, `schedule=None`, `schedule='@daily'`, or `schedule=timedelta(days=1)`.

Install

pip install apache-airflow-providers-smtp Install SMTP Provider

Imports

SmtpHook
```
from airflow.providers.smtp.hooks.smtp import SmtpHook
```
This hook provides the underlying SMTP client functionality.
EmailOperator
wrong:
```
from airflow.providers.smtp.operators.email import EmailOperator
```
correct:
```
from airflow.operators.email import EmailOperator
```
The EmailOperator is part of Airflow core, not directly provided by this package, but relies on this provider for SMTP functionality.

Quickstart

This quickstart demonstrates a basic Airflow DAG that uses the `EmailOperator` to send an email. The `apache-airflow-providers-smtp` package must be installed, and an 'smtp_default' connection configured in Airflow for this to function correctly. This provider enables the underlying SMTP communication.

from airflow.operators.email import EmailOperator
from airflow.models.dag import DAG
from datetime import datetime

# NOTE: For this DAG to send emails, an 'smtp_default' connection
# must be configured in Airflow (Admin -> Connections) or via airflow.cfg.
# The apache-airflow-providers-smtp package provides the SmtpHook that EmailOperator uses.

with DAG(
    dag_id='simple_email_notification',
    start_date=datetime(2023, 1, 1),
    schedule_interval=None,
    catchup=False,
    tags=['email_example'],
) as dag:
    send_test_email = EmailOperator(
        task_id='send_test_email',
        to='your_recipient@example.com', # Replace with a valid email address
        subject='Airflow Test Email from SMTP Provider',
        html_content='<h3>Hello from Airflow!</h3><p>This email confirms your SMTP provider is working.</p>',
        conn_id='smtp_default', # This connection ID should be configured
    )

view raw JSON →