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
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.
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:
Aviso
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:
{"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.
Aviso
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
Aviso
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.
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 información de un contacto
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": "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
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
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
Invalidar un contacto (introducido en v1.1)
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.
Nota
Esta es una llamada GET
{"status":"ok","msg":"whitelisted"}
Revalidar un contacto (introducido en v1.1)
Se insertará un Evento de Revalidación con el timestamp correspondiente.
Nota
Esta es una llamada GET
{"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.
Esta llamada va a devolver un eeid (Envío Efectivo ID), mediante el cual podemos consultar los eventos que se produjeron (ver Consulta Eventos).
Nota
Al especificar una URL, la API REST sigue redirecciones 301/302 hasta obtener finalmente un código 200 y la página.
Aviso
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
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
Aviso
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
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
También se pueden filtrar campañas por tipo:
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:
curl -X GET "https://api-dmds-host/v1/campania/" -H "accept: application/json" -H 'Authorization: xxxxxxxx' -d '{"tipo":"api","numid":1234}'
Aviso
Con esta llamada no se listan APIKEYs — para eso se usa campania_apikey.
Crear una campaña
La creación devuelve id y numid. La campaña tipo API devuelve además camp_apikey.
Crear un grupo
Listar los filtros
Listar las variables globales y sus valores
Crear variables globales
Borrar variables globales
Uso de Reply-To, Cc y Bcc
Reply-To:
{"reply-to": "usuario@dominio.com"}
Nota
El reply-to es un único item. No se usa alias para ocultar un correo, por razones de seguridad y trazabilidad.
Cc:
{ "copia":[{ "cc_email":"usuario1@gmail.com", "cc_nombre":"Usuario1", "cc_apellido":"Apellido1"}] }
Nota
En copia va siempre una lista [ ] — solo cc_email es obligatorio.
Bcc (copia oculta):
{
"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.)
curl -X POST 'https://api-dmds-dmdsid.planisys.net/v1/contacto/' --header 'accept: application/json' ...
Devuelve:
{"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.