Manual de Integración Email V4 (MAN-PP-03-03 ) #

Contenido

1. Control de Cambios. 2
2. Introducción. 3
3. Envío de Mensajes de Correo Electrónico. 4
4. SMTP: Protocolo Simple de Transferencia de Correo. 5
5. Recomendaciones de uso SMTP. 6
6. Pasos para la integración SMTP en Aldeamo. 6
7. Web Service Rest tipo POST. 9

1.           Control de Cambios #

2.           Introducción #

Aldeamo está en la capacidad de suministrar infraestructura, servicios, interfaz, protocolos y recursos necesarios para el envío de correos electrónicos mediante una integración a través de un Protocolo SMTP o HTTP

Para la integración de nuestros clientes a la plataforma de E-mail, contamos con un protocolo SMTP y HTTP que permite a nuestros aliados el envío y recepción de mensajes de correo electrónico. Esta tecnología facilita la integración rápida y transparente con el fin de potencializar el negocio de nuestros clientes y asociados.

Aldeamo cuenta con integraciones con proveedores de diferentes servicios de comunicación, principalmente operadores móviles (SMS, Flash SMS), proveedores de servicios de correo electrónico (Gmail, Hotmail, Yahoo etc.) y proveedores de servicios de mensajería OTP (WhatsApp, Facebook Messenger, Twitter, RCS, etc.). La comunicación en cada una de estas integraciones está protegida por los mecanismos de seguridad que ofrezca cada canal, principalmente basados en TLS 1.2 (HTTPS, SMTPS, VPN).

3.           Envío de Mensajes de Correo Electrónico #

La plataforma Email de Aldeamo permite la integración para envío de mensajes originados por su plataforma por medio de varios servicios de integración expuestos:

1. SMTP
2. HTTP

A continuación, se detallan estas tecnologías para un mayor entendimiento de su uso y complejidad:

4.           SMTP: Protocolo Simple de Transferencia de Correo #

SMTP es un protocolo de comunicación estándar que tiene 36 años de antigüedad y es utilizado por la gran mayoría de aplicaciones del mundo para poder enviar correo electrónico. Desde Outlook hasta el sistema CRM de su empresa.

El Protocolo SMTP es la entrega de correo de extremo a extremo desde un servidor de correo a otro. Existe una conexión directa entre un remitente SMTP (el cliente) y el receptor SMTP de destino (el servidor). El cliente SMTP mantiene el correo en el remitente hasta que lo transmite y lo copia satisfactoriamente en el receptor SMTP (servidor).

Para enviar correos electrónicos a través de la interfaz SMTP de Aldeamo, necesitará lo siguiente:

Parámetros:

*Estas credenciales serán entregadas por su ejecutivo de cuenta encargado.

Valores retornados:

Los valores retornados están implícitos en el protocolo SMTP.

Información importante de correo electrónico:

Cuando acceda a correo electrónico Aldeamo a través de la interfaz de SMTP, su aplicación cliente de SMTP monta el mensaje, por lo que la información que necesita proporcionar depende de la aplicación que esté utilizando. Como mínimo, el intercambio SMTP entre un cliente y un servidor requiere una dirección de origen, una dirección de destino y datos de mensaje.

Si utiliza la interfaz de SMTP y tiene habilitado el reenvío de retroalimentación, las notificaciones de rebotes, reclamaciones y entrega se envían a la dirección “MAIL FROM”. No se utiliza ninguna dirección “Reply-To” que especifique.

5.           Recomendaciones de uso SMTP #

• Si el sistema en el que está trabajando no cuenta con una integración a través de Protocolo SMTP, usted puede implementar una librería que lo permita.

• Si por motivos de seguridad, su acceso a la red es controlado por un Firewall “IPTABLES, SECURITY GROUP”, habilite el puerto SMTP 25 para permitir el tráfico de entrada y salida de correos electrónicos mediante este Protocolo.

6.           Pasos para la integración SMTP en Aldeamo #

Existe una serie de paquetes de software comerciales y de código abierto que admiten el envío de correo electrónico a través de SMTP. Estos son algunos ejemplos:

• Plataformas de blog.
• Agregadores RSS.
• Software de administración de listas.
• Sistemas de flujo de trabajo.
• Sistemas de gestión de requerimientos.
• CRM.

Puede configurar cualquier software habilitado para SMTP de este tipo para enviar correo electrónico a través de la interfaz de SMTP de Aldeamo. Para obtener instrucciones sobre cómo configurar SMTP para un determinado paquete de software, consulte la documentación de dicho software.

El siguiente procedimiento muestra cómo configurar el envío de correo electrónico automático con Aldeamo en JIRA, una conocida solución de seguimiento de Requerimientos. Con esta configuración, JIRA puede notificar a los usuarios por correo electrónico cuando haya un cambio en el estado de un problema de software.

Para configurar JIRA para enviar correo electrónico utilizando Aldeamo SMTP:

1. JIRA solicita a su ejecutivo de cuenta en Aldeamo la creación de un usuario en la interfaz de envío de correo electrónico.
2. JIRA solicita a su ejecutivo de cuenta en Aldeamo los parámetros necesarios para la integración SMTP.

Importante:

Las credenciales de uso del Protocolo SMTP son únicas para cada usuario. Si su organización necesita tener varios usuarios debe informarlo a su ejecutivo de cuenta en Aldeamo para la creación específica.

1. En la ventana del navegador, elija Administration.
2. En el menú System, elija Mail.
3. En la página Mail administration, elija Mail Servers.
4. Elija Configure new SMTP mail server.
5. En el formulario Add SMTP Mail Server, rellene los campos siguientes:
   1. Name: Deberá dar un nombre descriptivo para este servidor.
   2. From address: “Usuario”: Credenciales de la dirección desde la que se enviará el correo electrónico.
   3. Email prefix: Una cadena que JIRA añade a cada línea de asunto antes del envío.
   4. Protocol: Elija SMTP.

Nota:

Si no puede conectar a Aldeamo utilizando esta configuración, pruebe SECURE_SMTP.

1. 1. Host Name: “Servidor SMTP”: Dirección del servidor de salida de correo electrónico.

Ejemplo: email-smtp-2.aldeamo.com

1. 1. SMTP Port: “Puerto”: Puerto del servidor de salida de correo electrónico.

Ejemplo: 2589

1. 1. TLS: Seleccione esta casilla de verificación.
   2. Username: Su nombre de usuario de SMTP.
   3. Password: Su contraseña de SMTP.

1. Elija Test Connection: Si el correo electrónico de prueba que envía JIRA a través de Aldeamo llega correctamente, su configuración está completa.

• Ejemplo de la petición con Body HTML

Puedes enviar cualquiera de tus plantillas creadas a través del servicio SMTP, para esto se debe modificar el asunto y el correo del mensaje.

En el asunto, se debe añadir al comienzo la etiqueta *|tid:TEMPLATE_ID|* donde se debe reemplazar TEMPLATE_ID por el ID de la plantilla que se encuentra debajo del nombre en el listado de plantillas.

Esta etiqueta será eliminada de forma automática del mensaje, luego de esta etiqueta se puede poner el asunto del mensaje, incluso se puede usar variables en el texto del asunto, por ejemplo:

*|tid:42eqy7oaigql|* Este es un mensaje para {nombre} {apellido}

IMPORTANTE: Si el mensaje no contiene variables, la versión HTML y PLAIN-TEXT deben tener solamente la palabra “null”.

• ¿Cómo usar variables en el correo SMTP?

Si la plantilla tiene texto variable, se puede enviar en el cuerpo del mensaje el valor de las variables y estas serán reemplazadas de forma automática en el correo enviado.

Para usar variables en la plantilla, se debe usar sintaxis {NOMBRE_VARIABLE} reemplazar por NOMBRE_VARIABLE por el nombre de la variable que se quiere reemplzar de forma automática.

No se debe usar caracteres especiales en el nombre de las variables (ñ,&;, signos especiales, caracteres con tilde, etc.) ya que estas pueden no ser reemplazadas debido a la codificación del código HTML del mensaje.

Para usar variable en el mensaje, el cuerpo del correo debe tener la siguiente sintaxis:

{“nombre_variable”:”valor variable”}

Por ejemplo:

{
“var1″:”Random variable 1”,
“var2″:”Random variable 2”,
“var 3″:”Random variable”,
“var ñ 4″:”Esta variable puede no ser reeemplazada debido a que contiene caracteres especiales”,
“var-5-5″:”Random variable 5”,
“var&”:”Esta variable puede no ser reeemplazada debido a que contiene caracteres especiales”
}

Este formato es conocido como Json, por lo cual es muy importante el uso correcto de las comillas y los corchetes para que el servicio funciona correctamente.

En los siguientes links se pueden ver ejemplos de código listos para usar:

Node Js (Usando modemailer)

PHP (Usando PhpMailer)

7.           Web Service Rest tipo POST #

Para la integración de nuestros clientes a la plataforma de Email de Aldeamo contamos con un API que permite a nuestros aliados envío y recepción de mensajes de correo electrónico. Esta tecnología facilita una integración rápida y transparente con el fin de potencializar el negocio de nuestros clientes y asociados.

A continuación, se detalla esta tecnología para un mayor entendimiento de su uso y complejidad.

Este api está basado en llamados HTTP POST hechos por el cliente a una URL.

• Autenticación: El cliente se autentica por medio de una llave API_KEY que se obtiene desde la plataforma y se envía de la siguiente manera.

{    “Authorization”: “Bearer {API_KEY}”,}

Bajo este esquema se debe enviar una petición con la siguiente estructura.

• URL para consumir el servicio:
• https://api.ckpnd.com:5001/v1/email

• http://api.ckpnd.com:5000

• Ejemplo de la petición con Body HTML

Conten-Type: application/json

JSON petición:

{

“to”: [

{

“email”: “recipient@exampledomain.com”

}

],

“options”: {

“cc”: [

{

“email”: “cc@exampledomain.com”

}

],

“bcc”: [

{

“email”: “bcc@exampledomain.com”

}

]

},

“from”: {

“email”: “sender@yourdomain.com”,

“name”: “John Doe”

},

“replyTo”: {

“email”: “sender@yourdomain.com”,

“name”: “John Doe”

},

“subject”: “Hello World”,

“body”: “<h1>Hello World</h1>”,

“attachments”: [

{

“path”: “https://i1.wp.com/cms.babbel.news/wp-content/uploads/2015/05/HEAD02_FRA-20150703094705.gif”

},

{

“path”: “http://2.bp.blogspot.com/-DIEPOOz9uqI/UHomvta-AcI/AAAAAAAAAdI/_Nv0WyIXxhA/s1600/P1010411.JPG”

}

]

}

• Ejemplo de la petición usando Plantilla

{

“to”: [

{

“email”: “recipient@exampledomain.com”

}

],

“options”: {

“cc”: [

{

“email”: “cc@exampledomain.com”

}

],

“bcc”: [

{

“email”: “bcc@exampledomain.com”

}

]

},

“from”: {

“email”: “sender@yourdomain.com”,

“name”: “John Doe”

},

“replyTo”: {

“email”: “sender@yourdomain.com”,

“name”: “John Doe”

},

“subject”: “Hello World”,

“template_id”: “42eqy7oaigql”,

“variables”:{

“variable1″:”random variable 1”,

“variable2″:”random variable 2”

}

“attachments”: [

{

“path”:”https://i1.wp.com/cms.babbel.news/wp-content/uploads/2015/05/HEAD02_FRA-20150703094705.gif”

},

{

“path”:”http://2.bp.blogspot.com/-DIEPOOz9uqI/UHomvta-AcI/AAAAAAAAAdI/_Nv0WyIXxhA/s1600/P1010411.JPG”

}

]

}

• Parámetros de la petición

• Esquema de la respuesta

HTTP/1.1 200 OK

{

“message”: “Messages sent!”,

“to”: [

{

“email”: “recipient@exampledomain.com”,

“msgid”: “40f7f020-4c0c-11e9-870a-51bee176686d”

}

]

}

• Parámetros de la respuesta