Participe do Firebase Summit on-line e presencialmente em 18 de outubro de 2022. Veja como usar o Firebase pode ajudar você a acelerar o desenvolvimento de apps, a lançar seu aplicativo com confiança e a fazer o escalonamento com facilidade. Inscreva-se agora

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 emails automaticamente com base em documentos em uma coleção do Cloud Firestore. Adicionar um documento à coleção aciona essa extensão para enviar um email 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 com suporte a UIDs). O campo de message do documento especifica os outros elementos de email, como a linha de assunto e o corpo do email (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 configurar opcionalmente essa extensão para renderizar emails usando modelos de Handlebars .

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

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

  1. Configure seu serviço de correio 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 emails. Isso normalmente é fornecido por um serviço de entrega de e-mail, como Sendgrid, Mailgun ou Mailchimp Transactional Email, mas também pode ser um servidor que você mesmo executa.

  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 que você especifica. 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 clientes. 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 possam enviar 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 que estão sendo 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 de 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 documento do 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 de Handlebars . Para fazer isso, você precisará de uma coleção do Cloud Firestore para conter seus modelos.

    Consulte Usar modelos de guidão 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, siga um destes procedimentos:

  • Console do Firebase: 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 email. O campo de message contém os detalhes do email a ser entregue, incluindo o corpo do email.

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 email. Os campos disponíveis são:

  • from: 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ário 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 de entrega brutas para o email. Geralmente, esse campo deve ser preenchido apenas por código confiável executado 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 email, 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.
  • attachments: 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 email 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: