Guía rápida de como iniciar el API

El objetivo de este documento es brindar una guía para el correcto consumo del servicio API de Masivapp para envió de emails. El consumo de nuestra API te ofrece los siguientes beneficios:

✔ Facilidad de integración: Proporciona una forma estandarizada y estructurada de comunicación entre sistemas.

✔ Escalabilidad: Al integrar el API, la aplicación puede escalar más fácilmente al aprovechar los recursos o servicios proporcionados por Masiv ya que permite adaptarse a cambios en la demanda sin necesidad de grandes inversiones en infraestructura.

✔ Funcionalidad extendida: El API ofrece acceso a una amplia gama de funcionalidades que pueden enriquecer tu aplicación.

✔ Colaboración y conectividad: El API permiten la conectividad entre diferentes sistemas y aplicaciones, lo que fomenta la colaboración entre plataformas.

En resumen, la integración con nuestra API es una herramienta poderosa que puede ayudar a las empresas a mejorar sus procesos de envió de notificaciones de correo electrónico y la experiencia de sus usuarios.

1. 🌎Endpoint

A continuación se muestra la url y el método donde el API recibe las peticiones de envío:

Método	URL
POST	https://api.masiv.masivian.com/email/v1/delivery

2. 📋Prerrequisitos

A continuación se definen los prerrequisitos a tener en cuenta antes de enviar un email:

Es necesario que el dominio del remitente esté previamente registrado en el sistema del usuario que realiza las solicitudes.
El número de destinatarios permitidos no debe exceder los 500.
El tamaño del cuerpo de la solicitud no debe exceder los 30 MB, los campos no tienen restricciones de tamaño individuales. Se recomienda que el tamaño no supere los 20 MB en su totalidad

3. 🚫 Restricciones

Restricciones de envío para Colombia (Ley 2300 y RNE):

El API Transaccional de Email cuenta con la funcionalidad de aplicar las restricciones de envío que dicta la Ley 2300 o Ley de Toques para Colombia, así cómo la validación sobre el RNE (La Ley 2300 de Colombia regula los envíos de mensajes de texto con contenido de publicidad y/o cobranza para limitar la cantidad de envíos que se realizan a los usuarios finales y para que además se realicen dentro de los horarios permitidos: de lunes a viernes de 7:00 a.m. a 7:00 p.m., y sábados de 8:00 a.m. a 3:00 p.m., excluyendo domingos y festivos.).

Para que el API aplique las validaciones sobre restricciones, es necesario que se habiliten dichas características en la configuración de la cuenta, el personal de Masiv tiene la capacidad de ajustar la configuración para habilitar las restricciones.

<aside> 💡

Nota: Aclaración sobre cumplimiento de la normativa 2300 y consulta del RNE

El API realiza las validaciones necesarias para asegurar el cumplimiento de la Ley 2300 y consulta del Registro Nacional de Exclusiones (RNE), siempre y cuando las restricciones y parámetros asociados estén activos en la cuenta desde la cual se está efectuando el consumo.

</aside>

4. 🔐Autenticación

La autenticación básica es un esquema de autenticación simple integrado en el protocolo HTTP. Para usarlo, envíe sus solicitudes HTTP con un encabezado de Authorization que contenga la palabra Basic seguida de un espacio y una cadena codificada en base64 correspondiente a usuario:contraseña, como se muestra a continuación:

Nombre	Valor	Descripción	Obligatoriedad
Authorization	Basic <Token>	Cabecera de autenticación de tipo Basic Auth, el token debe contener la estructura de usuario:contraseña codificada en base 64 y corresponder a un usuario de Masiv válido.	Requerido

Ejemplo de encabezado para realizar peticiones a la API codificando usuario:contraseña en base 64.

Authorization: Basic dXN1YXJpbzpjb250cmFzZcOxYQ==

5. 🛰️Especificación de la petición para envíos

En la siguiente tabla se puede observar los diferentes valores que se pueden incluir dentro de la Petición.

<aside> 💡 Importante: Los elementos marcados con 📌 se refieren a parámetros de los objetos complejos de la petición, estos están descritos en detalle en la sección 4.1.

</aside>

Parámetro	Tipo de Dato	Obligatoriedad	Descripción	Valores permitidos
Subject	String	Requerido	Asunto del correo electrónico.	Debe contener al menos 1 carácter.
From	String	Requerido	Dirección del correo electrónico del remitente.	* Debe corresponder a un correo electrónico valido.

Tamaño máximo de 999 caracteres | | ReplyTo | String | No Requerido | Indica a quién se responderá el correo electrónico enviado, si no se especifica se toma el valor enviado en el campo From. | Debe corresponder a un correo electrónico valido. | | Bcc | List<String> | No Requerido | Indica los correos a los cuales se les quiere añadir como copia oculta para todos los recipients añadidos | * Debe corresponder a un correo electrónico valido. | | CC | List<String> | No Requerido | Indica los correos a los cuales se les quiere añadir como copia para todos los recipients añadidos | * Debe corresponder a un correo electrónico valido. | | 📌 Recipients | List<Object> | Requerido | Indica la dirección de correo electrónico del destinatario al que se enviará el correo electrónico, pueden ser uno o más correos electrónicos. | Ver detalle en la sección 4.1.1 | | 📌 Template | Object | Requerido | Contenido del correo electrónico. | Ver detalle en la sección 4.1.2 | | 📌 Parameters | List<Object> | No Requerido | Lista que contiene los parámetros de reemplazo para el contenido del correo electrónico. | Ver detalle en la sección 4.1.3 | | 📌 Attachments | List<Object> | No Requerido | Lista que contiene los archivos adjuntos que se indican en los correos electrónicos a enviar. | Ver detalle en la sección 4.1.4 | | 📌 Metadata | List<Object> | No Requerido | Información adicional al envío para facilitar el manejo de datos | Ver detalle en la sección 4.1.5 |

5.1 Especificación de objetos complejos de la petición

A continuación se describen los parámetros de los objetos complejos de la petición.

📌 5.1.1 Recipients

📌 5.1.2 Template

📌 5.1.3 Parameters

📌 5.1.4 Attachments

📌 5.1.5 Metadata

6. 📝Ejemplos de petición

En este apartado se muestran diferentes ejemplos de petición para cada tipo de envío que se puede realizar dentro de la API.

6.1 🧪 Ejemplos para envíos con HTML Fijo

A continuación se muestran algunos ejemplos que permiten el envió de una plantilla de tipo HTML que será enviado a todos los remitentes especificados en la petición.

6.1.1 Ejemplo Envío de HTML fijo para todos los Destinatarios

6.1.2 Ejemplo Envío de HTML fijo para todos los Destinatarios (Link de Desuscripción)

6.2 🧪 Ejemplos para envíos de plantillas y archivos adjuntos

A continuación se muestran algunos ejemplos para el envío de plantillas y archivos adjuntos.

6.2.1 Adjunto - Archivo Estático

6.2.2 Adjunto - Archivo Masivian Generado

6.2.3 Adjunto - Archivo Generado protegido con contraseña

6.2.4 Adjunto - Archivo Base 64

6.2.5 Adjunto - Archivo con formato de URL

6.2.6 Adjunto - URL de formato de archivo con eliminación en el origen

6.2.7 Envío con adjuntos combinados

6.3 🧪 Ejemplo para el envío de correos electrónicos con parámetros complejos

A continuación se muestra un ejemplo para el envió de parámetros personalizados dentro del correo electrónico.

6.3.1 Envío de correos con Parámetros personalizados

6.4 🧪 Ejemplo para el envío con control de toques

A continuación se muestra un ejemplo de Petición para envío con control de toques.