API Envío de EMAIL (7.0)

INTRODUCCION

API de integración de envío de mensajes EMAIL desde aplicaciones mediante peticiones https.

AUTENTICACIÓN

En su cuenta de usuario encontrará el Usuario API y el API Token, ambos son necesarios para realizar las peticiones API REST a las funciones de la API. Las Peticiones, por seguridad deben ralizarse en POST y con protocolo HTTPS Seguro.

Para utilizar la Autenticación Básica debe incluir una cabecera en las peticiones del tipo: Authorization: Basic Base64StringAPI donde Base64StringAPI es la codificación en Base64 de la cadena UsuarioAPI:APIToken, puede encontrar su Usuario API y API Token en su cuenta de usuario en Tus Datos -> Configurar Cuenta.

Para generar el string codificado en Base64, simplemente genere el string UsuarioApi:APIToken y codifíquelo en base64 mediante cualquier función base64encode.

A TENER EN CUENTA

Conexiones en vacío: Es importante tener en cuenta que una conexión errónea de forma repetida será tratada por el sistema como spam y podrá llegar a bloquear temporalmente la conexión. Es conveniente evitar realizar repetidas conexiones con datos erróneos o conexiones rápidas ‘en vacío’ (sin realizar envíos) con los mismos datos para obtener el número de créditos o el mismo report.

Para obtener reports de forma óptima en tiempo real se recomienda configurar la API en el panel para recibirlos en un script de su web.
Respuesta de las peticiones: La mayoría de las funciones disponen de un parámetro denominado ‘Resp’. Este parámetro define el formato de la respuesta que se devolverá. Puede ser TXT, JSON, XML o no definido. Se recomienda siempre definir este parámetro ya que todas las funciones, por compatibilidad con versiones anteriores de la API, responden por defecto (si no se define este parámetro) tal y como lo hacían en versiones antiguas. En estos resultados de versiones de API anteriores se obvian algunas de las variables que se incluyen en esta versión de la API y que consideramos importantes para facilitar la integración e información de la cuenta. En los ejemplos incluidos siempre se tiene en cuenta que ha definido el parámetro. Si está trabajando directamente con la API versión >= 5, asumiremos que ha definido el parámetro en todas las peticiones.
Validación del Dominio remitente: Antes de poder utilizar esta API, debe haber validado con su comercial asignado el dominio que va a utilizar como remitente y añadir los registros SPF y DKIM que le indiquemos a sus DNS. Esto permitirá al sistema enviar correctamente codificando el email para maximizar la entrega a destinatarios. También es conveniente que consulte con su comercial el proceso de calentamiento de las IPs de envío si va a realizar envíos masivos.
Funcionamiento recomendado: El funcionamiento recomendado, por ser el más sencillo y, a la vez, el más profesional es el siguiente:
- PROCESO 1: Envío de EMAIL : Descrito en la función EnviarEMAIL de este documento.
- PROCESO 2: Recepción automática de reports en su web (proceso descrito en el la sección 'Recepción de reports de entrega'.

Enviar Email

/EnviarEMAIL

Función de envío de mensajes Email desde aplicaciones. Definición de parámetros necesarios.

ATENCIÓN: Chequee la sección de recepción de reports en tiempo real si desea recibir el estado de los correos y las interacciones del destinatario en tiempo real en un script de su web.

query Parameters
Nombreremitente
string
Example: Nombreremitente=Mi nombre

Nombre del remitente del Correo.

Emailremitente
required
string
Example: Emailremitente=minombre@micorreo.com

Remitente del Correo. Debe ser un email válido y el dominio debe haber sido validado en su cuenta, añadido los registros SPF y DKIM en sus DNS y verificado funcionamiento.

Replyto
string
Example: Replyto=minombre@micorreo.com

Correo al que responderá el destinatario.

Destinatarios
required
Array of arrays
Example: Destinatarios=[{"Nombre":"Pedro Pérez","Email":"destinatario@eldominio.com","Variables":[{"Nombre":"Motivo","Valor":"Felicitarte"},{"Nombre":"Razon","Valor":"Tu 25 cumpleaños"]}]

Array JSON con los destinatario del correo. Puede añadir variables si desea personalizar Asunto y Mensaje por destinatario. Por ejemplo:


   [
    {
      "Nombre": "Pedro Aicart",
      "Email": "pedro@dominio.com",
      "Referencia": "12345678T",
      "Variables": [
          {
                "Nombre": "Accion",
                "Valor": "Transferencia"
         },
          {
                "Nombre": "Importe",
                "Valor": "10.000"
         },
     ]
    },
    {
      "Nombre": "Ana Aguado",
      "Email": "ana@empresa.com",
      "Referencia": "36578294H",
      "Variables": [
          {
                "Nombre": "Accion",
                "Valor": "Devolución"
         },
          {
                "Nombre": "Importe",
                "Valor": "127"
         },
      ]
    }
   ]
  

Asunto
required
string
Example: Asunto=Esto es un mensaje para ###Nombre### con motivo de ###motivo###

El asunto del correo electrónico

Plantilla
integer
Example: Plantilla=1234567

El Id de la plantilla que haya realizado dentro del panel de usuario. Es un parámetro opcional, puede enviar el HTML directamente en Mensaje o enviar este dato para referenciar la plantilla creada en el panel. Las variables dentro de la plantilla deben ser del tipo ###Variabel### que luego se personalizarán por destinatario. Ver parámetro Mensaje para revisar las variables reservadas.

Mensaje
string
Example: Mensaje=Contenido Html que se va a enviar

Mensaje que se enviará al/ a los destinatarios, es opcional, puede enviarse aquí el mensaje u optar por utilizar el parámetro Plantilla para enviar la plantilla correspondiente. Las variables dentro de la plantilla deben ser del tipo ###Variabel### que luego se personalizarán por destinatario. Hay variables reservadas que pueden utilizarse directamente en el HTML y que se actualizarán con los valores correspondientes, estos son:
###email### : Se cambiará por el email desl destinatario ###destinatario###: Nombre del destinatario ###__fechahora__###: Fecha/Hora del envío (CET) ###__fecha__###: Fecha del envío ###__hora__###: Hora del envío ###url_ver_en_web###: Se modificará por el link a la versión vista en web ejemplo: 'si Ud no ve correctamente este email pinche aquí'. Atencíon, la clase HideInWebView es una clase que permite, en nuestro sistema que, una vez que aparece en versión web, desaparezca ese contenido. Se suele usar para que, una vez que está en la versión web, no vuelva a aparecer ese mensaje evitando malentendidos.
###url_unsubscribe###: Es la Url de baja si desea que la gestionemos desde el sistema, se añadirá a su lista de bajas.
FUCIÓN ESPECIAL: Si desea que un elemento (div, span, p,...) no aparezca en la vista web (al pulsar en ver en web) , debe añadir a ese elemento la clase hiddeninwebsite class="hiddeninwebsite"

Fecha
string
Example: Fecha=2022-05-01 15:10

Fecha en la que queda programado el envío, el mensaje se enviará en esa fecha. Por defecto "" que significa enviar inmediatamente. Formato Año-Mes-dia hora:minuto. La referencia horaria es CET/CEST (Zona horaria de España).

Intervaloprohibido
Array of arrays
Example: Intervaloprohibido=[{"HoraInicio":"22:00","HoraFin":"9:00","Accion":"1"}]

Array JSON horas de inicio y fin del intervalo de envío prohibido.
Por ejemplo:


    {
      "HoraInicio": "22:00",
      "HoraFin": "8:00"
    },

Adjuntos
Array of arrays

Array en JSON con los adjuntos si desea incluirlos en el mensaje. Por ejemplo:


   [
    {
      "Nombre": "documento.pdf",
      "Contenido": "JVBERi0xLjcNJeLjz9MNCjg0IDAgb2JqDTw...."
    },
    {
      "Nombre": "otrodocumento.docx",
      "Contenido": "IyBleHBvcnRlZCBmcm9tIGJhY2ts....."
    }
   ]
  

Seguimientoaperturas
integer
Example: Seguimientoaperturas=1

Si se activa (1, por defecto) se realizará un seguimiento de las aperturas de los correos enviados, si se desactiva (0) no se hará seguimiento y no recibirá los reports de aperturas en la recepción de reports en su script.

Seguimientoclicks
integer
Example: Seguimientoclicks=1

Si se activa (1, por defecto) se realizará un seguimiento de locs clicks en los correos enviados, si se desactiva (0) no se hará seguimiento y no recibirá los reports de clicks en la recepción de reports en su script.

Listunsubscribe
string
Example: Listunsubscribe=List-Unsubscribe: <mailto:listrequest@dominio.com?subject=unsubscribe>, <https://dominio.com/unsubscribe/identific1234567>

Si envía a través de IPs certificadas CSA es obligatorio utilizar esta opción o listHelp. Se trata de una cabecera soportada por los principales gestores de correo y que permite la baja de destinatarios con un click. Si desea que se gestione de forma automática, déjelo en un espacio en blanco o el carácter '-' (signo menos)

Listhelp
string
Example: Listhelp=List-Help: <https://www.dominio.com/landing/listhelp>, <mailto:list-info@cominio.com>

Si envía a través de IPs certificadas CSA es obligatorio utilizar esta opción o listUnsubscribe. Se trata de una cabecera soportada por los principales gestores de correo y que permite indicar una landing donde el destinatario pueda informarse del motivo de estar recibiendo este correo y, si no puede darse de baja (por ejemplo porque sean mensajes OTP o transaccionales/operativos, de los motivos de recibirlos.

Referenciausuario
string
Example: Referenciausuario=Tu referencia

Parámetro que se utiliza como referencia de toda la campaña para el usuario. Si se selecciona recibir el report en una URL, recibirá este parámetro en el resultado del envío y también la referencia de cada uno de los destinatarios si la ha indicado en el array de usuario.

Report
integer
Example: Report=0

Si desea recibir reports en un script de su web (activando en panel de usuario la configuración API).

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
>0 Número de mensajes enviados.
-1 Error de autenticación.
-2 No hay créditos suficientes.
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-4 Fichero adjunto no permitido.
-5 No dispone de créditos suficientes.

Error
string

En caso de Res -3 , obtendrá un error descriptivo del problema en este parámetro.

idEnvio
integer

identificador de la campaña, es equivalente a idCampaign recibido en el report y que se mantiene por compatibilidad con versiones anteriores.

Destinatarios
integer

Número de destinatarios enviados.

Enviados
Array of arrays

Datos de los destinatarios en un array en el que se añade idMensaje por cada destinatario. El idMensaje es el Identificador del mensaje. Sirve, por ejemplo, como identificación para obtener el report del mensaje enviado. Se recibirá en las peticiones si activa la recepción de reports en tiempo real en un script de su web/servidor.

NoEnviados
Array of arrays

Destinatarios erróneos/no enviados.

Duplicados
integer

Número de destinatarios no enviados debido a que estaban duplicados.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/EnviarEMAIL' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Emailremitente="minombre@micorreo.com"' \ 
--form 'Destinatarios="[{\"Nombre\":\"Pedro Pérez\",\"Email\":\"destinatario@eldominio.com\",\"Variables\":[{\"Nombre\":\"Motivo\",\"Valor\":\"Felicitarte\"},{\"Nombre\":\"Razon\",\"Valor\":\"Tu 25 cumpleaños\"]}]"' \ 
--form 'Asunto="Esto es un mensaje para ###Nombre### con motivo de ###motivo###"' \ 

Response samples

Content type
[
  • {
    }
]

Recepción de reports de entrega y cambios de estado de mensajes enviados

https://{SuDominio}/path/de/su/script/de/recepción/de/reports

RECEPCIÓN EN TIEMPO REAL DE LOS ESTADOS DE ENTREGA EN UN SCRIPT DE SU SERVIDOR. Activando la opción de recibir los reports en tiempo real en un script en su servidor desde su panel de usuario, recibirá una petición POST con el formato indicado cada vez que cada mensaje enviado cambie de estado. Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORM-DATA

Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Tipo de report que está recibiendo (el objetivo es distinguir entre los reports de los diferentes servicios). Los servicios a los que se refiere esta especificación puede recibir EMAILTRANSACCIONAL Si el servicio se refiere a un report de un EMAIL Transaccional

Estado
required
integer

Estado de la notificación enviada. Los estados posibles son:

ESTADO DESCRIPCION SIGNIFICADO
`10` Apertura Registrada Se ha producido una apertura del correo enviado.
`11` Entregado al destinatario El EMAIL ha sido entregado. Si se trata de un Email Certificado, dispone de un certificado en formato PDF con sellado de Tiempo. El sistema seguirá grabando las interacciones.
`12` Lectura/Acceso al contenido Significado:El destinatario ha accedido a la lectura del contenido de la notificación.
`13` Entregado, acceso y descarga Significado: El destinatario ha recibido la notificación por correo electrónico, la ha abierto, se ha registrado la lectura y, adicionalmente, ha descargado los adjuntos enviados.
`14` El destinatario ha respondido Significado: Hemos registrado una respuesta por parte del destinatario. Si se trata de un Email Certificado, puede certificar la respuesta solicitando una adenda certificada.
`15` El destinatario ha abierto el mensaje Significado: Hemos registrado una apertura del destinatario.
`16` Entregado, abierto y aceptado Significado: (Sólo certificados) Se ha solicitado la aceptación de la notificación y el destinatario la ha abierto y aceptado.
`17` Entregado, abierto y rechazada Significado: (Sólo certificados) Se ha solicitado la aceptación de la notificación y el destinatario la ha abierto y rechazado.
`18` Entregado y abierto. Expirado Significado: (Sólo certificados) Se ha solicitado la aceptación de la notificación y el mensaje ha expirado sin ser aceptado.
`19` Entregado y expirado Significado: (Sólo certificados) Se ha solicitado la aceptación de la notificación y el mensaje ha expirado sin ser aceptado.
`28` Error temporal en destino Significado: Hay un error temporal en destino (por ejemplo buzón lleno).
`29` Mensaje Cancelado Significado: El mensaje ha sido cancelado por el usuario antes de su envío.
`50` El mensaje no puede entregarse Significado: Ha ocurrido un error en destino. Por ejemplo que el destinatario no existe.
`51` Dominio Inexistente Significado: Ha ocurrido un error en destino. El dominio no existe.
`52` Formato dirección incorrecta Significado: Ha ocurrido un error en destino. La dirección destino no es correcta.
`53` Notificación Expirada Significado: El EMAIL No ha podido ser entregado, la notificación está expirada.
`54` Buzón lleno Significado: El EMAIL No ha podido ser entregado, buzón destino lleno.
`55` La dirección no existe Significado: El servidor destino indica que el buzón no existe.
`56` Mensaje rechazado Significado: El destinatario ha marcado el mensaje como SPAM.
`57` Duplicado Significado: Mensaje duplicado en la campaña.
`58` Usuario dado de baja Significado: El usuario ha sido dado de baja del servidor destino.
`59` Fuera de oficina Significado: el buzón está configurado como fuera de oficina.
`60` Error reiterado Significado: Tras varios intentos de entrega, el buzón destino sigue indicando un error temporal.
`101-120` Click Significado: El destinatario ha abierto el mensaje y ha hecho click en el link número 1-20 (número por orden de aparición en el html) .
`999` Se está reintentando. Significado: El EMAIL se ha intentado entregar al servidor destino y ha habido un problema, se está reintentando.
`1000` El EMAIL ha sido enviado. Significado: El EMAIL ha sido enviado, se está intentando entregar al servidor destino.
`1001` EMAIL Programado Significado: En mensaje ha sido programado y se entregará a la hora indicada.
`1002` EMAIL en proceso de envío Significado: Se está procediendo al envío del mensaje.
`1003` Reintentando Significado: Ha habido un problema en destino, el sistema está reintentando.
Remitente
required
string

Remitente utilizado en el envío.

Destinatario
required
string

Correo del destinatario al que se refiere el report.

RefCampaign
required
string

Referencia genérica de la campaña. Es la referencia genérica que ha indicado en el envío

RefMensaje
required
string

Referencia específica del destinatario. Es la referencia que ha indicado en el envío para este destinatario

Fecha
required
string

Fecha del report

idCampaign
required
integer

Identificador único recibido como respuesta en la función de envío (idEnvio recibido en la función de envío)

idMensaje
required
integer

Identificador único recibido como respuesta en la función de envío (idMensaje recibido en la función de envío)

Aperturas
required
integer

Número de aperturas registradas en el mensaje

IP
required
string

Dirección IP desde la que se realiza la última apertura

Dispositivo
required
integer

Tipo de dispositivo con el que se realiza la apertura

DISPOSITIVO DESCRIPCION
`0` Sin Apertura
`1` Otros
`2` Ordenador
`3` Teléfono
`4` Tablet
`5` Consola
`6` TV
`7` Reproductor portable
SistOperativo
required
integer

Tipo de sistema operativo detectado en destino (en aperturas)

SIST. OPERATIVO DESCRIPCION
`0` Sin Apertura
`1` Otros
`2` Android
`3` Windows
`4` Apple IOS
`5` Mac OSX
`6` Linux/Unix

Request samples

Content type
{
  • "Servicio": "EMAILTRANSACCIONAL",
  • "Estado": 11,
  • "Remitente": "tucorreo@tudominio.com",
  • "Destinatario": "destino@dominio.com",
  • "RefCampaign": "12333-4545-23233",
  • "RefMensaje": "12345678T",
  • "Fecha": "2020-12-03 11:14:24",
  • "idCampaign": 10573758,
  • "idMensaje": 33434444443,
  • "Aperturas": 1,
  • "IP": "10.10.20.200",
  • "Dispositivo": 2,
  • "SistOperativo": 3
}