tb-email v1.2.3

tb-email Reference

Este módulo permite el envío de emails desde el servidor.

Configuración

Para utilizar el servicio de envío de emails es necesario configurar como se explicará a continuación.

- Servicios disponibles:

Para poder utilizar un servicio se utilizarán los identificadores de cada uno de ellos.

Los servicios disponibles para envío de emails son:

• SMTP

  • Identificador: "smtp"

• SendGrid

  • Identificador: "sendgrid"
  • Página web

• MailJet

  • Identificador: "mailjet"
  • Página web

- Configuración desde interfaz administrativa:

IMPORTANTE: La configuración desde la interfaz no está disponible para la ultima versión de tb-email

- Configuración manual:

La configuración manual se realiza sobre una colección en la base de datos llamada "tb.configs".

Para ello hay que añadir un nuevo documento cuyo id sea el "emailOptions" (Ej. "_id":"emailOptions"). Dicho documento debe tener un objeto para cada uno de los servicios que se quiera configurar cuya clave sea el identificador del servicio.

- Configuración del servicio SMTP:

Para configurar SMTP se requerirán los siguientes campos:

Un ejemplo de configuración del servicio SMTP sería el siguiente:

{
    "_id" : "emailOptions",
     "smtp" : {
        "user" : "myEmail@gmail.com",
        "pass" : "myPassword"
    },
    …
}

- Configuración del servicio SendGrid:

Para configurar SMTP se requerirán los siguientes campos:

Un ejemplo de configuración del servicio SendGrid sería el siguiente:

{
    "_id" : "emailOptions",
    "sendgrid" : {
        "apiKey" : "myApiKey"
    }
    …
}

- Configuración del servicio MailJet:

Para configurar SMTP se requerirán los siguientes campos:

Un ejemplo de configuración del servicio MailJet sería el siguiente:

{
    "_id" : "emailOptions",
    "mailjet" : {
        "apiKey" : "myApiKey",
        "apiSecret" : "myApiSecret"
    }
    …
}

Modo de uso

El envío de emails se puede realizar mediante la Class Api del servidor utilizando las funciones de "App.email" o a través de una peticion POST al servidor.

Funcionalidades

- Envío de un email:

Para enviar un email simple basta con indicar los destinatarios, el asunto y el texto que se va a enviar.

Pero en ocaciones es necesario enviar un mismo email a diferentes usuarios y en diferentes momentos, como por ejemplo al registrarse un usuario para pedir validación, o simplemente para recordar una contraseña. Para estos casos existe el envío de email desde templates. Que permiten predefinir un contenido de email en formato html permitiendo reemplazar ciertos valores para personalizar el email dependiendo del destinatario.

Nota: Para saber más cómo predefinir un email leer "Creando un email template".

• REST Api:

Petición:

- Parámetros Body:

- Respuesta:

- Ejemplo 1: Ejemplo básico

• Petición:

POST: https://a2server.a2system.net:1234/api/v1/srv/email

• BODY:

  {
    "service":"smtp",
    "from": "\"Fred Foo 👻\" <foo@example.com>", 
    "to": "bar@example.com",
    "subject": "Hello ✔",
    "text": "Hello world?",
    "html": "<b>Hello world?</b>"    
  }

- Ejemplo 2: Uso de template y lista de destinatarios

• Petición:

POST: https://a2server.a2system.net:1234/api/v1/srv/email

• BODY:

  {
    "service":"smtp",
    "from": "\"Fred Foo 👻\" <foo@example.com>", 
    "to": "bar@example.com, baz@example.com",
    "subject": "Hello ✔",
    "templateId":<myTemplateId> 
  }

- Ejemplo 3: Destinatario como objeto

• Petición:

POST: https://a2server.a2system.net:1234/api/v1/srv/email

• BODY:

  {
    "service":"smtp",
    "from": "\"Fred Foo 👻\" <foo@example.com>", 
    "to": {"name":"Bar", "email":"bar@example.com"},
    "subject": "Hello ✔",
    "templateId":<myTemplateId> 
  }

- Ejemplo 3: Destinatario como array

• Petición:

POST: https://a2server.a2system.net:1234/api/v1/srv/email

• Respuesta:

• BODY:

  {
    "service":"smtp",
    "from": "\"Fred Foo 👻\" <foo@example.com>", 
    "to": [{"name":"Bar", "email":"bar@example.com"}, "other@example.com"],
    "subject": "Hello ✔",
    "templateId":<myTemplateId> 
  }

• Código Javascript:

- Parámetros:

- Respuesta:

- Ejemplo:

var from = "\"Fred Foo 👻\" <foo@example.com>";
var to = "receiver1@gmail.com, receiver2@gmail.com" // tambien se puede utilizar [receiver1@gmail.com, receiver2@gmail.com]
var subject = "Email's subject";
var text = "Email's content";
var html = "<p>Email's html content</p>";
var email =   {
    "service":"smtp",
    "from": from, 
    "to": to,
    "subject": subject,
    "text": text,
    "html": html   
  }

App.email.send(email)
  .then(res => {…})
  .catch(err => {…})

Creando un email template:

Un email template es un archivo que tiene el contenido de un email para utilizar en distintas ocaciones, como el registro de un usuario, recordar una contraseña, dar la bienvenida, etc…. Para crear un template hay que crear archivos con el contenido del email y el subject y ubicarlos en una ruta específica para que sean reconocidos. Los templates permiten definición de variables que pueden ser reemplazadas en el momento del envío para así poder personalizar el email en función del destinatario.

A continuación veremos cómo crear un template y dónde ubicarlo para cuando utilicemos el servicio 'smtp'.

Para servicios distintos el template debe ser creado en la página web del servicio.

- Ubicación de los templates:

Un template debe estar alojado bajo la carpeta "resources" de nuestro servidor. Para ello, si no existía previamente, añadir una carpeta en "app/" de manera que quede como a continuación.

  root/
    - a2s/
    - app/
      - resources/
        - emails/

Una vez creada la carpeta "resources" es necesario crear una subcarpeta llamada "emails", donde ubicaremos los distintos templates.

Cada template tendrá un identificador y por cada template existirá una carpeta con los distintos archivos que pertenezcan al template. De esta manera, el identificador del template debe ser el nombre de la carpeta.

Por ejemplo, si creamos un template cuyo nombre sea "registration". Bajo la carpeta "resources" será necesario crear una carpeta con el nombre "registration", que será donde se almacenen los distintos archivos.

- Creando el contenido:

El contenido de un template puede estar en formato html y/o en texto plano para que se adapte según la necesidad del cliente de email del destinatario.

Para ello podemos crear distintos archivos que contengan los textos en formato html y archivos que contengan el texto en formato de texto plano dependiendo del idioma.

Para referenciar un template se utilizará su identificador. Dicho identificador será el nombre de la carpeta en la que estén alojados los distintos archivos.

Y los nombres de los archivos serán el código del idioma ("en", "es", "fr", etc…) con extensión .html, si el contenido es html, o .txt si el contenido es de texto plano.

- Ejemplo:

• Identificador: "registration"

• Ubicación:

root/
  - app/
    - resources/
      - emails/
        - resgistration/
          - en.html
          - en.txt

• en.html:

<!DOCTYPE html>
<html>
  <body>
    <h1>This is a Heading</h1>

    <p>This is a paragraph. And this is your name: ${name}</p>
  </body>
</html>

• en.txt:

This is a Heading

This is a paragraph. And this is your name: ${name}

Como se pudo ver en el ejemplo anterior, los textos tienen algunas variables para poder ser reemplazadas en el momento del envío. Estas variables se declaran estableciendo el nombre de la variable entre llaves y comenzando por el símbolo '$'

• Ejemplo:

  ${name} Declara una variable que se llama 'name'

NOTA 1: Si no se crea el template en formato de texto plano se intentará convertir el contenido del archivo html y extraer tomar una versión de texto plano.

NOTA 2: Si no se crea contenido en formato html ni en formato de texto plano no se podrá enviar el email.

- Creando el asunto:

En la mayoría de los casos los emails se mandan con un asunto. Para declarar el asunto basta con agregar la etiqueta "head" en el archivo html. Esto implica que es necesario que exista el contenido html para poder añadir un asunto.

De esta manera, añadiendo un asunto al ejemplo anterior quedaría de la siguiente manera:

- Ejemplo:

• en.html:

  <!DOCTYPE html>
  <html>
    <head>
      <title>This is the subject, and ${name} is your name</title>
    </head>
    <body>
      <h1>This is a Heading</h1>

      <p>This is a paragraph. And this is your name: ${name}</p>
    </body>
  </html>

• en.txt (No tiene asunto):

This is a Heading

This is a paragraph. And this is your name: ${name}

- Reemplazando variables:

Para reemplazar las variables creadas en los templates basta con pasar un objeto a la función "sendFromTemplate()" cuyas claves sean los nombres de las variables y cuyos valores sean los que se van a reemplazar.

Por ejemplo, si en los ejemplos anteriores pasáramos un objeto que indique el valor de "name" quedaría de la siguiente manera:

- Ejemplo:

var to = "receiver1@gmail.com" 
var templateId = "registration";  
var params = {
  name: "John"
}
App.email.sendFromTemplate(to,templateId,params, "en")
  .then(res => {…})
  .catch(err => {…})

- Respuesta:

• en.html:

<!DOCTYPE html>
<html>
  <head>
    <title>This is the subject, and John is your name</title>
  </head>
  <body>
    <h1>This is a Heading</h1>

    <p>This is a paragraph. And this is your name: John</p>
  </body>
</html>

• en.txt:

This is a Heading

This is a paragraph. And this is your name: John

Modelos

tb.email-sents

Modelo de datos que contiene información sobre un email enviado a un cierto destinatario. Si un email fue enviado a más de un destinatario. Apareceran tantos registros con la misma información del email como destinatarios tenga el envío pero indicarán distinta informacion relacionada con cada uno de los destinatarios