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:

../_images/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:

../_images/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:

../_images/api3.png

Advertencia

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.

Advertencia

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.

../_images/api33.png

Pueden figurar otros eventos como rebote-soft , rebote-hard, click o view

Advertencia

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.

../_images/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:

../_images/api6.png

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 :

../_images/api7.png

Quitar de lista blanca con DELETE

../_images/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.

../_images/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

{
    "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).

../_images/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

../_images/api10.png

Nota

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

../_images/api11.png

Invalidar un contacto (introducido en v1.1)

../_images/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).

Nota

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)

../_images/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.

Nota

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.

../_images/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).

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.

../_images/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.

Advertencia

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 ]

../_images/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).

Advertencia

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

../_images/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.

../_images/api16.png

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}'

Advertencia

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

../_images/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.:

../_images/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.

{"status":"ok","id":"66bfae5b-3b6f-4bc9-a563-f62d5a9812a3","numid":68235,"camp_apikey":"a62d247c345fe31d0cda39ba1c3d3501"}

Advertencia

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.

../_images/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.

../_images/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.

../_images/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.

../_images/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

../_images/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:

{"reply-to": "usuario@dominio.com"}

Nota

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"}] }

Nota

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