Apache Airflow 邮件发送配置与可插拔 Email Backend 完整指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 内置了基于 SMTP 的邮件通知能力用于发送任务成功、失败、重试等回调邮件。本文以 Airflow 官方文档中关于 Email Configuration 与 Email backends 的说明为主体结合当前仓库的源码实现系统讲解如何在airflow.cfg中配置邮件发送、如何定制邮件主题与正文模板、如何通过email_backend切换到第三方邮件服务如 SendGrid的 API 发送方式以及底层实现原理。1. 邮件配置的核心机制可插拔的email_backendAirflow 发送邮件例如任务成功、失败、重试回调通知时并不强制依赖默认的 SMTP 实现而是通过一个可插拔的email_backend配置项进行分发。这意味着你可以保持 Airflow 的核心调用逻辑不变仅替换底层发送通道——既可以是自带的 SMTP 实现也可以换成由社区 Provider 提供的、走第三方服务 API 的邮件后端。从源码看核心分发逻辑位于 airflow-core/src/airflow/utils/email.py 的send_email()函数backend conf.getimport(email, EMAIL_BACKEND) backend_conn_id conn_id or conf.get(email, EMAIL_CONN_ID) from_email conf.get(email, from_email, fallbackNone) to_list get_email_address_list(to) to_comma_separated , .join(to_list) return backend( to_comma_separated, subject, html_content, filesfiles, dryrundryrun, cccc, bccbcc, mime_subtypemime_subtype, mime_charsetmime_charset, conn_idbackend_conn_id, from_emailfrom_email, custom_headerscustom_headers, **kwargs, )send_email()会从配置中动态导入EMAIL_BACKEND指向的可调用对象通常是一个send_email函数统一向其传递收件人、主题、HTML 正文、附件、抄送、密送、连接 ID 等参数。因此任何一个 Provider 只要提供符合该签名的send_email函数就能无缝接入 Airflow 的邮件通知体系。2. 在airflow.cfg中配置邮件2.1 指定后端与模板文件邮件相关配置全部位于airflow.cfg的[email]段。你可以通过subject_template和html_content_template分别指定邮件主题与 HTML 正文的 Jinja2 模板文件[email] email_backend airflow.utils.email.send_email_smtp subject_template /path/to/my_subject_template_file html_content_template /path/to/my_html_content_template_file对应的环境变量写法为AIRFLOW__EMAIL__EMAIL_BACKENDairflow.utils.email.send_email_smtp AIRFLOW__EMAIL__SUBJECT_TEMPLATE/path/to/my_subject_template_file AIRFLOW__EMAIL__HTML_CONTENT_TEMPLATE/path/to/my_html_content_template_file2.2 配置发件人地址通过from_email设置发件人既可以是裸邮箱地址也可以是带显示名的完整格式[email] from_email John Doe johndoeexample.com环境变量写法AIRFLOW__EMAIL__FROM_EMAILJohn Doe johndoeexample.com从 config.yml 中[email]段的定义可以看到该段还包含email_conn_id默认smtp_default2.1.0 起可用、default_email_on_retry默认True2.0.0 起可用与default_email_on_failure默认True2.0.0 起可用等选项其中subject_template与html_content_template自 2.0.1 起可用from_email自 2.2.4 起可用其注释明确说明该值可以是裸邮箱也可以是Sender Name senderemail.com格式的完整地址。2.3 默认后端与 SMTP 配置默认情况下email_backend指向airflow.utils.email.send_email_smtp即通过 SMTP 协议发送邮件。SMTP 的具体参数在标准配置的[smtp]段中设置完整定义见 config.yml配置项类型默认值说明smtp_hoststringlocalhostSMTP 服务器地址smtp_starttlsbooleanTrue连接 SMTP 服务器时是否使用 STARTTLS 命令smtp_sslbooleanFalse是否使用 SSL 连接smtp_portinteger25连接 SMTP 服务器的端口smtp_mail_fromstringairflowexample.com发送邮件通知时使用的默认发件地址smtp_timeoutinteger30等待 SMTP 服务器建立连接的最大秒数2.0.0 起可用smtp_retry_limitinteger5首次尝试之后连接 SMTP 服务器的重试次数2.0.0 起可用2.4 通过 Connection 存放 SMTP 凭据如果你不希望把 SMTP 的用户名/密码明文存放在配置文件或环境变量中可以创建一个名为smtp_default、类型为Email的 Connection也可以使用自定义名称并在配置中通过email_conn_id指定将 SMTP 用户名与密码存入其中。需要说明的是连接可以是任意类型例如 HTTP 连接主机、端口等其余 SMTP 参数始终只从配置中读取凭据缺失时Airflow 会以无认证方式登录见 airflow-core/src/airflow/utils/email.py 中对 Connection 的解析逻辑。3. 检查当前生效的邮件后端你可以使用airflow config get-value命令快速确认当前实际生效的邮件后端$ airflow config get-value email email_backend airflow.utils.email.send_email_smtp当输出为airflow.utils.email.send_email_smtp时表示当前走的是内置 SMTP 后端若已切换到某个 Provider 提供的后端则会输出对应的模块路径。4. 使用 Jinja2 模板定制邮件内容在模板文件中你可以利用 Jinja2 模板语法访问任务TaskInstance的上下文信息。例如html_content_template文件可以写成Try {{try_number}} out of {{max_tries 1}}br Exception:br{{exception_html}}br Log: a href{{ti.log_url}}Link/abr Host: {{ti.hostname}}br Mark success: a href{{ti.mark_success_url}}Link/abr其中{{try_number}}、{{max_tries 1}}分别表示当前重试次数与总重试次数{{exception_html}}为异常堆栈的 HTML 形式{{ti.log_url}}为任务日志链接{{ti.hostname}}为执行任务的 Worker 主机名{{ti.mark_success_url}}为将任务标记为成功的快捷链接。关于配置的更多信息可参考 Set Configuration。5. 使用社区 Provider 提供的替代邮件后端除了 SMTP你还可以将email_backend指向社区 Provider 提供的实现通过第三方服务的 API 发送邮件例如 SendGrid。整体步骤如下安装对应的 Provider 发行包将email_backend设置为该 Provider 的send_email函数的点分路径将email_conn_id设置为保存其所需凭据的 Connection。社区管理 Provider 提供的邮件后端清单见 email-backends.rst该页面由文档构建时自动汇总生成。5.1 实例SendGrid 邮件后端以 SendGrid 为例其send_email实现位于 providers/sendgrid/src/airflow/providers/sendgrid/utils/emailer.py可通过如下配置启用[email] email_backend airflow.providers.sendgrid.utils.emailer.send_email email_conn_id sendgrid_default配置要点与源码实现一一对应凭据来源_post_sendgrid_mail()通过BaseHook.get_connection(conn_id)获取连接并将conn.password作为 SendGrid API Key见 emailer.py发件人优先取from_email参数否则回退到环境变量SENDGRID_MAIL_FROM发件人显示名取from_name参数或SENDGRID_MAIL_SENDER环境变量收件人/抄送/密送统一通过get_email_address_list()归一化为地址列表后逐条添加沙箱模式sandbox_modeTrue时启用 SendGrid 的 SandBoxMode测试环境不真正投递自定义参数与分类支持personalization_custom_args自定义参数和categories邮件分类附件将files列表中的文件 base64 编码后作为附件添加文件类型由mimetypes.guess_type()推断发送结果以 2xx 状态码判断是否成功失败时记录status_code日志。5.2 实例SMTP Provider 的 Hook 实现除了核心模块中的 SMTP 发送函数smtpProvider 在 providers/smtp/src/airflow/providers/smtp/hooks/smtp.py 中提供了功能更丰富的send_email_smtp()方法支持dryrunTrue时只构建消息、不真正发送便于联调mime_subtype默认mixed与mime_charset默认utf-8控制 MIME 消息构造custom_headers注入自定义邮件头依据smtp_retry_limit进行发送重试异步版本asend_email_smtp()用于异步场景见同一文件 L447 起。6. 底层原理邮件发送链路剖析结合源码可以完整还原一次邮件通知的调用链触发任务执行器在重试、失败等回调场景中调用airflow.utils.email.send_email()分发send_email()通过conf.getimport(email, EMAIL_BACKEND)动态导入并调用配置指定的后端函数见 airflow-core/src/airflow/utils/email.py构建 MIME 消息默认 SMTP 后端调用build_mime_message()构造MIMEMultipart消息——设置 Subject、From、To、CC、BCC、Date 头附加 HTML 正文、附件与自定义头见 email.py发送send_mime_email()从[smtp]配置段读取主机、端口、STARTTLS、SSL、超时与重试次数从 Connection 读取用户名/密码按需starttls()、login()后调用smtp_conn.sendmail()投递见 email.py替代通道若配置为 SendGrid 等 Provider 后端则跳过 SMTP改为调用第三方服务 API见第 5.1 节。这套统一入口 可插拔后端的设计使得邮件通道的替换对上层通知逻辑完全透明是 Airflow 邮件功能扩展与第三方服务接入的核心机制。7. 关键文件索引邮件配置官方文档airflow-core/docs/howto/email-config.rst邮件后端汇总页providers-summary-docs/core-extensions/email-backends.rst核心邮件发送实现airflow-core/src/airflow/utils/email.py[email]与[smtp]配置定义airflow-core/src/airflow/config_templates/config.ymlSendGrid 后端实现providers/sendgrid/src/airflow/providers/sendgrid/utils/emailer.pySMTP Provider Hookproviders/smtp/src/airflow/providers/smtp/hooks/smtp.py【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache Airflow 邮件发送配置与可插拔 Email Backend 完整指南
Apache Airflow 邮件发送配置与可插拔 Email Backend 完整指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 内置了基于 SMTP 的邮件通知能力用于发送任务成功、失败、重试等回调邮件。本文以 Airflow 官方文档中关于 Email Configuration 与 Email backends 的说明为主体结合当前仓库的源码实现系统讲解如何在airflow.cfg中配置邮件发送、如何定制邮件主题与正文模板、如何通过email_backend切换到第三方邮件服务如 SendGrid的 API 发送方式以及底层实现原理。1. 邮件配置的核心机制可插拔的email_backendAirflow 发送邮件例如任务成功、失败、重试回调通知时并不强制依赖默认的 SMTP 实现而是通过一个可插拔的email_backend配置项进行分发。这意味着你可以保持 Airflow 的核心调用逻辑不变仅替换底层发送通道——既可以是自带的 SMTP 实现也可以换成由社区 Provider 提供的、走第三方服务 API 的邮件后端。从源码看核心分发逻辑位于 airflow-core/src/airflow/utils/email.py 的send_email()函数backend conf.getimport(email, EMAIL_BACKEND) backend_conn_id conn_id or conf.get(email, EMAIL_CONN_ID) from_email conf.get(email, from_email, fallbackNone) to_list get_email_address_list(to) to_comma_separated , .join(to_list) return backend( to_comma_separated, subject, html_content, filesfiles, dryrundryrun, cccc, bccbcc, mime_subtypemime_subtype, mime_charsetmime_charset, conn_idbackend_conn_id, from_emailfrom_email, custom_headerscustom_headers, **kwargs, )send_email()会从配置中动态导入EMAIL_BACKEND指向的可调用对象通常是一个send_email函数统一向其传递收件人、主题、HTML 正文、附件、抄送、密送、连接 ID 等参数。因此任何一个 Provider 只要提供符合该签名的send_email函数就能无缝接入 Airflow 的邮件通知体系。2. 在airflow.cfg中配置邮件2.1 指定后端与模板文件邮件相关配置全部位于airflow.cfg的[email]段。你可以通过subject_template和html_content_template分别指定邮件主题与 HTML 正文的 Jinja2 模板文件[email] email_backend airflow.utils.email.send_email_smtp subject_template /path/to/my_subject_template_file html_content_template /path/to/my_html_content_template_file对应的环境变量写法为AIRFLOW__EMAIL__EMAIL_BACKENDairflow.utils.email.send_email_smtp AIRFLOW__EMAIL__SUBJECT_TEMPLATE/path/to/my_subject_template_file AIRFLOW__EMAIL__HTML_CONTENT_TEMPLATE/path/to/my_html_content_template_file2.2 配置发件人地址通过from_email设置发件人既可以是裸邮箱地址也可以是带显示名的完整格式[email] from_email John Doe johndoeexample.com环境变量写法AIRFLOW__EMAIL__FROM_EMAILJohn Doe johndoeexample.com从 config.yml 中[email]段的定义可以看到该段还包含email_conn_id默认smtp_default2.1.0 起可用、default_email_on_retry默认True2.0.0 起可用与default_email_on_failure默认True2.0.0 起可用等选项其中subject_template与html_content_template自 2.0.1 起可用from_email自 2.2.4 起可用其注释明确说明该值可以是裸邮箱也可以是Sender Name senderemail.com格式的完整地址。2.3 默认后端与 SMTP 配置默认情况下email_backend指向airflow.utils.email.send_email_smtp即通过 SMTP 协议发送邮件。SMTP 的具体参数在标准配置的[smtp]段中设置完整定义见 config.yml配置项类型默认值说明smtp_hoststringlocalhostSMTP 服务器地址smtp_starttlsbooleanTrue连接 SMTP 服务器时是否使用 STARTTLS 命令smtp_sslbooleanFalse是否使用 SSL 连接smtp_portinteger25连接 SMTP 服务器的端口smtp_mail_fromstringairflowexample.com发送邮件通知时使用的默认发件地址smtp_timeoutinteger30等待 SMTP 服务器建立连接的最大秒数2.0.0 起可用smtp_retry_limitinteger5首次尝试之后连接 SMTP 服务器的重试次数2.0.0 起可用2.4 通过 Connection 存放 SMTP 凭据如果你不希望把 SMTP 的用户名/密码明文存放在配置文件或环境变量中可以创建一个名为smtp_default、类型为Email的 Connection也可以使用自定义名称并在配置中通过email_conn_id指定将 SMTP 用户名与密码存入其中。需要说明的是连接可以是任意类型例如 HTTP 连接主机、端口等其余 SMTP 参数始终只从配置中读取凭据缺失时Airflow 会以无认证方式登录见 airflow-core/src/airflow/utils/email.py 中对 Connection 的解析逻辑。3. 检查当前生效的邮件后端你可以使用airflow config get-value命令快速确认当前实际生效的邮件后端$ airflow config get-value email email_backend airflow.utils.email.send_email_smtp当输出为airflow.utils.email.send_email_smtp时表示当前走的是内置 SMTP 后端若已切换到某个 Provider 提供的后端则会输出对应的模块路径。4. 使用 Jinja2 模板定制邮件内容在模板文件中你可以利用 Jinja2 模板语法访问任务TaskInstance的上下文信息。例如html_content_template文件可以写成Try {{try_number}} out of {{max_tries 1}}br Exception:br{{exception_html}}br Log: a href{{ti.log_url}}Link/abr Host: {{ti.hostname}}br Mark success: a href{{ti.mark_success_url}}Link/abr其中{{try_number}}、{{max_tries 1}}分别表示当前重试次数与总重试次数{{exception_html}}为异常堆栈的 HTML 形式{{ti.log_url}}为任务日志链接{{ti.hostname}}为执行任务的 Worker 主机名{{ti.mark_success_url}}为将任务标记为成功的快捷链接。关于配置的更多信息可参考 Set Configuration。5. 使用社区 Provider 提供的替代邮件后端除了 SMTP你还可以将email_backend指向社区 Provider 提供的实现通过第三方服务的 API 发送邮件例如 SendGrid。整体步骤如下安装对应的 Provider 发行包将email_backend设置为该 Provider 的send_email函数的点分路径将email_conn_id设置为保存其所需凭据的 Connection。社区管理 Provider 提供的邮件后端清单见 email-backends.rst该页面由文档构建时自动汇总生成。5.1 实例SendGrid 邮件后端以 SendGrid 为例其send_email实现位于 providers/sendgrid/src/airflow/providers/sendgrid/utils/emailer.py可通过如下配置启用[email] email_backend airflow.providers.sendgrid.utils.emailer.send_email email_conn_id sendgrid_default配置要点与源码实现一一对应凭据来源_post_sendgrid_mail()通过BaseHook.get_connection(conn_id)获取连接并将conn.password作为 SendGrid API Key见 emailer.py发件人优先取from_email参数否则回退到环境变量SENDGRID_MAIL_FROM发件人显示名取from_name参数或SENDGRID_MAIL_SENDER环境变量收件人/抄送/密送统一通过get_email_address_list()归一化为地址列表后逐条添加沙箱模式sandbox_modeTrue时启用 SendGrid 的 SandBoxMode测试环境不真正投递自定义参数与分类支持personalization_custom_args自定义参数和categories邮件分类附件将files列表中的文件 base64 编码后作为附件添加文件类型由mimetypes.guess_type()推断发送结果以 2xx 状态码判断是否成功失败时记录status_code日志。5.2 实例SMTP Provider 的 Hook 实现除了核心模块中的 SMTP 发送函数smtpProvider 在 providers/smtp/src/airflow/providers/smtp/hooks/smtp.py 中提供了功能更丰富的send_email_smtp()方法支持dryrunTrue时只构建消息、不真正发送便于联调mime_subtype默认mixed与mime_charset默认utf-8控制 MIME 消息构造custom_headers注入自定义邮件头依据smtp_retry_limit进行发送重试异步版本asend_email_smtp()用于异步场景见同一文件 L447 起。6. 底层原理邮件发送链路剖析结合源码可以完整还原一次邮件通知的调用链触发任务执行器在重试、失败等回调场景中调用airflow.utils.email.send_email()分发send_email()通过conf.getimport(email, EMAIL_BACKEND)动态导入并调用配置指定的后端函数见 airflow-core/src/airflow/utils/email.py构建 MIME 消息默认 SMTP 后端调用build_mime_message()构造MIMEMultipart消息——设置 Subject、From、To、CC、BCC、Date 头附加 HTML 正文、附件与自定义头见 email.py发送send_mime_email()从[smtp]配置段读取主机、端口、STARTTLS、SSL、超时与重试次数从 Connection 读取用户名/密码按需starttls()、login()后调用smtp_conn.sendmail()投递见 email.py替代通道若配置为 SendGrid 等 Provider 后端则跳过 SMTP改为调用第三方服务 API见第 5.1 节。这套统一入口 可插拔后端的设计使得邮件通道的替换对上层通知逻辑完全透明是 Airflow 邮件功能扩展与第三方服务接入的核心机制。7. 关键文件索引邮件配置官方文档airflow-core/docs/howto/email-config.rst邮件后端汇总页providers-summary-docs/core-extensions/email-backends.rst核心邮件发送实现airflow-core/src/airflow/utils/email.py[email]与[smtp]配置定义airflow-core/src/airflow/config_templates/config.ymlSendGrid 后端实现providers/sendgrid/src/airflow/providers/sendgrid/utils/emailer.pySMTP Provider Hookproviders/smtp/src/airflow/providers/smtp/hooks/smtp.py【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
