Documentacion DMDS API REST v1.5 usando Postman =============================================== En todos los ejemplos reemplazar **XXXXXXXXXXX** por el nombre del DMDS dedicado, y **APIKEY** o Authorization por el hash secreto. Ejemplo: .. image:: api1.5.png Descargar Postman para Windows ------------------------------ https://www.postman.com/downloads/ Cambios v1.4 a v1.5: cantidad de eventos y eventos paginados ------------------------------------------------------------ Se agrega el método ``cantidad_eventos`` para obtener la cantidad de eventos entre dos fechas determinadas. Cantidad de Eventos entre Fechas ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ejemplo: .. image:: api2.png Eventos entre fechas con paginado ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ El método ``ver_eventos`` permite paginar con largo de página variable mayor o igual a 10, y elegir de una página los eventos que se hayan presentado entre dos fecha-horas determinados. Lleva cuatro parámetros: Ejemplo: .. image:: api3.png .. warning:: Los parámetros **pagina** y **cantidad** dentro del JSON, deben ser numéricos. Consulta Eventos ---------------- La respuesta al envío de mails puede contener un código 4xx , para el cual el usuario deberá tener que analizar el error (p. ej. falta de un parámetro). En caso de funcionar correctamente un envío, la respuesta por lo general es un JSON con estos 3 pares: .. code-block:: json {"status":"ok", "sent":4, "eeid":"3abc993d-8i88-45e8-a6c9-e879378abba5"} El **uuid** que se devuelve como eeid (*envío_efectivo_id*) puede ser consultado posteriormente con un GET. El número que sigue a *sent* es la cantidad de mails enviados durante la llamada, p. ej. un destinatario con 3 copias. .. warning:: Importante: si se quiere agrupar envíos subsiguientes en un mismo lote, se puede agregar la opción **reuse_eeid: true**, y se deberá agregar **eeid: ....** de manera de poder reusar un eeid anterior y agrupar envíos en un mismo lote o batch. .. image:: api33.png Pueden figurar otros eventos como **rebote-soft**, **rebote-hard**, **click** o **view** .. warning:: A partir de v1.4, si el envío efectivo fue efectuado con **archive:true**, el JSON devuelve una sección llamada ``archive`` con la información de la traza del envío efectivo realizado. Cambios v1.3 a v1.4: archiving de mails enviados (requiere licencia de *archiving*) ----------------------------------------------------------------------------------- Se agrega el flag ``archive`` en *send_many_inline* y *send_one_inline*, con el objetivo de guardar en archivo un testigo de lo que fue enviado dentro de un **Envío Efectivo** (también referido como **Lote** o **Batch**). De esta manera, seteando ``archive":"true"`` en la lista de parámetros de los métodos arriba mencionados, se podrá recuperar más información con el método ``eeid_info`` (ver más abajo), y recuperar los formatos EML enviados a cada destinatario. A su vez, para mails archivados, se agrega el método ``eeid_eml`` que permite retornar el texto del mail enviado en un **envío efectivo** a uno de los **receptores**. De esta manera, se podrá tener una copia del **EML** efectivamente instanciado para cada destinatario en particular, conteniendo por ejemplo comprobantes, notificaciones o facturas para fines de **Auditoría**. Esta funcionalidad requiere licencia adicional de *archiving*. Cambios v1.2 a v1.3 - Whitelisting ---------------------------------- Se agrega el método ``whitelist`` que permite preguntar si un contacto está en whitelist, agregarlo o quitarlo de la misma. La **whitelist** sirve para **inmunizar** a un contacto para que no sea invalidado por un posible rebote por falla o mensaje confuso del MTA receptor. También lo protege ante un posible proceso de desuscripción/invalidación que se pueda hacer en base a procesamiento de rebotes. Cambios v1.1 a v1.2 - API version --------------------------------- Se agrega el método ``version`` que devuelve el número de versión de la API. Obtener Versión de la API ------------------------- Con esta llamada al método ``version`` se puede obtener la versión de la API que se está utilizando, y buscar los cambios en la documentación. .. image:: api4.png Cambios v1.0 a v1.1 - Revalidar e Invalidar ------------------------------------------- Se agregan los métodos ``revalidar`` e ``invalidar``, y se guardan eventos de **Revalidación** e **Invalidación** para poder hacer tracking de cambios de estado de contactos. También se agrega el evento **Not-Sent** para los casos en que se intenta enviar un correo electrónico a un contacto inválido. Dicho evento se visualiza en esta versión como **unknown** en la API, y como **Not-Sent** en la interfaz web Mtmail. La visualización de Eventos es compatible con la aplicación https://mtmail.planisys.net que reemplazará a las aplicaciones dmds-*xxxxxxxxxxx*.planisys.net próximamente. Whitelist de contacto --------------------- El método ``whitelist`` se puede utilizar para preguntar si un email está en lista blanca utilizando **GET**, quitarlo de la lista blanca utilizando **DELETE**, y agregarlo a la lista blanca utilizando **POST** o **PUT**. Preguntar si está en lista blanca con **GET**: .. image:: api6.png devuelve en caso de no estar en lista blanca: .. code-block:: json {"status":"ok","msg":"usuario@dominio.com not whitelisted"} y devuelve en caso de estar en lista blanca: .. code-block:: json {"status":"ok","msg":"usuario@dominio.com whitelisted"} Agregar a lista blanca con **POST** o **PUT** : .. image:: api7.png Quitar de lista blanca con **DELETE** .. image:: api8.png Devuelve información de un contacto ----------------------------------- .. image:: api5.png La respuesta viene en un JSON que contiene los eventos, bases/grupos a los que pertenece, campos e información estática. En este caso, se muestra una cuenta de mail que ha sido invalidada luego de dos rebotes **hard**, o *cuenta inexistente*. .. code-block:: json { "status": "ok", "contacto": { "numid": 455895, "email": "user@example.com", "nombre": "Juan", "apellido": "Pérez", "edad": null, "sexo": "M", "operacion": "Modificacion", "invalido": true, "eventos": [ {"evento": "envio", "timestamp": "2020-10-15T08:25:11"} ] } } Listar contactos inválidos -------------------------- .. image:: api14.png Crear de nuevo o actualizar un contacto --------------------------------------- Con esta llamada se puede crear un contacto o actualizar uno existente. La clave para identificar un contacto es siempre su **email** (primary key en BBDD). Asociar a una o más bases a un contacto nuevo o existente --------------------------------------------------------- .. image:: api10.png .. note:: Un **origen** o **base** es lo mismo que un **grupo**. Es el nombre de una ``base de contactos``. Un contacto puede formar parte de varias bases (grupos). Setear valores de campos a un contacto nuevo o existente -------------------------------------------------------- .. image:: api11.png Invalidar un contacto (introducido en v1.1) ------------------------------------------- .. image:: api12.png Se insertará un **Evento** de ``Invalidacion`` con el timestamp cuando ocurrió la invalidez. Al estar el contacto como *inválido*, todo intento de enviarle mail genera un evento ``Not-Sent``. .. note:: Esta es una llamada **GET** .. code-block:: json {"status":"ok","msg":"whitelisted"} Revalidar un contacto (introducido en v1.1) ------------------------------------------- .. image:: api13.png Se insertará un **Evento** de ``Revalidación`` con el timestamp correspondiente. .. note:: Esta es una llamada **GET** .. code-block:: json {"status":"ok","msg":"whitelisted"} Enviar un correo a un solo destinatario con html uri ---------------------------------------------------- Para realizar este envío es necesario definir algunos campos, como por ejemplo: el campo de email debe ser verdadero, si no, no se podrán enviar mensajes. En el apartado de headers, recordar definir su valor de autorización. .. image:: api244.png Esta llamada va a devolver un **eeid** (Envío Efectivo ID), mediante el cual podemos consultar los eventos que se produjeron (ver Consulta Eventos). .. note:: Al especificar una URL, la API REST sigue redirecciones 301/302 hasta obtener finalmente un código 200 y la página. .. warning:: El archivo HTML debe estar en codificación UTF-8. Si el HTML mezcla ISO-8859-1 / Windows-1252, parte del contenido puede no visualizarse correctamente. En caso de duda, se recomienda siempre utilizar **UTF-8** al generar HTML. Enviar un correo a un solo destinatario con html inline ------------------------------------------------------- .. image:: api25.png Esta llamada va a devolver un **eeid** (Envío efectivo ID), mediante el cual podremos consultar los eventos que se produjeron. Enviar un correo a más de un destinatario con html uri ------------------------------------------------------ .. image:: api26.png .. warning:: Al enviar a varios, se cambia **contacto** (JSON único) por **contactos** (lista [ ] de JSONs con email y opcionalmente nombre y apellido). Esta llamada va a devolver un **eeid** (Envío efectivo ID). Enviar un correo a más de un destinatario con html inline --------------------------------------------------------- .. image:: api27.png Esta llamada va a devolver un **eeid** (Envío efectivo ID). APIKEYs de campañas ------------------- Con ``campania_apikey`` se puede obtener una APIKEY con **GET**, o asignar una nueva con **POST**. Un usuario SMTP-API puede ser por ejemplo: ``dmdsid-12345`` y clave = apikey Listar campañas --------------- .. image:: api16.png También se pueden filtrar campañas por tipo: .. code-block:: bash curl -X GET "https://api-dmds-host/v1/campania/" -H "accept: application/json" -H 'Authorization: xxxxxxxx' -d '{"tipo":"api"}' o solo listar una campaña: .. code-block:: bash curl -X GET "https://api-dmds-host/v1/campania/" -H "accept: application/json" -H 'Authorization: xxxxxxxx' -d '{"tipo":"api","numid":1234}' .. warning:: Con esta llamada **no** se listan APIKEYs — para eso se usa ``campania_apikey``. Crear una campaña ----------------- .. image:: api18.5.png .. image:: api18.png La creación devuelve ``id`` y ``numid``. La campaña tipo **API** devuelve además **camp_apikey**. Crear un grupo -------------- .. image:: api28.png Listar los filtros ------------------ .. image:: api29.png Listar las variables globales y sus valores ------------------------------------------- .. image:: api30.png Crear variables globales ------------------------ .. image:: api31.png Borrar variables globales ------------------------- .. image:: api32.png Uso de Reply-To, Cc y Bcc ------------------------- Reply-To: .. code-block:: json {"reply-to": "usuario@dominio.com"} .. note:: El reply-to es un único item. No se usa alias para ocultar un correo, por razones de seguridad y trazabilidad. Cc: .. code-block:: json { "copia":[{ "cc_email":"usuario1@gmail.com", "cc_nombre":"Usuario1", "cc_apellido":"Apellido1"}] } .. note:: En ``copia`` va siempre una lista [ ] — solo **cc_email** es obligatorio. Bcc (copia oculta): .. code-block:: json { "copia_oculta": [ {"bcc_email":"usuario5@gmail.com"}, {"bcc_email":"usuario7@outlook.com"} ] } Mensajes de respuesta JSON -------------------------- Se deberán chequear códigos HTTP: * 200 – OK * 403 – Forbidden (APIKEY incorrecta) * 4xx – errores de datos (parametros faltantes, email inválido, etc.) .. code-block:: bash curl -X POST 'https://api-dmds-dmdsid.planisys.net/v1/contacto/' --header 'accept: application/json' ... Devuelve: .. code-block:: json {"status":"err","on":"invalid email ..."} Uso del Remitente y el Return-Path ---------------------------------- .. En el DMDS web se listan los dominios permitidos. Se provee un Return-Path acorde, por ejemplo: ``dmds-dom1@nl.dom1.com`` para que rebotes puedan ser procesados automáticamente.