Em 15 de setembro de 2026, todos os ambientes do Cloud Composer 1 e da versão 2.0.x do Cloud Composer 2 vão atingir o fim da vida útil planejado e não poderão mais ser usados. Recomendamos planejar a migração para o Cloud Composer 3.
Nesta página, você aprenderá a configurar serviços SMTP no ambiente do Cloud Composer.
Antes de começar
Se o ambiente do Cloud Composer estiver configurado para IP privado, verifique se ele tem conectividade com o endpoint de API do seu serviço de e-mail externo, como https://api.sendgrid.com ou o servidor SMTP de sua preferência.
Os componentes do Airflow em ambientes de IP público estabelecem conexões de saída, incluindo o envio de mensagens de e-mail, de endereços IP públicos e portas alocados automaticamente. Se você quiser que os ambientes de IP público enviem e-mails
de endereços IP e portas predeterminados, conecte uma rede VPC ao ambiente e
mude para IP particular. Para mais
informações sobre rede no Cloud Composer 3, consulte
Mudar o tipo de rede do ambiente.
Se você configurar um back-end de e-mail personalizado diferente, essa configuração não será propagada para o programador. Como resultado, o envio de e-mails diretamente do
programador faria com que ele não respondesse e falhasse repetidamente.
Os workers do Airflow e os processadores de DAGs são compatíveis com outros back-ends personalizados. Assim, você pode enviar e-mails desses componentes. Um caso comum em que o e-mail é enviado
diretamente do programador são os alertas por e-mail sobre falhas de DAG. Como alternativa, você pode enviar alertas de falha do DAG por um callback registrado. Eles serão
enviados pelo processador de DAG. Também é possível usar outros back-ends personalizados com operadores do Airflow que enviam e-mails. Nesse caso, o e-mail será enviado de um worker do Airflow que processa a tarefa.
Configurar serviços de e-mail SendGrid
Para receber notificações, configure as variáveis de ambiente para enviar e-mails por meio do serviço SendGrid.
Inscrever-se no SendGrid
Se ainda não tiver feito isso, inscreva-se com o SendGrid no console Google Cloud , clique em
"Gerenciar no provedor" para acessar o domínio do SendGrid e clique em "Configurações" para recuperar
seu nome de usuário e criar uma chave de API. Como desenvolvedor do Google Cloud , você pode começar com 12.000 e-mails gratuitos por mês.
Configure o endereço de e-mail do SendGrid. Não é possível configurar o endereço de e-mail usando um secret. Em vez disso, substitua a seguinte opção de configuração do Airflow:
Seção
Chave
Valor
email
from_email
O endereço de e-mail "De", como noreply@example.com.
Armazenar valores no Airflow
Substitua as seguintes opções de configuração do Airflow:
LOCATION: a região em que o ambiente está localizado.
USERNAME: o nome de usuário do SendGrid.
SENDGRID_API_KEY: a chave de API do SendGrid.
Configure o endereço de e-mail do SendGrid. Não é possível configurar o endereço de e-mail usando um secret. Em vez disso, substitua a seguinte opção de configuração do Airflow:
Seção
Chave
Valor
email
from_email
O endereço de e-mail "De", como noreply@example.com.
Testar a configuração do SendGrid
Para testar a configuração do SendGrid:
crie um DAG de teste que use EmailOperator; Exemplo:
importdatetimeimportairflowfromairflow.operators.emailimportEmailOperatorwithairflow.DAG("composer_sample_sendgrid",start_date=datetime.datetime(2022,1,1),)asdag:task_email=EmailOperator(task_id="send-email",conn_id="sendgrid_default",# You can specify more than one recipient with a list.to="user@example.com",subject="EmailOperator test for SendGrid",html_content="This is a test message sent through SendGrid.",dag=dag,)
faça login no SendGrid com as respectivas credenciais;
na IU do SendGrid, acesse a página "Activity";
procure o e-mail na lista. Você vai ver que o SendGrid processou
e entregou o e-mail.
se o e-mail não tiver sido processado e entregue:
Verifique a configuração do SendGrid.
Verifique se você ativou o back-end do Secret Manager. Confira se você concedeu permissões extras e definiu substituições para as opções de configuração do Airflow.
verifique o filtro de spam no seu cliente de e-mail.
Configurar serviços SMTP de terceiros
Para enviar e-mails por meio de um serviço SMTP de terceiros,
substitua a opção de configuração email_backend do Airflow
e configure outros parâmetros relacionados a SMTP.
Para configurar um serviço SMTP de terceiros, substitua as seguintes opções de configuração do Airflow:
Seção
Chave
Valor
email
email_backend
airflow.utils.email.send_email_smtp
smtp
smtp_host
O nome do host do servidor SMTP.
smtp
smtp_user
O nome de usuário no servidor SMTP.
smtp
smtp_port
A porta do servidor SMTP. A porta 25 não está disponível. É possível usar outras portas, como as portas SMTP padrão 465 e 587.
smtp
smtp_password
Não é possível definir uma senha por smtp_password. Para definir uma senha SMTP, siga as instruções em Como configurar uma senha SMTP.
smtp
smtp_mail_from
O endereço de e-mail "De", como noreply-composer@.
smtp
smtp_starttls
Para mais segurança, defina como True.
smtp
smtp_ssl
Para mais segurança, defina como True.
Configurar uma senha SMTP para um serviço SMTP de terceiros
Manter uma senha SMTP em texto simples no arquivo de configuração do Airflow é uma prática de segurança ineficiente. É por isso que o Cloud Composer não é compatível com esse método. Em vez disso, é possível usar dois outros métodos para configurar uma senha SMTP.
Usar um comando para recuperar a senha SMTP
É possível usar uma substituição de configuração para especificar um comando que recebe a senha SMTP. Ao se comunicar com o serviço SMTP, o Airflow usa esse comando para receber o valor da senha. Especifique um único comando, sem
operadores bash, como pipes e redirecionamentos.
Para usar esse método, substitua a seguinte opção de configuração do
Airflow:
Seção
Chave
Valor
smtp
smtp_password_cmd
Especifique um comando que retorne a senha SMTP.
Como usar um secret armazenado no Gerenciador de secrets para recuperar uma senha SMTP
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-26 UTC."],[[["\u003cp\u003eThis guide provides instructions on configuring SMTP services for Cloud Composer 3 environments, including using SendGrid and third-party SMTP services.\u003c/p\u003e\n"],["\u003cp\u003eFor SendGrid, users can configure email sending by storing the API key and connection details either in Secret Manager, which is recommended, or directly within Airflow, though the latter is less secure.\u003c/p\u003e\n"],["\u003cp\u003ePublic IP environments can send emails from predetermined IP addresses by connecting a VPC network and switching to Private IP.\u003c/p\u003e\n"],["\u003cp\u003eThird-party SMTP services require overriding specific Airflow configuration options, and Cloud Composer supports retrieving the SMTP password securely through either a command or from Secret Manager.\u003c/p\u003e\n"],["\u003cp\u003eTesting the configuration can be done by creating a DAG that utilizes the EmailOperator, and checking if it was successful, along with checking the activity page on the specified email server.\u003c/p\u003e\n"]]],[],null,["# Configure email notifications\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\n**Cloud Composer 3** \\| [Cloud Composer 2](/composer/docs/composer-2/configure-email \"View this page for Cloud Composer 2\") \\| [Cloud Composer 1](/composer/docs/composer-1/configure-email \"View this page for Cloud Composer 1\")\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis page explains how to configure SMTP services for your\nCloud Composer environment.\n\nBefore you begin\n----------------\n\n- If your Cloud Composer environment is\n [configured for Private IP](/composer/docs/composer-3/configure-private-ip), make sure that it has\n connectivity to the API endpoint for your external email service (such as\n `https://api.sendgrid.com`, or your preferred SMTP server).\n\n- Airflow components in Public IP environments establish outbound connections,\n including sending email messages, from automatically allocated public IP\n addresses and ports. If you want your Public IP environments to send email\n from predetermined IP addresses and ports, you can do so through\n [connecting a VPC network](/composer/docs/composer-3/connect-vpc-network) to your environment and\n [switching it to Private IP](/composer/docs/composer-3/change-networking-type#about-networking-type). For more\n information about networking in Cloud Composer 3, see\n [Change environment networking type](/composer/docs/composer-3/change-networking-type#about-networking-type).\n\n- The Airflow scheduler in Cloud Composer 3 supports only the following\n [custom email backends](#third-party):\n\n - airflow.providers.sendgrid.utils.emailer.send_email\n - airflow.utils.email.send_email_smtp\n\n If you configure a different custom email backend, this configuration won't\n be propagated to the scheduler. As a result, sending email directly from the\n scheduler would lead to the scheduler becoming unresponsive and repeatedly\n failing.\n\n Airflow workers and DAG processors support other custom backends, so you\n can send email from these components. One common case when email is sent\n directly from the scheduler is email alerts about DAG failures. As a\n workaround, you can send DAG failure alerts\n [through a registered callback](https://airflow.apache.org/docs/apache-airflow/stable/administration-and-deployment/logging-monitoring/callbacks.html) instead. They will be\n sent from the DAG processor. You can also use other custom backends with\n Airflow operators that send email. In this case, email will be sent from\n an Airflow worker that processes the task.\n\nConfigure SendGrid email services\n---------------------------------\n\nTo receive notifications, configure your environment variables\nto send email through the SendGrid email service.\n\n### Sign up with SendGrid\n\nIf you haven't already, sign up with SendGrid in Google Cloud console, click\nManage On Provider to go to the SendGrid domain, and click Settings to retrieve\nyour username and to create an API key. As a Google Cloud developer, you can\nstart with 12,000 free emails per month.\n\n[Go to SendGrid Email API](https://console.cloud.google.com/marketplace/details/sendgrid-app/sendgrid-email)\n\n### Configure variables\n\nSendGrid uses the API key and a From email address for sending mail. You\ncan provide this information with one of the following options:\n\n- (Recommended)\n [Store values in Secret Manager](#store-secret-manager)\n\n- [Store values in Airflow](#store-airflow)\n\n | **Caution:** If you use this option, the value for the SendGrid API key is stored in an Airflow connection.\n\n#### Store values in Secret Manager\n\nTo store values in Secret Manager:\n\n1. [Configure Secret Manager](/composer/docs/composer-3/configure-secret-manager) for your\n environment. Make sure to set up permissions and Airflow configuration\n options for the secrets backend.\n\n2. [Override](/composer/docs/composer-3/override-airflow-configurations) the following Airflow configuration options:\n\n3. Create a secret for the SendGrid connection named\n `airflow-connections-sendgrid_default`. Set the secret's value to the\n connection URI. For example:\n\n sendgrid://\u003cusername\u003e:\u003csendgrid_api_key\u003e@smtp.sendgrid.net:587\n\n For more information about storing connections in\n Secret Manager, see\n [Manage Airflow connections](/composer/docs/composer-3/manage-airflow-connections).\n4. Configure the email address for SendGrid. It's not possible to set up the\n email address through a secret. Instead, [override](/composer/docs/composer-3/override-airflow-configurations) the\n following Airflow configuration option:\n\n#### Store values in Airflow\n\n1. [Override](/composer/docs/composer-3/override-airflow-configurations) the following Airflow configuration options:\n\n2. In Airflow, [configure the connection](/composer/docs/composer-3/manage-airflow-connections)\n named `sendgrid_default`. Specify the Sendgrid API key in the connection\n URI. For example:\n\n gcloud composer environments run \u003cvar translate=\"no\"\u003eENVIRONMENT_NAME\u003c/var\u003e \\\n --location \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e \\\n connections add -- \\\n --conn-uri \"sendgrid://\u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e:\u003cvar translate=\"no\"\u003eSENDGRID_API_KEY\u003c/var\u003e@smtp.sendgrid.net:587\" \\\n sendgrid_default\n\n Replace the following:\n - `ENVIRONMENT_NAME`: the name of your environment.\n - `LOCATION`: the region where the environment is located.\n - `USERNAME`: the SendGrid username.\n - `SENDGRID_API_KEY`: the SendGrid API key.\n3. Configure the email address for SendGrid. It's not possible to set up the\n email address through a secret. Instead, [override](/composer/docs/composer-3/override-airflow-configurations) the\n following Airflow configuration option:\n\n### Test your SendGrid configuration\n\nTo test SendGrid configuration:\n\n1. Create a test DAG that uses the `EmailOperator`. For example:\n\n\n import datetime\n\n import airflow\n from airflow.operators.email import EmailOperator\n\n\n with airflow.DAG(\n \"composer_sample_sendgrid\",\n start_date=datetime.datetime(2022, 1, 1),\n ) as dag:\n task_email = EmailOperator(\n task_id=\"send-email\",\n conn_id=\"sendgrid_default\",\n # You can specify more than one recipient with a list.\n to=\"user@example.com\",\n subject=\"EmailOperator test for SendGrid\",\n html_content=\"This is a test message sent through SendGrid.\",\n dag=dag,\n )\n\n1. [Upload the DAG](/composer/docs/composer-3/manage-dags#add) to your environment and check that the task succeeds.\n2. Sign in to SendGrid in with your SendGrid credentials.\n3. In the SendGrid UI, go to Activity page.\n4. Search the list for the email. You should see that SendGrid processed and delivered the email.\n5. If the email is not processed and delivered:\n\n - Check your SendGrid configuration.\n - Verify that you enabled the Secret Manager backend. Make sure that you granted extra permissions and set overrides for Airflow configuration options.\n - Check the spam filter in your email client.\n\nConfigure third-party SMTP services\n-----------------------------------\n\nTo send email through a third-party SMTP service,\n[override](/composer/docs/composer-3/override-airflow-configurations) the `email_backend` Airflow configuration option\nand configure other SMTP-related parameters.\n| **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](#smtp_password) to learn about setting an SMTP password in a more secure way.\n\nTo configure a third-party SMTP service, [override](/composer/docs/composer-3/override-airflow-configurations) the following Airflow configuration options:\n\n### Configure an SMTP password for a third-party SMTP service\n\nKeeping an SMTP password in plain text in Airflow configuration file is a bad\nsecurity practice. That's why Cloud Composer does not support\nthis method. Instead, you can use two other methods for configuring an SMTP\npassword.\n\n#### Using a command to retrieve the SMTP password\n\nYou can use a configuration override to specify a command that obtains the\nSMTP password. When communicating with your SMTP service, Airflow uses this\ncommand to get the value of the password. Specify a single command, without\nbash operators such as pipes and redirects.\n\nTo use this method, [override](/composer/docs/composer-3/override-airflow-configurations) the following Airflow\nconfiguration option:\n\n\n#### Using a secret stored in Secret Manager to retrieve an SMTP password\n\nYou can [configure Secret Manager](/composer/docs/composer-3/configure-secret-manager) as your\nAirflow secrets backend.\n| **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.\n\nOnce you configure Secret Manager for your Composer\nenvironment, you can store an SMTP password in Secret Manager:\n\n1. Create a new secret:\n\n echo -n \"\u003cvar translate=\"no\"\u003eSMTP_PASSWORD\u003c/var\u003e\" | gcloud beta secrets create \\\n airflow-config-smtp-password \\\n --data-file=- \\\n --replication-policy=automatic\n\n Replace `SMTP_PASSWORD` with your SMTP password.\n2. Configure Airflow to obtain the SMTP password from\n Secret Manager. To do so, [override](/composer/docs/composer-3/override-airflow-configurations)\n the following Airflow configuration option:\n\nWhat's next\n-----------\n\n- [Override Airflow configuration options](/composer/docs/composer-3/override-airflow-configurations)\n- [Set environment variables](/composer/docs/composer-3/set-environment-variables)"]]
