Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Usando a extensão Trigger Email

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

A extensão Trigger Email ( firestore-send-email ) permite enviar e-mails automaticamente com base em documentos em uma coleção do Cloud Firestore. Adicionar um documento à coleção aciona essa extensão para enviar um e-mail criado a partir dos campos do documento. Os campos de nível superior do documento especificam o remetente e os destinatários do e-mail, incluindo as opções to , cc e bcc (cada uma suportando UIDs). O campo de message do documento especifica os outros elementos do e-mail, como a linha de assunto e o corpo do e-mail (seja texto simples ou HTML).

Aqui está um exemplo básico de gravação de documento que acionaria essa extensão:

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

Você também pode, opcionalmente, configurar esta extensão para renderizar e-mails usando modelos Handlebars .

Configuração de pré-instalação

Antes de instalar a extensão, conclua estas etapas:

  1. Configure seu serviço de e-mail de saída.

    Ao instalar a extensão Trigger Email, você precisará especificar os detalhes de conexão e autenticação de um servidor SMTP, que a extensão usa para enviar e-mails. Normalmente, isso é fornecido por um serviço de entrega de e-mail, como Sendgrid, Mailgun ou Mailchimp Transactional Email, mas também pode ser um servidor executado por você.

  2. Crie uma coleção de documentos de e-mail.

    A extensão Trigger Email detecta novos documentos em uma coleção do Cloud Firestore especificada por você. Ao encontrar um novo documento, a extensão envia um e-mail com base nos campos do documento. Você pode usar qualquer coleção do Cloud Firestore para essa finalidade; os exemplos nesta página usam uma coleção chamada email .

  3. Configure regras de segurança para sua coleção de documentos de e-mail.

    Essa extensão pode ser usada para acionar a entrega de e-mail diretamente de aplicativos cliente. No entanto, você deve controlar cuidadosamente o acesso do cliente à coleção para evitar possíveis abusos (você não deseja que os usuários enviem e-mails arbitrários do endereço da sua empresa!).

    As regras de segurança variam de aplicativo para aplicativo, mas você deve sempre garantir que os e-mails sejam enviados apenas para os destinatários pretendidos e que o conteúdo de formato livre seja reduzido ao mínimo. Os modelos podem ajudar aqui - você pode usar regras de segurança para verificar se os dados preenchidos no modelo correspondem às suas expectativas sobre o que um usuário deve ter permissão para acionar.

  4. Opcional: Configure uma coleção de usuários.

    No uso básico desta extensão, você especifica os destinatários de um e-mail especificando seus endereços de e-mail nos campos to , cc e bcc do documento da mensagem. Como alternativa, se você tiver um banco de dados de usuários no Cloud Firestore, poderá especificar destinatários usando os UIDs dos usuários. Para que isso funcione, sua coleção de usuários deve atender a estes critérios:

    • A coleção deve ser codificada em IDs de usuário. Ou seja, o ID do documento de cada usuário na coleção deve ser o UID do Firebase Authentication do usuário.
    • Cada documento do usuário deve ter um campo de e- email contendo o endereço de e-mail do usuário.
  5. Opcional: configure uma coleção de modelos.

    Você pode renderizar e-mails usando modelos Handlebars . Para fazer isso, você precisará de uma coleção Cloud Firestore para conter seus modelos.

    Consulte Usar modelos Handlebars com a extensão Trigger Email para obter detalhes.

Instale a extensão

Para instalar a extensão, siga as etapas na página Instalar uma extensão do Firebase . Em resumo, faça um dos seguintes:

  • Firebase console: Clique no botão a seguir:

    Instale a extensão Trigger Email

  • CLI: Execute o seguinte comando:

    firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

Ao instalar a extensão, você será solicitado a especificar suas informações de conexão SMTP e as coleções do Cloud Firestore que você configurou anteriormente.

Use a extensão

Após a instalação, esta extensão monitora todas as gravações de documentos na coleção que você configurou. O e-mail é entregue com base no conteúdo dos campos do documento. Os campos de nível superior especificam o remetente e os destinatários do e-mail. O campo da message contém os detalhes do e-mail a ser entregue, incluindo o corpo do e-mail.

Exemplo: Enviar um e-mail

Para enviar uma mensagem simples, adicione um documento à sua coleção de mensagens com um campo to e um campo de message com o seguinte conteúdo:

to: ['someone@example.com'],
message: {
  subject: 'Hello from Firebase!',
  text: 'This is the plaintext section of the email body.',
  html: 'This is the <code>HTML</code> section of the email body.',
}

Campos de remetente e destinatário

Os campos de nível superior do documento fornecem as informações do remetente e do destinatário do e-mail. Os campos disponíveis são:

  • de: O endereço de e-mail do remetente. Se não for especificado no documento, usa o parâmetro configurado "Default FROM address".
  • replyTo: o endereço de e-mail de resposta. Se não for especificado no documento, usa o parâmetro configurado "Endereço REPLY-TO padrão".
  • para: Um único endereço de e-mail de destinatário ou uma matriz contendo vários endereços de e-mail de destinatário.
  • toUids: Uma matriz contendo os UIDs do destinatário.
  • cc: Um único endereço de e-mail de destinatário ou uma matriz contendo vários endereços de e-mail de destinatário.
  • ccUids: Uma matriz contendo os UIDs do destinatário CC.
  • bcc: um único endereço de e-mail de destinatário ou uma matriz contendo vários endereços de e-mail de destinatário.
  • bccUids: Uma matriz contendo os UIDs do destinatário BCC.
  • headers: Um objeto de campos de cabeçalho adicionais (por exemplo, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

OBSERVAÇÃO: as toUids , ccUids e bccUids entregam e-mails com base em UIDs de usuários codificados para endereços de e-mail em um documento do Cloud Firestore. Para usar essas opções de destinatário, você precisa especificar uma coleção do Cloud Firestore para o parâmetro "Coleção de usuários" da extensão. A extensão pode então ler o campo de email para cada UID especificado nos toUids , ccUids e/ou bccUids .

Campo de mensagem

O campo de message do documento contém informações brutas de entrega para o e-mail. Este campo geralmente deve ser preenchido apenas por código confiável em execução em seus próprios servidores ou Cloud Functions (consulte a seção "Regras de segurança e envio de e-mail" abaixo).

As propriedades disponíveis para o campo de message são:

  • messageId: um cabeçalho de ID de mensagem para o e-mail, se houver.
  • assunto: O assunto do e-mail.
  • text: O conteúdo de texto simples do e-mail.
  • html: O conteúdo HTML do e-mail.
  • amp: O conteúdo AMP4EMAIL do e-mail.
  • anexos: Uma matriz contendo anexo(s); Opções do Nodemailer suportadas: string utf-8, tipo de conteúdo personalizado, URL, string codificada, URI de dados e nó MIME pré-gerado (esteja ciente de que seu e-mail não tem acesso ao sistema de arquivos do servidor em nuvem).

Uso avançado

Saiba mais sobre o uso mais avançado desta extensão: