DMDS API REST v1.5 Documentation using Postman
En todos los ejemplos reemplazar XXXXXXXXXXX por el nombre del DMDS dedicado, y APIKEY o Authorization por el hash secreto.
Example:
Download Postman for Windows
Changes from v1.4 to v1.5: number of events and paginated events
Se agrega el método cantidad_eventos para obtener la cantidad de eventos entre dos fechas determinadas.
Events between dates with pagination
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:
Example:
Warning
Los parámetros pagina y cantidad dentro del JSON, deben ser numéricos.
Event Query
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.
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 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.
Changes from v1.3 to v1.4: archiving of sent emails (requires archiving license)
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.
Additionally, for archived emails, the eeid_eml method is added, which allows the return of the email text sent in an effective send to one of the recipients.
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.
Changes from v1.2 to v1.3 - Whitelisting
Se agrega el método whitelist que permite preguntar si un contacto está en whitelist, agregarlo o quitarlo de la misma.
The whitelist serves to immunize a contact so that they are not invalidated by a possible bounce due to a failure or confusing message from the receiving MTA.
It also protects them from a possible unsubscribe/invalidation process that could be done based on bounce processing.
Changes from v1.1 to v1.2 - API version
Se agrega el método version que devuelve el número de versión de la API.
Get API Version
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.
Changes from v1.0 to v1.1 - Revalidate and Invalidate
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.
The Not-Sent event is also added for cases where an email is attempted to be sent to an invalid contact. This event is displayed in this version as unknown in the API, and as Not-Sent in the Mtmail web interface.
Event viewing is compatible with the https://mtmail.planisys.net application, which will replace the dmds-xxxxxxxxxxx.planisys.net applications soon.
Contact Whitelist
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.
Check if it is on the whitelist with GET:
returns if not on the whitelist:
{"status":"ok","msg":"usuario@dominio.com not whitelisted"}
and returns if it is on the whitelist:
{"status":"ok","msg":"usuario@dominio.com whitelisted"}
Add to the whitelist with POST or PUT:
Remove from the whitelist with 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
Create or update a contact
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).
Associate one or more bases with a new or existing contact
Note
A source or base is the same as a group. It is the name of a contact base. A contact can be part of several bases (groups).
Set field values for a new or existing contact
Invalidate a contact (introduced in 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.
Note
This is a GET call
{"status":"ok","msg":"whitelisted"}
Revalidate a contact (introduced in v1.1)
Se insertará un Evento de Revalidación con el timestamp correspondiente.
Note
This is a GET call
{"status":"ok","msg":"whitelisted"}
Send an email to a single recipient with 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.
In the headers section, remember to define your authorization value.
This call will return an eeid (Effective Send ID), through which we can check the events that occurred (see Event Query).
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.
Send an email to a single recipient with inline html
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
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
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
List campaigns
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}'
Warning
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.
Create a group
List filters
List global variables and their values
Create global variables
Delete global variables
Use of Reply-To, Cc, and Bcc
Reply-To:
{"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:
{ "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):
{
"copia_oculta": [
{"bcc_email":"usuario5@gmail.com"},
{"bcc_email":"usuario7@outlook.com"}
]
}
JSON Response Messages
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 ..."}
Use of Sender and 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.