API de integración de envío de mensajes EMAIL desde aplicaciones mediante peticiones https.
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.
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'.
Autenticación HTTP Basic. Use su Usuario API como usuario y su API Token como contraseña (los encuentra en su panel, en Tus Datos → Configurar Cuenta). El header resultante es Authorization: Basic base64(UsuarioAPI:APIToken). La mayoría de las librerías HTTP lo construyen automáticamente (curl -u, requests auth=, basic_auth de Ruby, etc.) sin necesidad de codificar el base64 a mano.
basicFunció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.
| 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:
|
| 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:
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 |
| 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:
|
| Adjuntos | Array of arrays Array en JSON con los adjuntos si desea incluirlos en el mensaje. Por ejemplo:
|
| 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=<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 gestionen las bajas de forma automática, deje este parámetro y ListHelp en blanco |
| Listhelp | string Example: Listhelp=<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.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Nombreremitente | string |
| Emailremitente required | string |
| Replyto | string |
| Destinatarios required | Array of any |
| Asunto required | string |
| Plantilla | integer |
| Mensaje | string |
| Fecha | string |
| Intervaloprohibido | Array of any |
| Adjuntos | Array of any |
| Seguimientoaperturas | integer |
| Seguimientoclicks | integer |
| Listunsubscribe | string |
| Listhelp | string |
| Referenciausuario | string |
| Report | integer |
| Resp | string |
| Res required | integer <int32> Respuesta de la función solicitada
|
| 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. |
{- "Nombreremitente": "Mi nombre",
- "Emailremitente": "minombre@micorreo.com",
- "Replyto": "minombre@micorreo.com",
- "Destinatarios": "[{\"Nombre\":\"Pedro Pérez\",\"Email\":\"destinatario@eldominio.com\",\"Variables\":[{\"Nombre\":\"Motivo\",\"Valor\":\"Felicitarte\"},{\"Nombre\":\"Razon\",\"Valor\":\"Tu 25 cumpleaños\"]}]",
- "Asunto": "Esto es un mensaje para ###Nombre### con motivo de ###motivo###",
- "Plantilla": "1234567",
- "Mensaje": "Contenido Html que se va a enviar",
- "Fecha": "2022-05-01 15:10",
- "Intervaloprohibido": "[{\"HoraInicio\":\"22:00\",\"HoraFin\":\"9:00\",\"Accion\":\"1\"}]",
- "Adjuntos": [
- null
], - "Seguimientoaperturas": "1",
- "Seguimientoclicks": "1",
- "Listunsubscribe": "<mailto:listrequest@dominio.com?subject=unsubscribe>, <https://dominio.com/unsubscribe/identific1234567>",
- "Listhelp": "<https://www.dominio.com/landing/listhelp>, <mailto:list-info@cominio.com>",
- "Referenciausuario": "Tu referencia",
- "Report": "0",
- "Resp": "JSON"
}[- {
- "Res": "10",
- "Error": "Falta parámetro obligatorio",
- "idEnvio": "1228853777",
- "Destinatarios": "2",
- "Enviados": "[{\"Email\": \"destinatario@eldominio.com\",\"idMensaje\": \"108366478\"}]",
- "NoEnviados": "[{\"Nombre\": \"Ana Gonzalez\",\"Email\": \"noexiste@dominiomal.com\"}]",
- "Duplicados": "0"
}
]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
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Estado required | integer Estado de la notificación enviada. Los estados posibles son:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SistOperativo required | integer Tipo de sistema operativo detectado en destino (en aperturas)
|
{- "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"
}