Usando a extensão Trigger Email

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 esta 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 para UIDs). O campo message do documento especifica os outros elementos do email, como linha de assunto e corpo do email (texto simples ou HTML).

Aqui está um exemplo básico de gravação de documento que acionaria esta 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 esta extensão para renderizar e-mails usando modelos do 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 e-mails. 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 administra.

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

    A extensão Trigger Email escuta novos documentos em uma coleção do Cloud Firestore que você especifica. Ao encontrar um novo documento, a extensão envia um email 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.

    Esta extensão pode ser usada para acionar a entrega de email 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 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 aos 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 digitada 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 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 do Handlebars . Para fazer isso, você precisará de uma coleção do Cloud Firestore para conter seus modelos.

    Consulte Usar modelos do 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, siga um destes procedimentos:

  • Console do Firebase: clique no seguinte botão:

    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 as informações de conexão SMTP e as coleções do Cloud Firestore configuradas 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 email é 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 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 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 do remetente e do 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 estiver especificado no documento, utiliza o parâmetro configurado "Endereço FROM padrão".
  • respondTo: O endereço de e-mail para resposta. Se não especificado no documento, utiliza o parâmetro configurado "Endereço REPLY-TO padrão".
  • to: Um endereço de e-mail de destinatário único ou uma matriz contendo vários endereços de e-mail de destinatários.
  • toUids: uma matriz contendo os UIDs do destinatário.
  • cc: Um endereço de e-mail de destinatário único ou uma matriz contendo vários endereços de e-mail de destinatários.
  • ccUids: uma matriz contendo os UIDs do destinatário do CC.
  • Cco: um endereço de e-mail de destinatário único ou uma matriz contendo vários endereços de e-mail de destinatários.
  • bccUids: uma matriz contendo os UIDs do destinatário Cco.
  • headers: um objeto de campos de cabeçalho adicionais (por exemplo, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

NOTA: As opções toUids , ccUids e bccUids entregam e-mails com base em UIDs de usuários vinculados a 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 email para cada UID especificado nos campos toUids , ccUids e/ou bccUids .

Campo de mensagem

O campo message do documento contém informações brutas de entrega do email. Geralmente, esse campo só deve ser preenchido 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 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 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: