Como usar a extensão do acionador de e-mails

Com a extensão do acionador de e-mails (firestore-send-email), é possível enviar e-mails automaticamente com base nos documentos em uma coleção do Cloud Firestore. Ao adicionar um documento à coleção, você aciona a 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 (compatíveis com UIDs). O campo message do documento especifica os outros elementos do e-mail, como o assunto e o corpo do e-mail (em texto simples ou HTML).

Veja a seguir um exemplo básico de gravação de documento que acionaria a 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.',
  },
})

Como opção, também é possível configurar essa extensão para renderizar e-mails usando os modelos do Handlebars.

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

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

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

    Ao instalar a extensão do acionador de e-mails, é necessário especificar os detalhes de conexão e autenticação de um servidor SMTP, que a extensão usa para enviar e-mails. Ela é fornecida geralmente por um serviço de entrega de e-mails, como o Sendgrid, o Mailgun ou o e-mail de transação do Mailchimp, mas também é possível usar um servidor executado por você.

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

    A extensão do acionador de e-mails detecta os novos documentos em uma coleção do Cloud Firestore que você especificou. Quando encontra um novo documento, a extensão envia um e-mail com base nos campos do documento. Para isso, use qualquer coleção do Cloud Firestore. 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-mails diretamente dos aplicativos clientes. No entanto, é necessário controlar cuidadosamente o acesso do cliente à coleção para evitar possíveis violações. Por exemplo, para evitar que os usuários enviem e-mails aleatórios usando o endereço da sua empresa.

    As regras de segurança variam de acordo com o aplicativo. Porém, é necessário garantir que os e-mails sejam enviados apenas aos destinatários pretendidos e que o conteúdo livre seja reduzido ao mínimo possível. Os modelos são úteis nesse caso: use as regras de segurança para permitir que os usuários acionem somente os dados apropriados para preencher o modelo.

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

    No uso básico dessa extensão, você especifica os destinatários de um e-mail informando os 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, será possível especificar destinatários usando os UIDs dos usuários. Para que isso funcione, a coleção de usuários precisa atender aos seguintes critérios:

    • A coleção precisa ter chaves nos IDs de usuários. Ou seja, o ID do documento de cada usuário na coleção precisa ser o UID do Firebase Authentication do usuário.
    • Cada documento de usuário precisa ter um campo email com o endereço de e-mail dele.

  5. Opcional: configure uma coleção de modelos.

    Renderize e-mails usando modelos do Handlebars. Para isso, você precisará de uma coleção do Cloud Firestore que contenha seus modelos.

    Para mais detalhes, consulte Usar modelos do Handlebars com a extensão do acionador de e-mail.

Instalar 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:

Ao instalar a extensão, é necessário especificar suas informações de conexão SMTP e as coleções do Cloud Firestore configuradas anteriormente.

Usar a extensão

Após a instalação, essa extensão monitora todas as gravações de documentos na coleção configurada. O e-mail é enviado 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 message contém os detalhes do e-mail a ser enviado, incluindo o corpo do e-mail.

Exemplo: enviar um e-mail

Para enviar uma mensagem simples, adicione um documento à coleção de mensagens com um campo to e um 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 da parte superior do documento fornecem informações sobre o remetente e o destinatário do e-mail. Estes são os campos disponíveis:

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

OBSERVAÇÃO: as opções toUids, ccUids e bccUids enviam e-mails baseados em UIDs dos usuários com chaves em 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 no parâmetro "Users collection" da extensão. Depois, a extensão pode 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 e-mail. Em geral, esse campo é preenchido apenas por códigos confiáveis executados nos seus próprios servidores ou no Cloud Functions. Consulte a seção "Regras de segurança e envio de e-mail" abaixo.

Estas são as propriedades disponíveis para o campo message:

  • messageId: um cabeçalho do ID da mensagem para o e-mail, se houver.
  • subject: 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 do AMP4EMAIL do e-mail.
  • attachments: uma matriz com anexos. Opções do Nodemailer com suporte: string utf-8, tipo de conteúdo personalizado, URL, string codificada, URI de dados e nó MIME pré-gerado. Lembre-se de que seu e-mail não tem acesso ao sistema de arquivos do servidor da nuvem.

Uso avançado

Veja a seguir mais informações sobre o uso mais avançado dessa extensão: