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:
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:
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:
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:
{"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.
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.
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:
devuelve en caso de no estar en lista blanca:
{"status":"ok","msg":"usuario@dominio.com not whitelisted"}
y devuelve en caso de estar en lista blanca:
{"status":"ok","msg":"usuario@dominio.com whitelisted"}
Agregar a lista blanca con POST o PUT :
Quitar de lista blanca con DELETE
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.
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
{
"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).
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
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
Invalidar un contacto (introducido en v1.1)
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:
{"status":"ok","msg":"whitelisted"}
Revalidar un contacto (introducido en v1.1)
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¡:
{"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.
Esta llamada va a devolver un eeid (Envío Efectivo ID), mediante el cual podemos consultar los eventos que se produjeron (ver Consulta Eventos).
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.
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.
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 ]
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
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.
Tambien se puede filtrar para que liste los campañas tipo api, normal o bulk
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:
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
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.:
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.
{"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.
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.
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.
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.
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
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:
{"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:
{ "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:
{ "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
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
{"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
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
{"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
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
{"status":"err","on":"invalid email Internationalized characters before the @-sign are not supported."}
Este es un caso de un dominio inexistente
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
{"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:
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
{"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.
Actualizado en 2024-05-01