apache-airflow-providers-mailer
=================================

.. include:: _autodoc/mailer_provider.inc.rst

This provider already carries its own full Sphinx docs tree in its own
repo, under ``docs/apache-airflow-providers-mailer/``. The narrative
content on this page mirrors that; it isn't a fresh write-up.

Sends email from Airflow tasks via plain SMTP, the Microsoft Graph API, or
SMTP with OAuth2/XOAUTH2 — each backed by its own Airflow connection type so
credentials live in **Connections**, not DAG code or ``airflow.cfg``.

Connection types
-----------------

For a screenshot walkthrough of creating this connection in the Airflow
UI, see :doc:`../connections/mailer`.

.. list-table::
   :header-rows: 1

   * - Connection type
     - Display name
     - Hook
   * - ``smtp`` (Airflow's own built-in type)
     - Plain SMTP
     - Airflow's standard SMTP connection — no extra provider needed
   * - ``mailer_graph``
     - Microsoft Graph Email
     - ``airflow.providers.mailer.hooks.graph.MailerGraphHook`` —
       provisioned automatically on the platform's managed Airflow
       deployments, no manual setup needed
   * - ``mailer_smtp_oauth``
     - SMTP OAuth Email
     - ``airflow.providers.mailer.hooks.smtp_oauth.MailerSmtpOAuthHook``

Operator
--------

``EmailOperator`` (``airflow.providers.mailer.operators.email.EmailOperator``)
   Sends an email as a DAG task. ``subject`` and ``html_content`` are
   Jinja-templated; ``html_content`` also accepts a path to a ``.html``
   file, loaded and templated automatically. ``mailer_conn_id`` selects
   which of the three connection types above to send through (default
   ``smtp_default``). Supports ``to``/``cc``/``bcc`` (str or list),
   ``files`` (attachments), and works like any other operator with
   ``trigger_rule`` for failure-notification tasks.

Usage
-----

.. code-block:: python

   from airflow.providers.mailer.operators.email import EmailOperator

   notify = EmailOperator(
       task_id="notify",
       to=["alice@example.com", "bob@example.com"],
       cc="manager@example.com",
       subject="Pipeline done — {{ ds }}",
       html_content="<p>Run {{ run_id }} completed.</p>",
   )

   on_failure = EmailOperator(
       task_id="on_failure_email",
       to="oncall@example.com",
       subject="[FAILED] ETL pipeline — {{ ds }}",
       html_content="<p>Task {{ task_instance.task_id }} failed on {{ ds }}.</p>",
       trigger_rule="one_failed",
       mailer_conn_id="mailer_graph_default",
   )