Módulo campaign

1.Listar Campañas

Servicio:

/campaign/list

Lista todas las campañas filtradas por nombre

Parámetros:

Parámetrocount
RequeridoNO
TipoNúmero Entero >0
ExplicaciónNúmero de campañas a devolver como máximo
Ejemplocount=10
Parámetroabsolutepage
RequeridoNO
TipoNúmero Entero >0
ExplicaciónPágina de "count" registros a la que se quiere ir. Si count vale 10 y absolutepage vale 3, entonces empezaremos a ver desde la campaña 31
Ejemploabsolutepage=3
Parámetrostatus
RequeridoNO
TipoArreglo de Cadena de Caracteres
Valores Posibles:

Active(Pendiente de aprobación, pendiente, preparando o enviando)
Inactive(Borrador, pausada o detenida)

Completed(Enviada)
ExplicaciónTipos de estado por los que se desea filtrar la lista
Ejemplostatus[] = Inactive&status[] = Completed
Parámetrofilter
RequeridoNO
TipoCadena de Caracteres
ExplicaciónNombre o parte del nombre por el que se filtran las campañas
Ejemplofilter=Promo Verano
ParámetroorderBy
RequeridoNO
TipoCadena de Caracteres
ExplicaciónValores posibles:
name (Nombre de la campaña)
id (Id de la campaña)
EjemploorderBy=name
Parámetrodesc
RequeridoNO
TipoNúmero Entero
Valores posibles:
1 (si)
0 (no)
ExplicaciónDetermina si el orden del listado es ascendente o descendente
Ejemplodesc=1

Errores:

errorMsg_formValidations
Uno o varios de los parámetros de entrada es incorrecto, falta o es requerido. Tiene asociada una estructura del tipo "Parámetro inválido"=>"error"
errorMsg_noCampaigns
Por un error inesperado no se pudo realizar ninguna consulta

Estructura de Salida:

campaign.CampaignID
ID de la campaña
campaign.Name
Nombre de la campaña
campaign.Status
Estado de envío
  • [Draft(Borrador)
  • Halted|Paused(Pausada)
  • Stopped(Detenida)
  • Completed(Completada)
  • Pending(Pendiente)
  • Sending(Enviando)
  • Completed(Enviada)]
Solo las campañas en Paused o Stopped se pueden enviar
campaign.ScheduleType
Tipo de programación de envío [Not scheduled | Send Now | One time scheduled]
campaign.schedule.ScheduleSendDate
Fecha programada para el envío. Solo válido si el tipo es "One time scheduled"
campaign.schedule.ScheduleErrorStatus
Errores verificados durante el envío (ver recuadro abajo)

** Solo se documentan los campos mas relevantes.

ScheduleErrorStatus:

errorMsg_remoteContentNotFound
No se ha podido recuperar el contenido remoto de tu campaña
errorMsg_campaignNotFound
La campaña ha sido eliminada y no puede recuperarse
errorMsg_administratorSuspended
La cuenta se encontraba suspendida al momendo de intentar enviar la campaña
errorMsg_administratorExhaustedQuota
Tu cuenta no tenía créditos disponibles y la operación fué detenida
errorMsg_maillistsEmpty
La lista de destinatarios utilizada no posee contactos activos

** 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:

ParámetroCampaignID
RequeridoSI
TipoNúmero Entero >0
ExplicaciónIdentificador de la campaña a recuperar
EjemploCampaignID=10

Errores:

errorMsg_formValidations
Uno o varios de los parámetros de entrada es incorrecto, falta o es requerido. Tiene asociada una estructura del tipo "Parámetro inválido"=>"error".
errorMsg_campaignInvalidID
Por un error inesperado no se pudo realizar ninguna consulta
errorMsg_campaignNotFound
No se puede encontrar la campaña
errorMsg_campaignMaillistNotFound
No se pueden encontrar las listas asociadas
errorMsg_campaignContentNotFound
No se puede encontrar el contenido de la campaña
errorMsg_campaignScheduleNotFound
No se puede encontrar la programación de la campaña

Estructura de Salida

campaign.CampaignID
ID de la campaña
campaign.Name
ID de la campaña
campaign.Status
Estado de envío.(Solo las campañas en Paused o Stopped se pueden enviar)Valores Posibles
  • [Draft(Borrador)
  • Paused(Pausada)
  • Stopped(Detenida)
  • Pending(Pendiente)
  • Pendingfor Approval(Pendiente de aprobación)
  • Sending (Enviando)
  • Completed (Completada)
Solo las campañas en Paused o Stopped se pueden enviar
campaign.schedule.ScheduleType
Tipo de programación de envío. Valores Posibles:
  • Not scheduled(Sin Programar)
  • Send Now(Enviar Ahora)
  • One time scheduled(Envío Programado.)
campaign.schedule.ScheduleSendDate
Fecha programada para el envío. Solo válido si el tipo es "One time scheduled"
campaign.schedule.ScheduleErrorStatus
Errores verificados durante el envío (ver recuadro abajo)

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:

ParámetroCampaignID
RequeridoNO
TipoNúmero Entero >0
ExplicaciónIdentificador de la campaña que se quiere modificar
EjemploCampaignID=2
ParámetroCampaignName
RequeridoSI
TipoCadena de caracteres
ExplicaciónIdentificador de la campaña que se quiere modificar
EjemploCampaignName=Campaña de navidad
ParámetroCampaignSubject
RequeridoNO
TipoCadena de caracteres
ExplicaciónAsunto con el que se enviará la campaña
EjemploCampaignSubject=Feliz Navidad
ParámetroMailListsIds
RequeridoNO
TipoArray de enteros >0
ExplicaciónIDs de listas a las que se enviará la campaña
EjemploMailListsIds[]=4
ParámetroFromID
RequeridoNO
TipoNúmero Entero >0
ExplicaciónID de email de administrador designado como origen de la campaña (FROM)
EjemploFromID=3
ParámetroReplyToID
RequeridoNO
TipoNúmero Entero >0
ExplicaciónID del email de administrador designado como email de respuesta (ReplyTO)
EjemploReplyToID=4
ParámetroTrackLinkClicks
RequeridoNO
Tipo0 o 1 (por defecto 0)
ExplicaciónSi el parámetros es = 1, se registraran todos los clicks que se hagan en los links una vez enviada la campaña
EjemploTrackLinkClicks=1
ParámetroTrackReads
RequeridoNO
Tipo0 o 1 (por defecto 0)
ExplicaciónSi el parámetros es = 1, se registrará cada vez que un contacto abra el email de campaña
EjemploTrackReads=1
ParámetroTrackAnalitics
RequeridoNO
Tipo0 o 1 (por defecto 0)
ExplicaciónSi el parámetros es = 1, se agregaran a cada link los parámetros requeridos por "google analitics" para hacer un seguimiento de la campaña
EjemploTrackAnalitics=0
ParámetroSendStateReport
RequeridoNO
Tipo0 o 1 (por defecto 0)
ExplicaciónSi el parámetros es = 1, al terminar de enviar la campaña, se enviará un email al dueño de la cuenta informando la situación
EjemploSendStateReport=0
ParámetroScheduleCampaign
RequeridoNO
Tipo0 o 1 (por defecto 0)
ExplicaciónSi el parámetros es = 1, si se debe registrar la "Programación de envío" de la campaña
EjemploScheduleCampaign=1
ParámetroSendDate
RequeridoNO
TipoFecha con el formato yyyy-MM-dd HH:mm:ss
ExplicaciónFecha de envío de la campaña. Este parámetro depende de "ScheduleCampaign"
EjemploSendDate=2012-11-20 14:10:00
ParámetroAddToPublicArchive
RequeridoNO
Tipo0 o 1 (por defecto 0)
ExplicaciónAgregar la campaña al "archivo publico de campañas"
EjemploAddToPublicArchive=1

** Solo se documentan los campos mas relevantes.

Errores:

errorMsg_formValidations
Uno o varios de los parámetros de entrada es incorrecto, falta o es requerido
errorMsg_invalidCampaignDate
La fecha de envío es menor a la fecha actual
errorMsg_campaignIsCompletedNotSaved
La campaña que se quiere modificar ya fue enviada
errorMsg_campaignMaillistsNotSaved
No se pudieron guardar asignar las listas de contactos
errorMsg_phishing
La campaña es detectada como posible intento de estafa
errorMsg_campaignContentNotSaved
No se pudo guardar el asunto o parámetros relacionados con el contenido de la campaña
errorMsg_campaignScheduleNotSaved
No se pudo guardar la "Programación de envío"
errorMsg_campaignLoad
No se puede recuperar la campaña
errorMsg_campaignNotPost
Los parámetros fueron pasados por GET y deben ser pasados por POST
errorMsg_campaignNotFound
Una vez guardados los datos, se intenta verificar la correcta persistencia de los datos. Si no se puede encontrar la campaña se retorna este error
errorMsg_campaignMaillistNotFound
Una vez guardados los datos, se intenta verificar la correcta persistencia de los datos. Si no se pueden encontrar las listas asociadas se retorna este error
errorMsg_campaignContentNotFound
Una vez guardados los datos, se intenta verificar la correcta persistencia de los datos. Si no se puede encontrar el contenido de la campaña se retorna este error
errorMsg_campaignScheduleNotFound
Una vez guardados los datos, se intenta verificar la correcta persistencia de los datos. Si no se puede encontrar la programación de la campaña se retorna este error

Estructura de Salida:

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

campaign.integrity.status
= 1 si la campaña tiene toda la información necesaria para ser enviada
= -1
campaign.integrity.schedule
= 1 si la información de programación de envío es correcta y completa
= -1
campaign.integrity.status
= 1 si la campaña tiene toda la información necesaria para ser enviada
= -1
campaign.integrity.subject
= 1 si tiene asunto
= -1
campaign.integrity.content
= 1 si el cuerpo de los emails no esta vacío
= -1
campaign.integrity.replyTo
= 1 si tiene un email de respuesta asignado
= -1
campaign.integrity.fromTo
= 1 si tiene un email de remitente asignado
= -1
campaign.integrity.maillist
= 1 si tiene una o varias listas asignadas
= -1

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:

ParámetroCampaignID
RequeridoSI
TipoNúmero Entero
ExplicaciónIdentificador de la campaña a recuperar
EjemploCampaignID=10
ParámetroEmail
RequeridoSolo si el formato es "email"
TipoDirección de correo electrónico
ExplicaciónDestinatario de la pre-visualización de la campaña
EjemploEmail=j.f.fray@envialosimple.com

** Solo se documentan los campos mas relevantes.

Errores:

errorMsg_formValidations
Uno o varios de los parámetros de entrada es incorrecto, falta o es requerido. Tiene asociada una estructura del tipo "Parámetro inválido"=>"error".
errorMsg_campaignNotFound
No se puede encontrar la campaña
errorMsg_remoteContentEmpty
El contenido remoto asociado a la campaña esta vacío.
errorMsg_remoteContentNotFound
El contenido remoto asociado a la campaña no se pudo encontrar
errorMsg_campaignNotPersonalized
No se pueden reemplazar los tokens de los campos personalizados

Estructura de Salida:

email.fromName
Etiqueta nombre del email del remitente.
email.from
Email del remitente.
email.replyToName
Etiqueta nombre del emailResponder a:
email.replyTo
Email de Responder a:
campaign.CampaignName
Nombre de la campaña
campaign.CampaignName
Nombre de la campaña
campaign.subject
Asunto de la campaña
campaign.HTML
Código HTML de la campaña
campaign.plainText
Texto plano alternativo para los clientes que no soportan HTML.
campaign.CampaignID
Identificador de la campaña.

5.Borrar una campaña

Servicio:

/campaign/delete

Elimina definitivamente una campaña

Parámetros:

ParámetroCampaignIds
RequeridoSI
TipoArreglo de Números Enteros
ExplicaciónIds de campañas a eliminar
EjemploCampaignIds[]=10&CampaignIds[]=1

Errores:

errorMsg_formValidations
Uno o varios de los parámetros de entrada es incorrecto, falta o es requeridoTiene asociada una estructura del tipo "Parámetro inválido"=>"error"
errors.notDeleted
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

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

countDeleted
Número de campañas eliminadas

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

Servicio:

/content/edit

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

Ver detalles del servicio

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:

ParámetroCampaignID
RequeridoSI
TipoNúmero Entero
ExplicaciónIdentificador de la campaña a enviar
EjemploCampaignID=10

Errores:

errorMsg_formValidations
Uno o varios de los parámetros de entrada es incorrecto, falta o es requeridoTiene asociada una estructura del tipo "Parámetro inválido"=>"error"
errorMsg_campaignNotActive
La campaña esta en estado "Draft" por lo que no esta lista para ser enviada
errorMsg_campaignNotResumed
La campaña no se pudo reanudar/enviar
errorMsg_campaignNotScheduled
No se pudo Cambiar el estado a la configuración de envío
errorMsg_campaignCompleted
La campaña ya fue enviada en su totalidad. No puede reenviarse
errorMsg_maxSimultaneousCampaignLimitExceeded
No pueden enviarse más de 10 campañas simultáneamente

Estructura de Salida

campaign.CampaignID
ID de la campaña

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:

ParámetroCampaignID
RequeridoSI
TipoNúmero Entero
ExplicaciónIdentificador de la campaña a pausar
EjemploCampaignID=10

Errores:

errorMsg_formValidations
Uno o varios de los parámetros de entrada es incorrecto, falta o es requerido. Tiene asociada una estructura del tipo "Parámetro inválido"=>"error"
errorMsg_campaignNotActive
La campaña esta en estado "Draft" por lo que no puede ser pausada
errorMsg_campaignAlreadyPaused
La campaña ya esta pausada
errorMsg_campaignStoppedOrCompleted
La campaña esta detenida o completada
errorMsg_campaignCompleted
La campaña ya fue enviada en su totalidad. No puede pausarse
errorMsg_campaignNotPaused
La campaña no pudo pausarse

Estructura de Salida

campaign.CampaignID
ID de la campaña

9.Ejemplos útiles de implementación en PHP

En este ejemplo vamos 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";}?>