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 metodo ``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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Este metodo ``ver_eventos`` permite paginar con largo de pagina variable mayor o igual a 10, y elegir de una pagina los eventos que se hayan presentado entre dos fecha-horas determinados. Lleva cuatro parametros: Ejemplo: .. image:: api3.png .. warning:: Los parametros **pagina** y **cantidad** dentro del JSON, deben ser numericos. Consulta Eventos ---------------- La respuesta al envio de mails puede contener un codigo 4xx , para el cual el usuario debera¡ tener analizar el error (p.ej. falta de un parametro). En caso de funcionar correctamente un envio, 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 (*envio_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 envio efectivo fue efectuado con **archive**:**true** , el JSON devuelve una seccion llamada ``archive`` con la informacion de la traza del envio 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 *L$ 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, por ejemplo. 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 informacion de un contacto ----------------------------------- En este ejemplo se ve como devolver la informacion de un contacto en concreto. En la llamada, en la url, hay que especificar el email del usuario ya existente en la base de datos de la api. Asi de esta manera, se nos presentara¡ toda la informacion de un contacto, como su nombre, apellido, a que **Base** o grupo pertenece, sus eventos, etc. .. 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": "fdkslafjkdsjafdjsakjfdsa@hotmail.com", "nombre": "Juan", "apellido": "Pérez", "edad": null, "sexo": "M", "profesion": "", "localidad": "", "operacion": "Modificacion", "actualizado": "2020-10-15T08:25:32", "origenes": "", "codigo_pais": "", "codigo_region": "", "ciudad": "", "dispositivo": "web", "subtipo_dispositivo_id": null, "grupo_de_dominio_id": 0, "invalido": true, "campos": [ { "nombre": "XYZDNIXYZ", "valor": "21232421" }, { "nombre": "XYZEMPLEADORXYZ", "valor": "Planisys" }, { "nombre": "XYZEMPLEADOR2XYZ", "valor": "AvasCloud" }, { "nombre": "XYZTELCELXYZ", "valor": "+34999111333" } ], "eventos": [ { "evento": "envio", "timestamp": "2020-10-15T08:25:11", "campania": "VIMS " }, { "evento": "envio", "timestamp": "2020-10-15T08:25:16", "campania": "VIMS " }, { "evento": "envio", "timestamp": "2020-10-15T08:25:18", "campania": "VIMS " }, { "evento": "envio", "timestamp": "2020-10-15T08:25:29", "campania": "VIMS " }, { "evento": "rebote_hard", "timestamp": "2020-10-15T08:25:32", "campania": "VIMS " }, { "evento": "rebote_hard", "timestamp": "2020-10-15T08:30:08", "campania": "VIMS " } ], "grupos": [ "Origen API" ], "campanias": [], "campanias_desusc": [] } } Listar contactos invalidos -------------------------- Con esta llamada se nos mostraran todos los contactos que estan invalidos (es decir que por causa de rebotes o Feedback loops de Spam han sido invalidados). .. image:: api14.png Crear de nuevo o actualizar un contacto --------------------------------------- Con la siguiente llamada se puede crear un contacto de nuevo o actualizar uno existente. La primera variable que se define es el correo electrónico, para entenderlo es como una primary key en la base de datos. Siempre para actualizar algún contacto nos basaremos en su email ya que es único. En la parte de datos definimos diferentes atributos, que pueden definir un contacto. Todos esos campos se pueden ir cambiando a medida que el contacto cambia alguno de los valores. Para especificar qué usuario queremos modificar usaremos su email. 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 insertara un **Evento** de ``Invalidacion`` con el timestamp cuando ocurrio³ la invalidacion. Al estar el contacto como *invalido*, todo intento de enviarle e-mail directo o en copia, hace aparecer un evento de ``Not-Sent`` (no enviado). .. note:: Esta es una llamada **GET** En v1.3 , al agregarse el whitelisting puede cambiar la respuesta a la llamada diciendo que no es posible invalidar un contacto en lista blanca, primero se lo debe remover de la lista blanca, y no se agregará el evento: .. 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 cuando ocurrió la revalidación. Si el contacto era válido, sigue siendo válido. Si estaba invalidado, quedará invalidado a partir de ahora nuevamente. .. note:: Esta es una llamada **GET** De manera similar a ``invalidar`` , en ``revalidar`` no se insertara un evento de ``Revalidacion`` en caso de estar el mail en lista blanca, y devolvera¡: .. 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 tiene que ser siempre verdadero, ya que esto nos permite enviar el correo. Si este valor está en falso, no se podrán enviar mensajes. Otros$ 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 a los códigos 301 y 302 para redirección hasta llegar a un código 200 y obtener la página. .. warning:: El archivo HTML se espera en codificación o charset UTF-8 , de manera que si el HTML contiene caracteres mezclados de windows-1252 o iso-8859-1 p.ej. , puede ser que parte del contenido no se muestre correctamente. En caso de dudas respecto de la codificación de ciertos caracteres o manipulación multi-plataforma que mezcle varias codificaciones en un mismo HTML , recomendamos utilizar las codificaciones de caracteres internacionales standard de HTML en esta página. Enviar un correo a un solo destinatario con html inline ------------------------------------------------------- La diferencia de la llamada previa esta es como definir el html dentro del codigo. .. image:: api25.png Esta llamada va a devolver un **eeid** (Envio Efectivo ID), mediante el cual podemos consultar los eventos que se produjeron (ver Consulta Eventos). Enviar un correo a mass de un destinatario con html uri ------------------------------------------------------ Para esta llamada vamos a seguir el mismo concepto que para las otras a la hora de enviar un mensaje. En este caso queremos enviar a mucho destinatarios, para esto vamos a definir un array de contactos que quienes queremos enviar y cambiar **contacto** por **contactos**. En el ejemplo que se muestra más abajo, enviamos un correo a dos personas, pero su puede definir muchas más personas. .. warning:: Al enviar a varios, se cambia *contacto* (un JSON con email, y opcionalmente nombre y apellido), por **contactos** que es una **LISTA** de jsons y va entre corchetes cuadrados [ y ] .. image:: api26.png Esta llamada va a devolver un **eeid** (Envio Efectivo ID), mediante el cual podemos consultar los eventos que se produjeron (ver Consulta Eventos). .. warning:: Como algunas de las direcciones de mail pueden ser incorrectas, puede ser que el numero de mails enviados que figura en el json de respuesta bajo **sent** sea menor al numero de recipientes especificados Enviar un correo a mas de un destinatario con html inline --------------------------------------------------------- .. image:: api27.png Esta llamada va a devolver un eeid (Envio Efectivo ID), mediante el cual podemos consultar los eventos que se produjeron (ver Consulta Eventos). APIKEYs de campañas -------------------- Con el metodo ``campania_apikey`` se puede especificar un numid con metodo HTTP **GET** , y obtener la APIKEY de la campaña si es que tiene una asignada y es tipo api. A su vez , se puede setear una apikey con el metodo **POST** y el argumento "apikey". De esta manera, se podra utilizar en SMTP-API un usuario p.ej. dmdsid-12345 y clave el valor de apikey. Listar campañas --------------- Con la misma estructura, como listar los contactos invalidos o listar las variables globales, podemos listar todas las campañas existentes. Para esto se utiliza el metodo get. .. image:: api16.png Tambien se puede filtrar para que liste los campañas tipo ``api``, ``normal`` o ``bulk`` .. code-block:: bash curl -X GET "https://api-dmds-host/v1/campania/" -H "accept: application/json" -H 'Authorization: xxxxxxxx' -d '{"tipo":"api"}' Otro filtro que se puede aplicar, es el de listar unicamente una campaña por su numid, cuando se quiere ver una en particular: .. 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 las APIKEYs de campañas, para eso se utiliza el metodo ``campania_apikey`` Crear una Campaña ----------------- Con el metodo **/v1/campania/** en modo ``POST`` se puede crear una campana tipo **api** o **normal** La creacion devuelve siempre el id y el numid, mas una apikey en el caso API, que se pueden usar en llamadas subsiguientes, p.ej. para enviar un mail. Al obtener una **apikey** , se puede tambien utilizar **SMTP-API** con un nombre de usuario dmdsid-campnumid, y clave apikey, para el caso de aplicaciones que requieran configurar SMTP con autenticacion, dando esto la posibilidad de asignar un par username/password a una campaña determinada. Para crear una normal, luego se debe entrar a la interfaz web y completar la creacion del **envio** .. image:: api18.5.png La campañas tipo api requiere de mas parametros, de los cuales solo ``replyto`` es opcional , crea un **envio** unico y permite enviar mails bajo el numid retornado p.ej.: .. image:: api18.png Si en el asunto va ``XYZTAG-CURLXYZ`` , entonces el metodo requiere del parametro asunto_uri , porque va a ser un asunto dinamico. Si se prefiere, se puede poner un asunto estatico fijo, y obviar asunto_uri. Tanto el remitente como el asunto y la url de la pieza de mail son defaults, es decir se pueden sobreescribir al momento de enviar emails bajo el numid de campaña. La llamada retorna un json conteniendo un ``numid`` para subsiguientes llamadas, p.ej. .. code-block:: json {"status":"ok","id":"66bfae5b-3b6f-4bc9-a563-f62d5a9812a3","numid":68235,"camp_apikey":"a62d247c345fe31d0cda39ba1c3d3501"} .. warning:: Actualmente no se permite modificar la campaña creada, teniendo en cuenta que los metodos como send_one_inline y send_one_uri sobreescriben los defaults de la campaña. Crear un grupo -------------- Como hemos visto anteriormente, cuando creamos o modificamos un contactos podemos asignarle un grupo (tambien conocido como **base**). Para poder asignar un grupo, hay que ver si este grupo existe. Si no existe, podemos crearlo de la siguiente manera. .. image:: api28.png Listar los filtros ------------------ En el sistema de la api, se pueden crear diferentes filtros, que ayudan a especificar los envíos. Para ver esta lista de filtros existentes, seguimos el código mencionado abajo. .. image:: api29.png Listar las variables globales y sus valores ------------------------------------------- En la api hay definidas una serie de variables globales. Para ver cuales son estas variables y sus valores podemos ver el siguiente código. .. image:: api30.png Crear variables globales ------------------------ Siempre podemos crear las variables globales. Para la creacion vamos a usar el método POST, donde le pasamos un variable, cual nos va a indicar el nombre de la variable global. .. image:: api31.png Borrar variables globales ------------------------- De la misma manera que creamos unas variables globales, podemos eliminar estas. Solo que en este vamos a usar un metodo que se llama ``DELETE`` .. image:: api32.png Uso de Reply-To, Cc y Bcc ------------------------- En las llamadas send_one_inline y send_one_uri , se pueden agregar dentro del JSON principal: Reply-To: .. code-block:: json {"reply-to": "usuario@dominio.com"} .. note:: El reply-to es un unico item, y no se utiliza un nombre que oculte la direccion de mail por razones de seguridad y transparencia Cc: .. code-block:: json { "copia":[{ "cc_email":"usuario1@gmail.com", "cc_nombre":"Usuario1", "cc_apellido": "Apellido1"}] } .. note:: en el caso copia, va una lista entre [] de posible destinatarios de copia. Solo el cc_email es mandatorio. En caso de querer mandar copia oculta , se debe agregar: .. code-block:: json { "copia_oculta": [ { "bcc_email":"usuario5@gmail.com"}, {"bcc_email:"usuario7@outlook.com"} ] } Mensajes de respuesta JSON -------------------------- Si bien a nivel de CURL no se ve el codigo de respuesta, en los lenguajes de programacion cuando se quiere chequear la respuesta, se deberan chequear * HTTP Code 200 - OK * HTTP Code 403 - Forbiden (usualmente APIKEY equivocada) * HTTP Code 4xx - Errores de datos, tales como falta de algun parametro en el JSON de entrada, como direcciones incorrectas Se debe tener en cuenta que, en las llamadas send_one_inline y send_one_uri , asi como en la introduccion de un nuevo contacto, se hace un chequeo de la validez de la direccion de mail. Ejemplos: En este caso se chequea la validez de la sintaxis de un dominio de Internet .. code-block:: bash curl -X POST 'https://api-dmds-dmdsid.planisys.net/v1/contacto/' --header 'accept: application/json' --header 'Authorization: 11111111111113243433' --header 'Content-Type: application/json' --data '{"email": "ifdjsahfjdsaf@gmail"}' Devuelve .. code-block:: json {"status":"err","on":"invalid email The domain name gmail is not valid. It should have a period."} En este caso se chequea que haya una sola @ en cada direccion de mail .. code-block:: bash curl -X POST 'https://api-dmds-dmdsid.planisys.net/v1/contacto/' --header 'accept: application/json' --header 'Authorization: 11111111111113243433' --header 'Content-Type: application/json' --data '{"email": "@-@gmail"}' Devuelve .. code-block:: json {"status":"err","on":"invalid email The email address is not valid. It must have exactly one @-sign."} Este es un caso de caracteres internacionales no permitidos en direcciones de mail .. code-block:: bash curl -X POST 'https://api-dmds-dmdsid.planisys.net/v1/contacto/' --header 'accept: application/json' --header 'Authorization: 11111111111113243433' --header 'Content-Type: application/json' --data '{"email": "josépérez@gmail.com"}' Devuelve .. code-block:: json {"status":"err","on":"invalid email Internationalized characters before the @-sign are not supported."} Este es un caso de un dominio inexistente .. code-block:: bash curl -X POST 'https://api-dmds-dmdsid.planisys.net/v1/contacto/' --header 'accept: application/json' --header 'Authorization: 11111111111113243433' --header 'Content-Type: application/json' --data '{"email": "juanperez@gmail.com", "remitente":"jose@escuelaxyz.com", "remitente_nombre":"PLANICóRP"}' Devuelve .. code-block:: json {"status":"err","on":"remitente invalido The domain name escuelaxyz.com does not exist."} En este caso, el dominio remitente no esta declarado en la web del DMDS, es decir no es un dominio permitido para este DMDS en particular: .. code-block:: bash curl -X POST 'https://api-dmds-dmdsid.planisys.net/v1/contacto/' --header 'accept: application/json' --header 'Authorization: 11111111111113243433' --header 'Content-Type: application/json' --data '{"email": "juanperez@gmail.com", "remitente":"jose@gmail.com", "remitente_nombre":"PLANICóRP"}' Devuelve .. code-block:: json {"status":"err","on":"dominio remitente no permitido"} Uso del Remitente y el Return-Path ---------------------------------- En el DMDS web se listan los dominios permitidos para ser usados como remitentes. En el ejemplo anterior se vio que la API REST v1 rechaza el remitente como no permitido porque el dominio a la derecha de la @ no figura en su lista. Lo que debe ser tenido en cuenta, es que en el DMDS Web, por cada dominio permitido, se lista un return-path apropiado para lectura de rebotes. P.ej. si el dominio remitente es dom1.com, probablemente tendremos *dmds-dom1@nl.dom1.com* como direcciôn de **Return-Path** diferente del encabezado **From:** que sera p.ej. *usuario@dom1.com*. Estos datos se dan de alta en el aprovisionamiento del DMDS, y se pueden cambiar en la medida que se quiten y agreguen dominios. El objetivo del Return-Path siendo un subdominio del dominio principal, es via el registro DMARC tener un Return-Path valido y que sirva para dirigir rebotes a una casilla que el DMDS pueda procesar de manera automática. .. |date| date:: Actualizado en |date|