HTTP API

1.Introducción

¿Qué es?

El API HTTP es una herramienta que te permite integrar EnvialoSimple.com con tus aplicaciones mediante simples llamadas a URLs.

La interfaz (API) te ofrece innumerables funcionalidades agrupadas por módulos para facilitar su utilización e implementación.

A través de la nueva API HTTP de EnvialoSimple.com podrás enviar tu campañas de email marketing; crear, modificar y eliminar contactos, listas de contactos y campañas; consultar estadísticas y reportes integrando todas las funcionalidades de EnvialoSimple.com en tu propia aplicación.

Todas las URLs tienen la misma estructura:

https://app.envialosimple.com/<modulo>/<accion>?APIKey=<api key>&format=<format>

<modulo> Simboliza a un grupo de acciones. Puede tomar los valores:

• campaign
• member
• report
• maillist

<accion> - Acción particular a realizar. Esta acción depende del modulo. Toma valores como "list", "add", "edit", etc.

<api key> - Token de autenticación. Estos token se generan desde tu cuenta de EnvialoSimple.com en las "Configuraciones Avanzadas".

<format> - Formato de salida del pedido. Los formatos soportados son:

• json
• xml

Respuesta (Estructura)

Todas las respuestas empiezan con un nodo "root" seguido por "ajaxResponse" si es que el formato de salida es "json" o directamente los datos después del nodo "root" si el formato de salida es XML.

Si NO se producen errores durante la ejecución de la operación se retorna un nodo "success" junto a los datos correspondientes al método. De lo contrario encontraremos un nodo "errors" con códigos de error.

Ejemplo:

{
            "root": {
                "ajaxResponse": {
                    "success": true,
                    <respuesta particular del servicio>
                }
            }
        }

{
            "root":{
                "ajaxResponse":{
                    "errors":{
                        <tokens de error>:<detalle de error si corresponde>
                    }
                }
            }
        }

{
        "root":{
            "ajaxResponse":{
                "errors":{
                "errorMsg_formValidations":{
                    "count":[
                    "notDigits"
                        ],
                    "absolutepage": [ ],
                    "filter": [ ],
                    "orderBy": [ ],
                    "desc": [ ],
                    "MailListsIDs": [ ]
                    }
                }
            }
        }
    }

1.Listar Campañas

Servicio:

/campaign/list

Lista todas las campañas filtradas por nombre

Parámetros:

Errores:

Estructura de Salida:

** Solo se documentan los campos mas relevantes.

ScheduleErrorStatus:

** Solo se documentan los errores más relevantes.

2.Recuperar información de una Campaña

Servicio:

/campaign/load

Recupera la información de una campaña

Parámetros:

Errores:

Estructura de Salida

3.Crear o Modificar la información de una campaña

Servicio:

/campaign/save

Crea o modifica información de una campaña. La llamada se debe hacer mediante POST

Parámetros:

** Solo se documentan los campos mas relevantes.

Errores:

Estructura de Salida:

** Devuelve todos los parámetros de entrada y agrega los siguientes datos:.

4.Vista previa de una campaña por e-mail o Navegador

Servicio:

/campaign/preview

Vista previa de una campaña por e-mail o Navegador. Este servicio soporta un tipo de formato de salida ("format") especial. El tipo "email"

Parámetros:

** Solo se documentan los campos mas relevantes.

Errores:

Estructura de Salida:

5.Borrar una campaña

Servicio:

/campaign/delete

Elimina definitivamente una campaña

Parámetros:

Errores:

En caso de no poder eliminar una campaña en la respuesta tendremos un nodo "errors" los los IDs de las campañas no eliminadas y otro nodo "countNotDeleted" con la cantidad de campañas no eliminadas.

Ej: errors:{notDeleted:["10","2"]},countNotDeleted: "2"

Estructura de Salida

6.Crear cuerpo de la campaña (HTML/Texto plano)

Servicio:

/content/edit

Crea/Modifica el cuerpo del e-mail de la campaña

7.Enviar una campaña

Servicio:

/campaign/resume

Una vez creada la campaña con su contenido se puede comenzar el proceso de envío de e-mails a los destinatarios. Este método también debe usarse para reanudar una campaña pausada

Parámetros:

Errores:

Estructura de Salida

8.Pausar campaña

Servicio:

/campaign/pause

Detiene el envío de una campaña. Esta campaña luego puede ser retomada con una llamada al servicio "/campaign/resume"

Parámetros:

Errores:

Estructura de Salida

9.Ejemplos útiles de implementación en PHP

En este ejemplo vamos a:

• 1. Crear una campaña con las siguentes características:
• 1. Nombre: 'Promo Verano'
• 2. Asunto: 'Super Ofertas de verano!!!'
• 3. ID de lista de contactos: 1
• 4. ID de email de remitente: 21
• 5. ID de email de respuesta: 21
• 6. Seguir enlaces: si
• 7. Contar aperturas: si
• 8. Usar Google Analytics: si
• 9. Enviar informe al finalizar: no
• 10. Agregar al archivo público: si
• 2. Modificación de estado de envío activada: si
• 3. Programar para envío inmediato: si
• 4. Crear el contenido del email y asignáraselo a la campaña.
• 5. Enviar la campaña.

Script

textarea con el codigo del script member.php

Salida Script PHP

Nueva Campaña: XX

Cuerpo de la campaña creado

Campaña enviada. Para ver el avance y el resultado de la campaña ver el modulo de 'reportes'

<?php$baseURL = 'https://app.envialosimple.com';$apiKey = 'TU LLAVE';// Creo nueva campaña$params = array();$params['APIKey']=$apiKey;$params['CampaignName']='Promo Verano';$params['CampaignSubject']='Super Ofertas de verano!!!';$params['MailListsIds']=array('1','2');$params['FromID']='21';$params['ReplyToID']='21';$params['TrackLinkClicks']='1';$params['TrackReads']='1';$params['TrackAnalitics']='1';$params['SendStateReport']='';$params['AddToPublicArchive']='1';$params['ScheduleCampaign']='1';$params['SendNow']='1';$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/campaign/save/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$ok = isset($response['root']['ajaxResponse']['success']);if(!$ok){echo "Error al crear la campaña\n";print_r($response);exit;}$id = $response['root']['ajaxResponse']['campaign']['CampaignID'];$name = $response['root']['ajaxResponse']['campaign']['Name'];echo "Nueva Campaña: $id $name\n";if($response['root']['ajaxResponse']['campaign']['integrity']['status']=='1'){if($response['root']['ajaxResponse']['campaign']['integrity']['subject']=='-1'){echo "Debes asignar un Asunto.\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['schedule']=='-1'){echo "Debes determinar una configuracion de envio\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['content']=='-1'){echo "Debes determinar un contenido de la campaña\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['replyTo']=='-1'){echo "Debes determinar un remitente 'reply to'\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['fromTo']=='-1'){echo "Debes determinar un origen 'from'\n";}if($response['root']['ajaxResponse']['campaign']['integrity']['maillist']=='-1'){echo "Debes determinar una o varias listas de contactos\n";}}// Crea contenido$params = array();$params['APIKey']=$apiKey;$params['CampaignID']=$id;$params['HTML']='<h1>Super ofertas de verano!!!</h1><p>Mirá nuestros <a href="http://mitiendita.com.ar">productos</a></p> <br/> para desuscribirse click <a href="%UnSubscribe%">aquí</a>';$params['PlainText']="Super ofertas de verano!!!\n\n\tMira nustros productos en http://mitiendita.com.ar";// Asigno contenido a la campaña.$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/content/edit/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$ok = isset($response['root']['ajaxResponse']['success']);if(!$ok){echo "No se pudo asigar el contenido del email a la campaña\n";print_r($response);exit;}echo "Cuerpo de campaña creado\n";// Envio la campaña$params = array();$params['APIKey']=$apiKey;$params['CampaignID']=$id;$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/campaign/resume/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$ok = isset($response['root']['ajaxResponse']['success']);if(!$ok){echo "Error al enviar la campaña\n";print_r($response);exit;}if($ok){echo "Campaña enviada. Para ver el avance y el resultado de la campaña ver el modulo de 'reportes'\n";}?>

1.Crear cuerpo de la campaña (HTML/Texto plano)

Servicio:

/content/edit

Recupera, crea o edita el cuerpo del e-mail de una campaña. Si el llamado al servicio es por GET, recupera la información del registro indicado por el parámetro CampaignID. Si es por POST Crea o actualiza los datos del registro indicado por el parámetro CampaignID

Parámetros:

Nota:

En el contenido del email debe estar presente un link de desuscripción a la lista de contactos.

Puede ser proporcionado de dos maneras:

a) Si el contenido ha sido proporcionado a través del parámetro URL (contenido remoto) debe indicarse en el parámetro RemoteUnsubscribeBlock el link de desuscripción.

b) Si el contenido ha sido proporcionado a través del parámetro HTML, éste debe contener el link de desuscripción conjuntamente con el contenido del email. Link de desuscipción: ‹span›Para desuscribirse de nuestra lista haga‹/span› ‹a href="%UnSubscribe%" target="_blank"›Click Aquí‹/a›

El link de desuscripción es obligatorio, en caso de no estar presente, la API devolverá el error errorMsg_unSubscribeTagMissing

Errores:

Estructura de Salida

** Solo se documentan los campos mas relevantes.

2.Listar plantillas

Servicio:

/template/gallery

Recupera el listado de plantilla

Parámetros:

Nota:Cada uno de los filtros por categoría produce una búsqueda de tipo (OR); la combinación de los dos filtros produce una búsqueda de tipo (OR) AND (OR).Ej. SELECT ... WHERE ( 'filterListByCategory'=5 OR 'filterListByCategory'=7 ) AND ('filterListByCategory2'=16)

Errores:

Estructura de Salida

** Solo se documentan los campos mas relevantes.

3.Listar categorías de plantillas

Servicio:

/campaign/templatecategories

Recupera el listado de categorías que se utilizan para agrupar las plantillas

list.category[]Listado de categorías generales.

list.color[]Listado de categorías por color.

Estructura de Salida:

1.Listar contactos

Servicio:

/member/list

Lista todos los contactos de todas las listas filtradas por email

Parámetros:

Errores:

Estructura de Salida:

** solo los campos relevantes son explicados y enumerados

2.Crear o Modificar la información de un Contacto

Servicio:

/member/edit

Recupera, crea o modifica información de un contacto.

Este servicio se comporta de formas distintas dependiendo la forma en la que realizamos la llamada. Si lo hacemos mediante GET y pasamos el parámetro MemberID, intentara recuperar la información del contacto. Si utilizamos POST intentara modificar o crear el contacto dependiendo si esta o no definido el parámetro MemberID

Parámetros:

Errores:

Estructura de Salida:

** Solo los campos relevantes son explicados y enumerados.

3.Cambiar el estado un Contacto (Suscribir, Desuscribir, Des-asociar, etc)

Servicio:

/member/changestaus

Modifica el estado de uno o mas contactos en relación a una lista o mas listas

Parámetros:

Errores:

Estructura de Salida:

changestatus: {
            detail: {
            changed: {
                2:["4","9"],
                1:["4","9"]
                     }
                    }
                SubscriptionStatus: "Subscribed"
                  }
            countChanged: 2

4.De-suscribir Contactos por email

Servicio:

/member/unsubscribebyemail

Remueve uno o mas contactos de una o varias listas de contactos filtrándolos por email

Parámetros:

Errores:

Estructura de Salida:

5.Ejemplos útiles de implementación en PHP:

En este ejemplo vamos a:

Crear un contacto con email=juanperez@gmail.com, nombre=Juan, apellido=Perez y suscripto a la lista con ID = 1.

Suscribimos el contacto a la lista con ID = 2.

Desuscribimos de la lista 1 al contacto creado en el paso 1

Buscamos el contacto creado en el paso 1 dentro de la lista 2

Script

textarea con el codigo del script member.php

Salida Script PHP

Nuevo Contacto: 19962 - juanperez@gmail.com: Juan Perez

Usuario suscripto correctamente a la lista 2

Usuario desuscripto correctamente de la lista 1

El usuario 19962 - juanperez@gmail.com (Juan Perez) esta suscripto a la lista 2

<?php$baseURL = 'https://app.envialosimple.com';$apiKey = ' TU LLAVE';// Creo un nuevo contacto en la lista 1$params = array();$params['APIKey']=$apiKey;$params['MailListID']=1;$params['Email']='juanperez@gmail.com';$params['CustomField1']='Juan';$params['CustomField2']='Perez';$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/member/edit/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$id = $response['root']['ajaxResponse']['member']['MemberID'];$email = $response['root']['ajaxResponse']['member']['Email'];$nombre = $response['root']['ajaxResponse']['member']['CustomFields']['item']['CustomField1']['Values']['Option'][0]['Value'];$apellido = $response['root']['ajaxResponse']['member']['CustomFields']['item']['CustomField2']['Values']['Option'][0]['Value'];echo "Nuevo Contacto: $id - $email: $nombre $apellido \n";//Suscricribo el contacto antes creado a la lista 2$params = array();$params['APIKey']=$apiKey;$params['MailListsIds']=array(2);$params['MemberIds']=array($id);$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/member/changestatus/SubscriptionStatus/Subscribed/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$exito = $response['root']['ajaxResponse']['success'];$count = $response['root']['ajaxResponse']['countSubscribed'];if($exito && $count=1){echo "Contacto suscripto correctamente a la lista 2\n";}else{echo "No se pudo suscribir correctamente a la lista 2\n";print_r($response);exit;}// De-Suscricribo el contacto antes creado de la lista 1$params = array();$params['APIKey']=$apiKey;$params['MailListsIds']=array(1);$params['MemberIds']=array($id);$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/member/changestatus/SubscriptionStatus/Unsubscribed/format/json');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);$exito = $response['root']['ajaxResponse']['success'];$count = $response['root']['ajaxResponse']['countUnsubscribed'];if($exito && $count=1){echo "Contacto desuscripto correctamente de la lista 1\n";}else{echo "No se pudo desuscribir correctamente de la lista 1\n";print_r($response);exit;}//Busco el contacto antes creado en la lista 2$params = array();$params['APIKey']=$apiKey;$params['MailListID']=2;$params['filter']='juanperez';$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $baseURL.'/member/listbymaillist/format/json?'.http_build_query($params));curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);$jsonResponse = curl_exec($ch);curl_close($ch);$response = json_decode($jsonResponse, true);foreach ($response['root']['ajaxResponse']['list']['item'] as $item){$tmpid = $item['MemberID'];$tmpemail = $item['Email'];$tmpnombre = $item['CustomFields']['item']['CustomField1']['Values']['Option'][0]['Value'];$tmpapellido = $item['CustomFields']['item']['CustomField2']['Values']['Option'][0]['Value'];echo "El Contacto $tmpid - $tmpemail ($tmpnombre $tmpapellido) esta suscripto a la lista 2\n";}?>

1.Listar listas de contactos

Servicio:

/maillist/list

Lista todas las listas de contactos

Parámetros:

Errores:

Estructura de Salida:

2.Crear o Modificar la información de una Lista de Contactos

Servicio:

/maillist/edit

Recupera, crea o edita los atributos de una lista de contactos. Si el llamado al servicio es por GET, recupera la información de la lista solicitada. Si es por POST Crea o actualiza (si se ingresa el parametro MailListID) el nombre de la lista de contactos

Parámetros:

Errores:

Estructura de Salida:

** Solo se documentan los campos mas relevantes.

1.Seguimiento en tiempo real

Servicio:

/report/livetrack

Informa el progreso de envío de una campaña

Parámetros:

Errores:

Estructura de Salida:

** Solo se documentan los campos mas relevantes.

2.Reporte general

Servicio:

/report/livetrack

Informa el detalle de una campaña con todos sus posibles envíos. (Los envíos múltiples de una campaña se mantienen por compatibilidad con un sistema anterior)

Parámetros:

Errores:

Estructura de salida:

** Solo se documentan los campos mas relevantes.

3.Reportes distribuidos en el tiempo

Servicio:

/report/trackintime

Informa las lecturas (únicas y totales) y click distribuidos en el tiempo. Se recomienda usar Flot (http://code.google.com/p/flot/) para graficar este reporte

Parámetros:

Errores:

Estructura de salida:

** Solo se documentan los campos mas relevantes.

4.Reporte resumido

Servicio:

/report/trackgraph

Informe resumido de lecturas, rebotes, de-suscripciones, entregas de emails, etc. Se recomienda usar Flot (http://code.google.com/p/flot/) para graficar este reporte

Parámetros:

Errores:

Estructura de salida:

** Solo se documentan los campos mas relevantes.

5.Exportación de reportes de lectura y clicks

Servicio:

/report/exportreads | /report/exportlinks

Genera un fichero csv con la informacion de lecturas (/report/exportreads) y clicks (/report/exportlinks) de una campaña. Una ves generado el fichero CSV se debe llamar al servicio "/download/export?FileToken=" para descargarlo

Parámetros:

Errores:

Estructura de salida:

** Solo se documentan los campos mas relevantes.

Si te interesa tener acceso a mas reportes o tenes sugerencias sobre nuevos reportes, por favor comunicate con nosotros. https://administracion.donweb.com/clientes/index.php?modulo=soporte&archivo=asistente

1.Seguimiento en tiempo real

Servicio:

/administratoremail/list

Listar direcciones de correo electrónico

Parámetros:

Errores:

Estructura de Salida:

** Solo se documentan los campos mas relevantes.

2.Crear o Modificar la información de una dirección de correo electrónico

Servicio:

/administratoremail/edit

Recupera, crea o edita los atributos de una dirección de correo electrónico. Si el llamado al servicio es por GET, recupera la información del registro solicitado. Si es por POST Crea o actualiza (si se ingresa el parametro EmailID) los datos del registro

Parámetros:

Errores:

Estructura de salida:

** Solo se documentan los campos mas relevantes.

3.Generación automática de Claves DKIM

Servicio:

/administratoremail/genKey

Genera automáticamete un par de claves para utilizar en la configuración DKIM

Parámetros:

Estructura de salida:

** Solo se documentan los campos mas relevantes.

4.Verificar configuración DKIM

Servicio:

/administratoremail/testdkim

Verifica si la configuración de la firma DKIM y la información de los registros DNS sean correctos y estén actualizados

Parámetros:

** Solo se documentan los campos mas relevantes.

5.Borrar una dirección de correo electrónico

Servicio:

/administratoremail/delete

Elimina lógicamente una dirección de correo electrónico, el registro no estará disponible para su visualización en los listados pero podrá seguir siendo utilizado por el sistema para asegurar el correcto funcionamiento de las campañas que lo utilicen

Parámetros:

1.Estado de la cuenta del administrador

Servicio:

/administrator/status

Este servicio provee la información correspondiente al estado de la cuenta del administrador como por ejemplo: créditos disponibles, tareas programadas, procesos de importación/exportación/purga de miembros de las listas de contactos, etc

Parámetros:

Estructura de Salida:

Cada uno de los elementos del arreglo contiene los siguientes datos:

1.Listar campos personalizados

Servicio:

/customfield/list

Lista los campos personalizados que han sido configurados

Parámetros:

Errores:

Estructura de Salida:

2.Crear o Modificar la información de un campo personalizado

Servicio:

/customfield/edit

Recupera, crea o edita los atributos de un campo personalizado. Si el llamado al servicio es por GET, recupera la información del registro solicitado. Si es por POST Crea o actualiza (si se ingresa el parametro CustomFieldID) los datos del registro

Parámetros:

Nota: Los parámetros ItemsNames eItemsValues están relacionados entre sí a través de la correspondencia de las claves de ambos arreglos. Ej. ItemsNames[5] posee la etiqueta de la opción cuyo valor se encuentra indicado en ItemsValues[5]

Errores:

Estructura de salida:

** Solo se documentan los campos mas relevantes.

3.Borrar un campo personalizado

Servicio:

/customfield/delete

Elimina definitivamente un campo personalizado, el registro no estará más disponible para su utilización

Parámetros:

Errores:

Estructura de salida: