Configure email notifications

Cloud Composer 1 | Cloud Composer 2

This page explains how to configure SMTP services for your Cloud Composer environment.

Before you begin

If your Cloud Composer environment is configured for Private IP, make sure that it has connectivity to the API endpoint for your external email service (such as https://api.sendgrid.com, or your preferred SMTP server).

Configure SendGrid email services

To receive notifications, configure your environment variables to send email through the SendGrid email service.

Sign up with SendGrid

If you haven't already, sign up with SendGrid in Google Cloud console, click Manage On Provider to go to the SendGrid domain, and click Settings to retrieve your username and to create an API key. As a Google Cloud developer, you can start with 12,000 free emails per month.

Go to SendGrid Email API

Configure variables

SendGrid uses the API key and a From email address for sending mail. You can provide this information with one of the following options:

• (Recommended) Store values in Secret Manager.

  Note: This option is available in Airflow 2.1.4 and later versions. In Airflow versions from 2.1.4 to 2.2.3, you still need to use an environment variable to set the email address, but you can store the SendGrid API key in a secret.

• Store values in Airflow.

  Caution: If you use this option, the value for the SendGrid API key is stored in an Airflow connection.

Store values in Secret Manager

To store values in Secret Manager:

1. Install the apache-airflow-providers-sendgrid PyPI package.

2. Configure Secret Manager for your environment. Make sure to set up permissions and Airflow configuration options for the secrets backend.

3. Override the following Airflow configuration options:

   Section	Key	Value
   email	email_conn_id	sendgrid_default
   email	email_backend	airflow.providers.sendgrid.utils.emailer.send_email

4. Create a secret for the SendGrid connection named airflow-connections-sendgrid_default. Set the secret's value to the connection URI. For example:

   sendgrid://<username>:<sendgrid_api_key>@smtp.sendgrid.net:587
   

   For more information about storing connections in Secret Manager, see Manage Airflow connections.

5. Configure the email address for SendGrid:

   • (Airflow 2.2.4 and later versions) It's not possible to set up the email address through a secret. Instead, override the following Airflow configuration option:

     Section	Key	Value
     email	from_email	The From email address, such as [e-mail].

   • (Airflow versions 2.1.4 to 2.1.3) Set the following environment variable for your environment:

     Name	Value
     SENDGRID_MAIL_FROM	The From email address, such as [e-mail].

Store values in Airflow

1. Override the following Airflow configuration options:

   Section	Key	Value
   email	email_conn_id	sendgrid_default
   email	email_backend	airflow.providers.sendgrid.utils.emailer.send_email

2. In Airflow, configure the connection named sendgrid_default. Specify the Sendgrid API key in the connection URI. For example:

   gcloud composer environments run ENVIRONMENT_NAME \
     --location LOCATION \
     connections add -- \
     --conn-uri "sendgrid://USERNAME:[e-mail]:587" \
     sendgrid_default
   

   Replace the following:

   • ENVIRONMENT_NAME: the name of your environment.
   • LOCATION: the region where the environment is located.
   • USERNAME: the SendGrid username.
   • SENDGRID_API_KEY: the SendGrid API key.

3. Configure the email address for SendGrid:

   • (Airflow 2.2.4 and later versions) Override the following Airflow configuration option:

     Section	Key	Value
     email	from_email	The From email address, such as [e-mail].

   • (Airflow versions 2.1.4 to 2.1.3) Set the following environment variable for your environment:

     Name	Value
     SENDGRID_MAIL_FROM	The From email address, such as [e-mail].

Test your SendGrid configuration

To test SendGrid configuration:

1. Create a test DAG that uses the EmailOperator. For example:

import datetime

import airflow
from airflow.operators.email import EmailOperator


with airflow.DAG(
    "composer_sample_sendgrid",
    start_date=datetime.datetime(2022, 1, 1),
) as dag:
    task_email = EmailOperator(
        task_id="send-email",
        conn_id="sendgrid_default",
        # You can specify more than one recipient with a list.
        to="[e-mail]",
        subject="EmailOperator test for SendGrid",
        html_content="This is a test message sent through SendGrid.",
        dag=dag,
    )

1. Upload the DAG to your environment and check that the task succeeds.
2. Sign in to SendGrid in with your SendGrid credentials.
3. In the SendGrid UI, go to Activity page.
4. Search the list for the email. You should see that SendGrid processed and delivered the email.

5. If the email is not processed and delivered:

   • Check your SendGrid configuration.
   • Verify that you enabled the Secret Manager backend. Make sure that you granted extra permissions and set overrides for Airflow configuration options.
   • Check the spam filter in your email client.

Configure third-party SMTP services

To send email through a third-party SMTP service, override the email_backend Airflow configuration option and configure other SMTP-related parameters.

Note: Using a third-party SMTP service requires setting an SMTP password. Cloud Composer does not support configuring the smtp_password because the value is stored in plain text in airflow.cfg and considered non-secure. See Configuring an SMTP password to learn about setting an SMTP password in a more secure way.

To configure a third-party SMTP service, override the following Airflow configuration options:

Section	Key	Value
email	email_backend	airflow.utils.email.send_email_smtp
smtp	smtp_host	The hostname for the SMTP server.
smtp	smtp_user	The username on the SMTP server.
smtp	smtp_port	The port for the SMTP server. Port 25 is not available. You can use other ports, such as standard SMTP ports 465 and 587.
smtp	smtp_password	Setting a password via smtp_password is not supported. To set an SMTP password, follow instructions provided in Configuring an SMTP password.
smtp	smtp_mail_from	The From email address, such as noreply-composer@.
smtp	smtp_starttls	For enhanced security, set to True.
smtp	smtp_ssl	For enhanced security, set to True.

Configure an SMTP password for a third-party SMTP service

Keeping an SMTP password in plain text in Airflow configuration file is a bad security practice. That's why Cloud Composer does not support this method. Instead, you can use two other methods for configuring an SMTP password.

Using a command to retrieve an SMTP password

Note: this method works only for Cloud Composer 2. In the case of Cloud Composer 1, providing password via a command will trigger an error when accessing Admin -> Configuration in Airflow UI.

You can use a configuration override to specify a command that obtains the SMTP password. When communicating with your SMTP service, Airflow uses this command to get the value of the password. Specify a single command, without bash operators such as pipes and redirects.

To use this method, override the following Airflow configuration option:

Section	Key	Value
smtp	smtp_password_cmd	Specify a command that returns the SMTP password.

Using a secret stored in Secret Manager to retrieve an SMTP password

You can configure Secret Manager as your Airflow secrets backend.

Note: If the smtp_ssl Airflow configuration option is set to True for your environment, then disable this override if you get the SSL_WRONG_VERSION_NUMBER error.

Once you configure Secret Manager for your Composer environment, you can store an SMTP password in Secret Manager:

1. Create a new secret:

   echo -n "SMTP_PASSWORD" | gcloud beta secrets create \
     airflow-config-smtp-password \
     --data-file=- \
     --replication-policy=automatic
   

   Replace SMTP_PASSWORD with your SMTP password.

2. Configure Airflow to obtain the SMTP password from Secret Manager. To do so, override the following Airflow configuration option:

   Section	Key	Value
   smtp	smtp_password_secret	smtp-password

What's next

• Override Airflow configuration options
• Set environment variables