Usa la extensión Correo electrónico activador

La extensión Correo electrónico activador (firestore-send-email) te permite enviar correos electrónicos de forma automática en función de documentos en una colección de Cloud Firestore. Cuando se agrega un documento a la colección, se activa la extensión para enviar un correo electrónico generado a partir de los campos del documento. Los campos de nivel superior del documento especifican el remitente y los destinatarios del correo electrónico, incluidas las opciones to, cc y bcc (todas admiten UID). El campo message del documento especifica los otros elementos del correo electrónico, como el asunto y el cuerpo del mensaje (ya sea en texto simple o HTML).

A continuación, veremos un ejemplo básico de una operación de escritura que activaría esta extensión:

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

De forma opcional, también puedes configurar esta extensión para renderizar correos electrónicos con las plantillas de Handlebars.

Configuración previa a la instalación

Antes de instalar la extensión, sigue estos pasos:

  1. Configura tu servicio de correo saliente.

    Cuando instales la extensión Correo electrónico activador, deberás especificar los detalles de conexión y autenticación de un servidor SMTP, que la extensión usa para enviar correos electrónicos. Por lo general, los proporciona un servicio de entrega de correo electrónico, como Sendgrid, Mailgun o Mailchimp Transactional Email, pero también podría ser un servidor que administras tú mismo.

  2. Crea una colección de documentos por correo electrónico.

    La extensión Correo electrónico activador detecta documentos nuevos en una colección de Cloud Firestore que especifiques. Cuando encuentra un documento nuevo, la extensión envía un correo electrónico basado en los campos del documento. Puedes usar cualquier colección de Cloud Firestore con este propósito. En los ejemplos de esta página, se usa una colección llamada email.

  3. Configura reglas de seguridad para la recopilación de documentos de correo electrónico.

    Esta extensión se puede usar para activar la entrega de correo electrónico directamente desde las aplicaciones cliente. Sin embargo, debes controlar con cuidado el acceso de los clientes a la colección para evitar posibles abusos (no es recomendable que los usuarios puedan enviar correos electrónicos arbitrarios desde la dirección de tu empresa).

    Las reglas de seguridad varían según la aplicación, pero siempre debes asegurarte de que los correos electrónicos se envíen solo a los destinatarios previstos y que el contenido en formato libre se limite al mínimo. Las plantillas pueden ser útiles en estos casos, y puedes usar reglas de seguridad para verificar que los datos que se propagan a la plantilla correspondan con lo que se espera que pueda activar un usuario.

  4. Configura una colección de usuarios (opcional).

    En el uso básico de esta extensión, debes especificar los destinatarios de un correo electrónico. Para ello, especifica sus direcciones de correo electrónico en los campos to, cc y bcc del documento del mensaje. Como alternativa, si tienes una base de datos de usuarios en Cloud Firestore, puedes especificar destinatarios mediante los UID de los usuarios. Para que esto funcione, la colección de usuarios debe cumplir con los siguientes criterios:

    • La colección debe estar vinculada con los ID de usuario. Es decir, el ID del documento de cada documento de usuario en la colección debe ser el UID de Firebase Authentication del usuario.
    • Cada documento de usuario debe tener un campo email que contenga la dirección de correo electrónico del usuario.

  5. Configura una colección de plantillas (opcional).

    Puedes renderizar correos electrónicos con plantillas de Handlebars. Para ello, necesitarás una colección de Cloud Firestore a fin de que contenga tus plantillas.

    Si deseas obtener más información, consulta Utiliza plantillas de Handlebars con la extensión Correo electrónico activador.

Instala la extensión

Para instalar la extensión, sigue los pasos que se indican en la página Instala una Extensión de Firebase. En resumen, realiza una de las siguientes acciones:

Cuando instales la extensión, se te solicitará que especifiques la información de conexión SMTP y las colecciones de Cloud Firestore que configuraste antes.

Usa la extensión

Después de la instalación, esta extensión supervisa todas las escrituras de documentos en la colección que configuraste. Los correos electrónicos se envían en función del contenido de los campos del documento. Los campos de nivel superior especifican el remitente y los destinatarios del correo electrónico. El campo message contiene los detalles del correo electrónico que se enviará, incluido el cuerpo del correo electrónico.

Ejemplo: Envía un correo electrónico

Para enviar un mensaje simple, agrega un documento a tu colección de mensajes con un campo to y un campo message con el siguiente contenido:

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 remitente y destinatario

Los campos de nivel superior del documento proporcionan información sobre el remitente y el destinatario del correo electrónico. Los campos disponibles son los siguientes:

  • from: Es la dirección de correo electrónico del remitente. Si no se especifica en el documento, se usa el parámetro configurado “Default FROM address”.
  • replyTo: Es la dirección de correo electrónico de respuesta. Si no se especifica en el documento, se usa el parámetro configurado “Default REPLY-TO address”.
  • to: Es una dirección de correo electrónico de destinatario único o un array que contiene varias direcciones de correo electrónico de destinatario.
  • toUids: Es un array que contiene los UID del destinatario.
  • cc: Es una sola dirección de correo electrónico de destinatario o un array que contiene varias direcciones de correo electrónico de destinatario.
  • ccUids: Es un array que contiene los UID de destinatarios en Cc.
  • bcc: Es una dirección de correo electrónico de destinatario único o un array que contiene varias direcciones de correo electrónico de destinatario.
  • bccUids: Es un array que contiene los UID de destinatario en Cco.
  • headers: Es un objeto de campos de encabezado adicionales (por ejemplo, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"})

NOTA: Las opciones toUids, ccUids y bccUids entregan correos electrónicos en función de los UID de usuario vinculados a direcciones de correo electrónico dentro de un documento de Cloud Firestore. A fin de usar estas opciones de destinatario, debes especificar una colección de Cloud Firestore para el parámetro “Users collection” de la extensión. A continuación, la extensión puede leer el campo email de cada UID especificado en los campos toUids, ccUids o bccUids.

Campo de mensaje

El campo message del documento contiene información de entrega sin procesar para el correo electrónico. Por lo general, este campo solo debe propagarse con el código de confianza que se ejecuta en tus propios servidores o Cloud Functions (consulta la sección “Reglas de seguridad y envío de correos electrónicos” que aparece a continuación).

Las propiedades disponibles para el campo message son las siguientes:

  • messageId: Es un encabezado de ID de mensaje para el correo electrónico, si corresponde.
  • subject: Es el asunto del correo electrónico.
  • text: Es el contenido de texto simple del correo electrónico.
  • html: Es el contenido HTML del correo electrónico.
  • amp: Es el contenido AMP4EMAIL del correo electrónico.
  • attachments: Es un array que contiene adjuntos. Se admiten opciones de Nodemailer: string utf-8, tipo de contenido personalizado, URL, string codificada, URI de datos y nodo MIME pregenerado (ten en cuenta que tu correo electrónico no tiene acceso al sistema de archivos del servidor de nube).

Uso avanzado

Obtén más información sobre el uso más avanzado de esta extensión: