eMail Marketing - Envíos Masivos de eMails Certificados

Conociendo la API

Sobre nuestra API e integración

La API (Application Program Interface) te permitirá integrar el email marketing con cualquier otro sistema externo. Esta es una API RESTfull. Todas las llamadas a la API deben ser hechas con HTTP POST y HTTP GET. En respuesta a las llamadas, la API devolverá su respuesta en formato JSON.

RESTfull API

Esta es una API RESTfull. Todas las llamadas a la API deben ser hechas con HTTP POST y HTTP GET. En respuesta a las llamadas, la API devolverá su respuesta en formato JSON. También es posible hacer el request enviando el body en formato JSON.

URL de la API

Todas las llamadas a la API se harán a la misma URL correspondiente a su cuenta. Puede consultar esta URL en “Información de cuenta” solapa “API”.

Aclaraciones previas

Dado que la URL de la API dependerá de la que corresponda a su cuenta, para todos los ejemplos en esta documentación utilizaremos el dominio “{SERVERURL}”. Te en cuenta que esta URL no existe, si no que es solo a modo ejemplo.

Estructura de la documentación

La documentación de la API esta dividida en funciones o acciones. En cada apartado de acción, podrá encontrar una descripción o consideraciones a tener en cuenta para esa acción. Contará con una tabla de parámetros de entrada, seguido de una tabla con información sobre los valores de retorno, además de una tabla con los posible errores. Contará con información necesaria para entender más el uso de la acción y es posible que algunos parámetros podrían necesitar de una ayuda adicional, en ese caso será dada al final del apartado.

Llamada a las funciones

Las funciones se determinan en la URL. Por ejemplo para crear una campaña llamaremos a la URL

                    
                    http://{SERVERURL}/api/2.0/message/create

Si quisiéramos obtener las estadísticas del envío de una campaña llamaríamos a la URL.

                    
                    http://{SERVERURL}/api/2.0/message/stats

La URL de consulta es del tipo

                    
                    http://{SERVERURL}/api/2.0/MODULO/ACCION

Autenticación

Todas las funciones de la API requieren uno o varios parámetros de identificación de su cuenta. Algunas funciones podrán requerir de su nombre de usuario y contraseña, que serán los mismo que utiliza para el acceso a la plataforma. Otras funciones requerirán una clave llamada “user_key” la cual puede encontrar en la sección “Herramientas -> API e integración”.

Parámetros
user_key string	Cadena alfanumérica que identifica una cuenta de usuario.

Manejo de errores

Siempre que se produzca un error, la API devolverá un “status” igual a “error”, un código de error y una descripción del mismo.

                
                    {
                        "status":"error",
                        "errno":"103001A",
                        "message":"Recipient address is missing or not valid."
                    }

Valores de respuesta
status	"error"
error	Código de error, numérico o alfanumérico.
message	Descripción de error

Errores de API

Esta es una lista de los errores comunes en la API para cualquier modulo.

Código de error
001001A	No se ha proporcionado una user_key o la misma es inválida.
001002A	La cuenta de usuario se encuentra suspendida.
001003A	El módulo no existe. Verifique la URL de consulta.
001004A	La acción no existe. Verifique la URL de consulta.

Ejemplos de request

Request JSON

URL: http://{SERVERURL}/api/2.0/list/get

Body

                
                    {
                        "user_key":"261615af2e48a86459ead77",
                        "list_id":"103001019AZD",
                    }

Módulos y Operaciones

users

Manipulación de usuarios

Operaciones
create	Crea una cuenta de usuario.
edit	Edita una cuenta de usuario.
delete	Elimina una cuenta de usuario y todo su contenido.
credits	Agrega créditos a una cuenta de usuario.
list	Obtiene una lista de cuentas de usuario.
get	Obtiene los parámetros y estadísticas de uso de una cuenta de usuario.
changeStatus	Cambia el estado de una cuenta de usuario entre activo y suspendido.
updateToken	Crea una cuenta de usuario
getTokens	Crea una cuenta de usuario

list

Manipulación de listas

Operaciones
create	Crea una nueva lista e importa suscriptores.
delete	Elimina una lista.
edit	Permite modificar los valores editables de una lista.
get	Obtiene los datos de una lista.
list	Devuelve la información de todas las listas en la cuenta.
import	Permite importar datos a una lista.
importStatus	Importa el estado los suscriptores de la lista.
clone	Clona la lista especificada.

message

Manipulación de mensajes y campañas.

Operaciones
create	Crea y envía una nueva campaña o mensaje de automatización.
changeStatus	Cambia el estado de un mensaje.
details	Obtiene listados detallados de clicks, aperturas o rechazados de una campaña.
list	Lista todas las campañas.
stats	Obtiene las estadísticas de envío de una campaña.

subscriber

Manipulación de suscriptores.

Operaciones
subscribe	Suscribe una dirección a la lista o actualiza los datos de un suscriptor.
unsuscribe	Desuscribe una dirección de una lista.
delete	Elimina un suscriptor de una lista.
get	Obtiene datos, estado e historial de eventos y acciones de un suscriptor.

txnemail

Manipulación de emails transaccionales.

Operaciones
send	Envía un email transaccional.
stats	Obtiene las estadísticas de un email transaccional.

automation

Manipulación automatizaciones.

Operaciones
create	Crea una automatización.

form

Manipulación de formularios de suscripción.

Operaciones
create	Crea un formulario de susripción.

/user

Administra cuentas de usuario. Este modulo esta disponible únicamente para cuentas reseller o user-manager, a excepción de la acción “get” con la que cualquier tipo de usuario podrá acceder a los detalles de su cuenta.

Todos los parámetros deben ser pasados con POST.

La respuesta será en formato JSON.

Operaciones
create	Crea una cuenta de usuario.
edit	Edita una cuenta de usuario.
delete	Elimina una cuenta de usuario y todo su contenido.
credits	Agrega créditos a una cuenta de usuario.
list	Obtiene una lista de cuentas de usuario.
get	Obtiene los parámetros y estadísticas de uso de una cuenta de usuario.
changeStatus	Cambia el estado de una cuenta de usuario entre activo y suspendido.
updateToken	Crea una cuenta de usuario
getTokens	Crea una cuenta de usuario

/user/create

Crea una nueva cuenta de usuario.

Parámetros

Nombre

Descripción

Formato

username string

Nombre de usuario.

3 a 60 caracteres alfanuméricos incluidos -._@

password string

Contraseña.

6 a 20 caracteres (a-z A-Z 0-9 -$%&-_.,!@#*»:) debe contener al menos 1 letra y 1 número.

name string

Nombre.

0 a 40 caracteres.

lastname string

Apellido.

0 a 40 caracteres.

email string

Dirección de email

Formato válido de dirección de email, son espacios.

company string

Nombre de compañía/Empresa (opcional)

address string

Dirección postal (opcional).

region string

Región (opcional).

city string

Ciudad (opcional).

max_sends integer

Número de envíos mensuales permitidos. 0 representa cero, -1 representa ilimitados. (opcional).

Número de 0 a 99.999.999

credits integer

Número de créditos de envío para la carga inicial. (opcional).

Número entero de 0 a 99.999.999

max_lists integer

Número máximo de listas que el usuario puede tener. 0 (cero) es ilimitado.

Número entero de 0 a 99.999.999

max_subscribers integer

Número máximo de suscriptores que el usuario puede tener. 0 (cero) es ilimitado.

Número entero de 0 a 99.999.999

trial integer

Número de días en los que la cuenta sera eliminada. 0 (cero) es nunca.

Número entero

day_reset integer

Valor numérico 1-28 indica el día en que cambia el ciclo de envíos mensuales y se resetea su cuota. (Opcional. Debe en blanco para utilizar el día de creación de la cuenta).

allow_api boolean

Permite el uso de API.

True o False

allow_send boolean

Permite el envío de campañas.

True o False

allow_txn boolean

Permite el envío de emails transaccionales.

True o False

allow_email_templates boolean

Permite el uso de plantillas prediseñadas.

True o False

allow_verifications boolean

Permite el uso del modulo verificador de listas.

True o False

tokens array

Array con los tokens que se desean crear junto con la cuenta de usuario. (opcional)

name string	Nombre del token. Hasta 50 caracteres alfanuméricos.
value string	Valor del token. Hasta 255 caracteres.

Array

Valores de retorno
status	“success”.
user_id	ID del la cuenta de usuario creada.
user_key	Identificador de usuario para el uso de la API

Códigos de error
013001D	El día de reinicio debe ser un número entero entre 1 y 31
013002D	El nombre de usuario debe ser de 3 o más caracteres
013003D	La contraseña no puede tener menos de 6 caracteres
013004D	El nombre de usuario es demasiado largo
013005D	La contraseña es demasiado larga
013006D	La contraseña es demasiado simple
013007D	El nombre de usuario contiene caracteres inválidos. Solo se permiten caracteres alfanuméricos y los caracteres especiales -_.@
013007D	La contraseña contiene caracteres no permitidos
013008D	La cantidad de envíos debe ser numérica
013010D	La cantidad de créditos debe ser numérica y no puede contener valores negativos
013011D	La cantidad de borrado de listas debe ser numérica
013012D	La cantidad de listas debe ser numérica y no puede contener valores negativos
013013D	La cantidad de suscriptores debe ser numérica y no puede contener valores negativos
013014D	El nombre de usuario no esta disponible
013015D	El nombre de usuario no esta disponible
013016L	No tienes suficiente disponibilidad de envíos mensuales para asignarle el valor indicado a este usuario.
013021L	El valor de max_sends no puede ser menor a -1.
013017L	No tienes suficiente disponibilidad de listas para asignarle el valor indicado a este usuario.
013018L	No tienes suficiente disponibilidad de suscriptores para asignarle el valor indicado a este usuario.
013019L	No tienes suficiente disponibilidad de créditos para asignarle el valor indicado a este usuario.

/user/edit

Es posible identificar la cuenta de usuario por nombre de usuario o ID numérico. Debe especificar una de las 2 variables.

Parámetros

Nombre

Descripción

Formato

user_i string

ID de usuario.

Número entero.

usernam string

Nombre de usuario.

3 a 60 caracteres alfanuméricos incluidos -._@

password string

Contraseña.

6 a 20 caracteres (a-z A-Z 0-9 -$%&-_.,!@#*»:) debe contener al menos 1 letra y 1 número.

name string

Nombre.

0 a 40 caracteres.

lastname string

Apellido.

0 a 40 caracteres.

email string

Dirección de email

Formato válido de dirección de email, son espacios.

company string

Nombre de compañía/Empresa (opcional)

address string

Dirección postal (opcional).

region string

Región (opcional).

city string

Ciudad (opcional).

max_sends integer

Número de envíos mensuales permitidos. 0 representa cero, -1 representa ilimitados. (opcional).

Número de 0 a 99.999.999

credits integer

Número de créditos de envío para la carga inicial. (opcional).

Número entero de 0 a 99.999.999

max_lists integer

Número máximo de listas que el usuario puede tener. 0 (cero) es ilimitado.

Número entero de 0 a 99.999.999

max_subscribers integer

Número máximo de suscriptores que el usuario puede tener. 0 (cero) es ilimitado.

Número entero de 0 a 99.999.999

trial integer

Número de días en los que la cuenta sera eliminada. 0 (cero) es nunca.

Número entero

day_reset integer

Valor numérico 1-28 indica el día en que cambia el ciclo de envíos mensuales y se resetea su cuota. (Opcional. Debe en blanco para utilizar el día de creación de la cuenta).

allow_api boolean

Permite el uso de API.

True o False

allow_send boolean

Permite el envío de campañas.

True o False

allow_txn boolean

Permite el envío de emails transaccionales.

True o False

allow_email_templates boolean

Permite el uso de plantillas prediseñadas.

True o False

allow_verifications boolean

Permite el uso del modulo verificador de listas.

True o False

tokens array

Array con los tokens que se desean crear junto con la cuenta de usuario. (opcional)

name string	Nombre del token. Hasta 50 caracteres alfanuméricos.
value string	Valor del token. Hasta 255 caracteres.

Array

Valores de retorno
status	“success”.

Códigos de error
013001D	El día de reinicio debe ser un número entero entre 1 y 31
013002D	El nombre de usuario debe ser de 3 o más caracteres
013003D	La contraseña no puede tener menos de 6 caracteres
013004D	El nombre de usuario es demasiado largo
013005D	La contraseña es demasiado larga
013006D	La contraseña es demasiado simple
013007D	El nombre de usuario contiene caracteres inválidos. Solo se permiten caracteres alfanuméricos y los caracteres especiales -_.@
013007D	La contraseña contiene caracteres no permitidos
013008D	La cantidad de envíos debe ser numérica
013010D	La cantidad de créditos debe ser numérica y no puede contener valores negativos
013011D	La cantidad de borrado de listas debe ser numérica
013012D	La cantidad de listas debe ser numérica y no puede contener valores negativos
013013D	La cantidad de suscriptores debe ser numérica y no puede contener valores negativos
013014D	El nombre de usuario no esta disponible
013015D	El nombre de usuario no esta disponible
013016L	No tienes suficiente disponibilidad de envíos mensuales para asignarle el valor indicado a este usuario.
013021L	El valor de max_sends no puede ser menor a -1.
013017L	No tienes suficiente disponibilidad de listas para asignarle el valor indicado a este usuario.
013018L	No tienes suficiente disponibilidad de suscriptores para asignarle el valor indicado a este usuario.
013019L	No tienes suficiente disponibilidad de créditos para asignarle el valor indicado a este usuario.

/user/delete

Puede eliminar una cuenta de usuario a través del nombre de usuario o ID numérico. Deberá especificar una de las 2 variables.

Parámetros:
username string	Nombre de usuario.	3 a 60 caracteres alfanuméricos incluidos -._@.
user_id integer	ID de usuario.	Número entero.

Valores de retorno:

status

“success”.

Códigos de error:

014001D

La cuenta de usuario no existe.

/user/credits

Esta acción permite agregar o quita créditos de envío a un usuario.

Parámetros
username string	Nombre de usuario.	3 a 60 caracteres alfanuméricos incluidos -._@.
user_id integer	ID de usuario.	Número entero.
credits integer	Cantidad de créditos a agregar.	Número entero de 1 a 9999999.
remove boolean	Indique true para remover créditos en lugar de agregarlos.	True o False.
description string	Descripción opcional.	Cadena de texto de hasta 150 caracteres.

Valores de retorno
status	“success”.
credits_left	Nueva cantidad de créditos disponibles en su cuenta.
user_credits	Nueva cantidad de créditos disponibles en la cuenta de usuario.

Códigos de error
014001D	La cuenta de usuario no existe.
016001D	La cantidad de créditos indicada no es un valor numérico o esta fuera de rango.
016002D	Su cuenta no dispone de suficientes créditos para asignar esta cantidad.
016003D	El usuario no tiene la cantidad de créditos que le desea quitar.

/user/list

Obtiene una lista de cuentas de usuario.

Parámetros
username string	Nombre de usuario.	3 a 60 caracteres alfanuméricos incluidos -._@.
user_id integer	ID de usuario.	Número entero.

Valores de retorno

status

“success”.

users_list

Array de datos con la información de todas las cuentas de usuario.

status	Estado de la cuenta de usuario, “active” o “suspended”
user_id	ID numérico de la cuenta de usuario.
username	Nombre de usuario.
firstname	Nombre de persona.
lastname	Apellido de persona.
email	Email de la cuenta de usuario.
company	Nombre de la empresa/compañía.
address	Dirección postal.
city	Ciudad.
region	Región.
credits	Cantidad de créditos disponibles en la cuenta.
max_sends	Cantidad máxima de envíos mensuales permitidos (-1 es ilimitado).
max_lists	Cantidad máxima de listas permitidas (cero es ilimitado).
max_subscribers	Cantidad máxima de suscriptores permitidos (cero es ilimitado).
allow_api	Permite el uso de API (1=permite, 0=no permite).
allow_delete_kust	Permite eliminar listas de suscriptores (1=permite, 0=no permite).
allow_verifications	Permite el uso de la herramienta de verificación de listas (1=permite, 0=no permite).
allow_txn	Permite el envío de emails transaccionales (1=permite, 0=no permite).
ln_domain	Dominio utilizado para enmascarar los enlaces de las campañas.
rp_domain	Dominio utilizado en la dirección de Return-Path.
reputation	Reputación de usuario (1-100).
reputation_level	Nivel de reputación (good, bad, worst).
day_reset	Día del mes en que se reinicia el contador de envios mensuales.
dateCreated	Fecha de creación de la cuenta de usuario (formato unix-time).
lastlogin	Fecha de ultimo acceso (formato unix-time).
timezone	Zona horaria registrada desde el ultimo acceso.
available_sends	Cantidad de envíos disponibles en la cuenta de usuario.
email_sent_in_period	Cantidad de email enviado en el periodo actual.
current_subscribers	Cantidad actual de suscriptores en listas.
limit_reset	Día del próximo reinicio del contador de envíos mensuales.

/user/get

Obtiene los datos de un usuario.

Parámetros
username string	Nombre de usuario.	3 a 60 caracteres alfanuméricos incluidos -._@.
user_id integer	ID de usuario.	Número entero.

Valores de retorno

status

“success”.

users_list

Array de datos con la información de todas las cuentas de usuario.

status

Estado de la cuenta de usuario, “active” o “suspended”

user_id

ID numérico de la cuenta de usuario.

username

Nombre de usuario.

firstname

Nombre de persona.

lastname

Apellido de persona.

email

Email de la cuenta de usuario.

company

Nombre de la empresa/compañía.

address

Dirección postal.

city

Ciudad.

region

Región.

credits

Cantidad de créditos disponibles en la cuenta.

max_sends

Cantidad máxima de envíos mensuales permitidos (-1 es ilimitado).

max_lists

Cantidad máxima de listas permitidas (cero es ilimitado).

max_subscribers

Cantidad máxima de suscriptores permitidos (cero es ilimitado).

allow_api

Permite el uso de API (1=permite, 0=no permite).

allow_delete_kust

Permite eliminar listas de suscriptores (1=permite, 0=no permite).

allow_verifications

Permite el uso de la herramienta de verificación de listas (1=permite, 0=no permite).

allow_txn

Permite el envío de emails transaccionales (1=permite, 0=no permite).

ln_domain

Dominio utilizado para enmascarar los enlaces de las campañas.

rp_domain

Dominio utilizado en la dirección de Return-Path.

reputation

Reputación de usuario (1-100).

reputation_level

Nivel de reputación (good, bad, worst).

day_reset

Día del mes en que se reinicia el contador de envios mensuales.

dateCreated

Fecha de creación de la cuenta de usuario (formato unix-time).

lastlogin

Fecha de ultimo acceso (formato unix-time).

timezone

Zona horaria registrada desde el ultimo acceso.

available_sends

Cantidad de envíos disponibles en la cuenta de usuario.

email_sent_in_period

Cantidad de email enviado en el periodo actual.

current_subscribers

Cantidad actual de suscriptores en listas.

limit_reset

Día del próximo reinicio del contador de envíos mensuales.

nro_campaigns

Número de campañas creadas en la cuenta de usuario.

nro_lists

Número de listas que posee el usuario.

lists_info

Array de datos con la información de las listas del usuario.

name

Nombre de la lista.

subscribers

Array de datos con las estadísticas de suscriptores

active	Suscriptores activos.
unsus	Desuscriptos.
notconfirmed	No confirmados.
bkl	Bloqueados.
failed	Fallidos.
invalid	Invalidados.

Códigos de error
014001D	La cuenta de usuario no existe.

Obtener los detalles de mi cuenta

Es posible obtener los detalles de cualquier cuenta de usuario, incluso la suya misma reseller. Para obtener los detalles de su propia cuenta, haya la llamada definiendo el parámetro “username” igual a “me”.

/user/changeStatus

Cambia el estado de una cuenta de usuario entre activo y suspendido.

Parámetros
username string	Nombre de usuario.	3 a 60 caracteres alfanuméricos incluidos -._@
user_id string	ID de usuario.	Número entero.
status integer	Estado al que se quiere cambiar.	“active” o “suspended”.

Valores de retorno
status	“success”.

Códigos de error
014001D	La cuenta de usuario no existe.
014102D	El ‘status’ indicado no es válido.

/user/updateToken

Crea un token personalizados para usar en las plantillas de email. Al enviar una campaña de email o un email de automatización, el token es reemplazado por el valor.

Parámetros
username string	Nombre del token.	3 a 50 caracteres alfanumericos.
value string	Valor del token.	Hasta 255 caracteres

Valores de retorno
status	“success”.
name	Nombre del token
token	Código del tocken para usar en las plantillas de email

Códigos de error
T150101D	El nombre del token supera los 50 caracteres.
T150102D	El valor del token supera los 255 caracteres.
T150103D	El nombre del tocen es menor a 3 caracteres.

/user/getTokens

Sin parámetros adicionales. Obtiene todos los tokens del usuario.

Valores de retorno

status

“success”.

total_tokens

Numero entero con el total de tokens creados.

tokens

Array con los tokens

name	Nombre del token.
token	Código de token.
value	Valor asignado al token.

/list

Este modulo esta disponible para cualquier tipo de cuenta de usuario, regular o reseller. Administra listas de suscriptores

Todos los parámetros deben ser pasados con POST.

La respuesta será en formato JSON.

Operaciones
create	Crea una nueva lista e importa suscriptores.
delete	Elimina una lista.
edit	Permite modificar los valores editables de una lista.
get	Obtiene los datos de una lista.
list	Devuelve la información de todas las listas en la cuenta.
import	Permite importar datos a una lista.
importStatus	Importa el estado los suscriptores de la lista.
clone	Clona la lista especificada.

/list/create

Crea una nueva lista e importa suscriptores.

Parámetros
name string	Nombre de la lista.	Entre 3 y 60 caracteres alfanuméricos incluidos []-_*!@#.,/+
from_name string	Nombre del remitente.	3 a 60 caracteres alfanuméricos.
from_mail email	Email del remitente.	Formato válido de dirección de email.
notify_email email	Email para notificaciones.	Formato válido de dirección de email.

Valores de retorno
status	“success”.
list_id	Cadena alfanumérica con el ID de la lista creada.

Códigos de error
U02301P	La cuenta ya no permite la creación de más listas. Puede que haya alcanzado el limite máximo de listas permitidas o que el administrador no le permita crear listas.
U02303D	El nombre del remitente no ha sido ingresado.
U02303D	La dirección de email remitente, from_mail no es válida.

/list/delete

Elimina una lista de suscriptores.

Parámetros
list_id string	ID de list.	String alfanumérico

Valores de retorno
status	“success”.

Códigos de error
U02401D	No se encontró la lista con el list_id indicado.

/list/edit

Permite editar los datos de una lista.

Parámetros
list_id string	ID de list.	String alfanumérico.
name string	Nombre de la lista.	Entre 3 y 60 caracteres alfanuméricos incluidos []-_*!@#.,/+.
from_name string	Nombre del remitente.	3 a 60 caracteres alfanuméricos.
from_mail email	Email del remitente.	Formato válido de dirección de email.
description string	Descripción de la lista.	Texto plano.
notify_email	Email para notificaciones.	Formato válido de dirección de email.

Valores de retorno
status	“success”.
list_info	Array con la información de la lista. Igual a /list/get.

Códigos de error
U02401D	No se encontró la lista.
U03101D	La dirección de email en notify_email no es válida.
U03102D	La dirección de email en from_email no es válida.

Datos opcionales

Todos los parámetros son opcionales. Solo se modificarán los atributos que se envíen en los parámetros.

/list/get

Obtiene los detalles de una lista.

Parámetros
list_id string	ID de list.	String alfanumérico

Valores de retorno

status

“success”.

list_data

Array de datos con la información de las listas del usuario.

name

Nombre de la lista.

from_name

Nombre del remitente de la lista.

from_mail

Dirección de email del remitente de la lista.

subscribers

Array de datos con las estadísticas de suscriptores.

active	Suscriptores activos.
unsus	Desuscriptos.
notconfirmed	No confirmados.
bkl	Bloqueados.
failed	Fallidos.
invalid	Invalidados.

custom_fields

Array con los campos adicionales.

name	Nombre del campo.
pretty_name	Nombre amigable.
required	Flag: es requerido en formulario.
internal	Flag: de uso interno únicamente.
type	Tipo de dato.

Detalle de suscriptores:

Desuscriptos: son aquellos suscriptores que han solicitado la desuscripción.
No confirmados: son aquellos suscriptores que se han suscripto vía formulario pero aun no validaron su dirección de email.
Bloqueados: son aquellos suscriptores que han denunciado un email como spam o bien el sistema detecto que la dirección de email es inexistente.
Fallidos: son aquellos suscriptores que han rechazado envíos 3 o más veces.
Invalidados: son los suscriptores fallidos más los bloqueados.

/list/list

Retorna los datos de las listas creadas. Sin parámetros.

Valores de retorno

status

“success”.

total_results

Número de listas

lists

Array de datos con la información de cada lista.

name	Nombre de la lista.
from_name	Nombre del remitente de la lista.
from_mail	Dirección de email del remitente de la lista.
subscribers	Número de suscriptores totales
blocked	Número de suscriptores bloqueados
invalid	Número de suscriptores inválidados
list_id	ID de lista

/list/import

Permite importar datos a una lista.

Parámetros
list_id string	ID de list.	String alfanumérico.
data string	Contenido de la lista. (Opcional).	String.
url string	URL en donde se encuentra el contenido de la lista. (Opcional).	String \| URL.
cols string	String con el orden de las columnas, separadas por coma. (Opcional).	String con comas.
data file	Archivo adjunto con la lista.	Archivo.

Valores de retorno
status	“queued”.
queuedID	ID del proceso de importación.
Cols	Array con los campos utilizados en la lista.

Códigos de error
U02401D	No se encontró la lista con el list_id indicado.
U02601I	No se proporciono el contenido de la lista.
U02606I	El formato de compresión no es válido.
U02602I	No se definió la columna “email”.
U02604I	No se pudo acceder a la URL.
U02604I	No se pudo acceder al contenido de la lista. Es posible que esto sea un error interno.

Métodos para cargar los datos

Es posible cargar el contenido de la lista de diferentes métodos.

El parámetro “data” puede ser un string o un file. En caso de que sea un string, este puede esta comprimido en formato GZip. El sistema detectará automáticamente la compresión.

La segunda forma de obtener el contenido de la lista es vía URL. Si la lista esta alojada en algún servidor externo, puede indicar la URL en este parámetro.

“data” y “url” son opcionales, pero al menos uno de los 2 debe especificarse.

Si quisiera enviar la lista en un archivo adjunto, debe enviar un archivo (y solo uno) con el nombre “data”.

Retorno

Cuando el proceso finalice, recibirá un status “queued”. Esto significa que el proceso de importación se va a realizar en segundo plano debido a que puede demorar varios minutos según el tamaño de la lista. Con el valor retornado en “queuedID” podrá consultar el estado de importación de la lista.

/list/importStatus

Obtiene el estado de la importación.

Parámetros
queueID string	ID de proceso de importación.	String alfanumérico.

Valores de retorno
status	“queued” o “completed”.
ListID	ID de la lista.
imported	Numero de direcciones importadas.
updated	Numero de direcciones actualizadas.
failed	Numero de direcciones invalidas.
duplicated	Numero de direcciones duplicadas.
completed	Número que indica el porcentaje de progreso de la importación. Se muestra únicamente si la importación no se completó.

Códigos de error
U03701E	No se encontró el ID.

/list/clone

Esta función permite clonar una lista de suscriptores. Adicionalmente es posible clonar una lista de cualquier otro usuario. Solamente es necesario obtener el código de la lista.

Parámetros
clone_id string	Codigo de la lista.	String alfanumérico.

Valores de retorno

status

“success”.

list_id

ID de la nueva lista.

list_info

Array de datos con la información de las listas clonada.

name

Nombre de la lista.

from_name

Nombre del remitente de la lista.

from_mail

Dirección de email del remitente de la lista.

subscribers

Array de datos con las estadísticas de suscriptores.

active	Suscriptores activos.
unsus	Desuscriptos.
notconfirmed	No confirmados.
bkl	Bloqueados.
failed	Fallidos.
invalid	Invalidados.

custom_fields

Array con los campos adicionales.

name	Nombre del campo.
pretty_name	Nombre amigable.
required	Boolean flag: es requerido en formulario.
internal	Boolean flag: de uso interno únicamente.
type	Tipo de dato.

Códigos de error
U02401D	No se encontró la lista con el list_id indicado.
U02301P	La cuenta no permite crear mas listas.
C02801Q	La cuenta no posee suficiente limite para la cantidad de suscriptores de la lista a clonar.

Estado de la nueva lista

La lista será clonada manteniendo el estado de cada suscriptor, ya sea activo, invalido, bloqueado. Los suscriptores desuscriptos o no confirmados no será agregados a la nueva lista.

/message

Esta función permite manipular campañas y mensajes de automatización.

Todos los parámetros deben ser pasados con POST.

La respuesta será en formato JSON.

Operaciones
create	Crea y envía una nueva campaña o mensaje de automatización.
changeStatus	Cambia el estado de un mensaje.
details	Obtiene listados detallados de clicks, aperturas o rechazados de una campaña.
list	Lista todas las campañas.
stats	Obtiene las estadísticas de envío de una campaña.

/message/create

Envía o programa el envío de una campaña o un email de automatización.

Parámetros
type string	Tipo de mensaje, puede ser “campaign” para campañas, o “automation” para crear un mensaje para usar con automatización.
name string	Nombre de campaña o email de automatización.
html string	Código HTML del email (opcional).
text string	Texto opcional para ser enviado (opcional).
html_url string	URL para obtener el cuerpo HTML. Si se define URL, el parámetro “html” será ignorado. (opcional)
subject string	Asunto del email.
from_mail string	Dirección de email del remitente.
from_name string	Nombre del remitente.
track_opens string	Si desea o no hacer seguimiento de aperturas (opcional).
track_clicks string	Si desea o no hacer seguimiento de clicks (opcional).
auto_text string	Si desea o no generar la parte texto en base al HTML. (salvo que se especifique el texto alternativo) (opcional).
auto_html string	Si desea o no generar la parte HTML en base al texto. (Salvo que se especifique el HTML). (opcional)
g_analytics string	Si se desea o no convertir los enlaces para integrarlos con Google Analytics (opcional).
clicktale string	Si se desea o no convertir los enlaces para integrarlos con ClickTale (opcional).
reply_to string	Dirección de email para recibir las respuestas de sus emails (opcional).
list_id string	Destinatarios. Array con 1 o más elementos que contienen los ID de las listas de destinatarios.
segmentation_id string	ID de la segmentación a utilizar para filtrar las listas de destinatarios (opcional).
send_at string	Día y horario de envío. Deje en blanco para enviar inmediatamente. Formato: YYYY-MM-DD HH:MM:SS También puede especificar su zona horaria. Por ejemplo: “2017-03-18 15:45:00 +0500” Limite: 30 días en el futuro

Valores de retorno
status	“success”.
message_id	ID numérico del mensaje creado.
date_start	Fecha en que iniciará el envío en caso de ser una campaña.
recipients	Número de destinatarios en caso de ser una campaña.

Códigos de error
M05032D	Debe especificar un tipo de mensaje, “campaign” o “automation”.
M05003D	‘html_url’ es invalida o no se ha podido acceder a la misma.
M05026D	No se puede obtener la información de la URL en ‘html_url’.
M05004D	‘from_mail’ no es una dirección de email válida.
M05031D	‘segmentation_id’ no es válido o no ha sido encontrado.
M05025D	‘from_mail‘ no esta en su lista de remitente o no ha sido validado.
M05005D	Debe proveer un nombre de remitente ‘from_name’.
M05020D	La línea de asunto debe contener entre 3 y 150 caracteres.
M05021D	El nombre de campaña o nombre de mensaje de automatización “name”, debe contener entre 3 y 150 caracteres.
M05019D	‘reply_to’ no es una dirección de email válida.
M05023D	Debe proveer al menos una lista de destinatarios.
M05024D	Una o más listas de destinatarios, no es válida.
M05010D	El formato de fecha ‘sent_at’ no es válido.
M05011D	‘send_at’ es en el pasado.
M05012D	No puede programar un envío a más de 30 días en el futuro.
M05028E	No se ha podido crear el mensaje.
M05030D	No hay subscriptores que coincidan con los parámetros de selección. O bien las listas no contienen suscriptores activos o bien se aplico una segmentación en donde se filtran todos los suscriptores.
M05029E	No se ha podido crear el mensaje.

Cuerpo del mensaje

El mensaje debe contener al menos uno de los 3 parámetros “html”, “text” o “html_url”. En caso de ingresar una URL valida, el parámetro “html” es reemplazado por el contenido de la URL ingresada.

Remitente

La dirección de email de remitente debe estar creada y validada en la plataforma para poder utilizarse en la creación de mensajes.

Listas de destinatarios

Para la creación de un mensaje de campaña, es necesario que indique al menos una lista de destinatarios. Las listas de destinatarios se definen como un array en el parámetro “list_id” donde cada elemento del array es un ID de lista. Los ID de lista se obtiene en la configuración de la lista o bien puede ver todos los IDs juntos en la sección “Herramientas -> API e integración”.

Fecha y hora de envío

Es posible programar en envío de la campaña para cualquier fecha y hora en el futuro. Para ellos puede definir la fecha y hora con el parámetro “send_at” usando alguno de estos formatos de fecha: “YYYY-MM-DD HH:MM:SS +/-0000” o “YYYY-MM-DD HH:MM:SS”.

Para evitar la diferencia de horario por zona horaria, defina el huso horario según UTC, por ejemplo “2017-03-18 15:45:00 +0500”.

Si el parámetro “send_at” no es definido, el mensaje será programado para ser enviado 5 minutos después de su creación. En caso de que necesite hacer alguna modificación o haya cometido un error en la creación, dispone de este tiempo para hacer los arreglos necesarios.

/message/changeStatus

Esta acción puede detener un envío en curso, puede reanudar un envío detenido o iniciar inmediatamente el envío de una campaña programada a futuro. Solo aplica a campañas.

Parámetros
message_id integer	ID numérico del mensaje. Puede ser mensaje de campaña.
status string	Nuevo estado del mensaje, al cual se quiere pasar. Puede ser “stop”, para detener un envío en curso, “restart” para reanudar un envío detenido o “send_now” para enviar inmediatamente un envío de campaña programado.

Valores de retorno
status	“success”.
message_id	ID numérico del mensaje creado.

Códigos de error
M05200D	Estado no válido.
M05201D	‘message_id’ inválido o no encontrado.
M05203D	El mensaje no se esta enviando, no puede ser detenido.
M05204D	El mensaje no esta detenido, no se puede reanudar.
M05205D	El mensaje no esta programado, no se puede cambiar el estado para iniciarlo ahora.

/message/details

Obtiene una lista detallada de todas las acciones realizadas por los suscriptores que recibieron la campaña.

Las acciones son:

open: Detalle de las aperturas del email. Si están disponibles se proveerán datos de geolocación y dispositivo con el que se leyó el email.
click: Detalle de los clicks en los enlaces del email.
unsubscribe: Detalle de las desuscripciones.
blocked: Detalle de los suscriptores que fueron bloqueados. El bloqueo se puede generar por que la casilla no existe o porque el suscriptor denunció SPAM. Se detalla el motivo.
bounce: Detalla los envíos rechazados, junto con su código de rechazo.
site_track: Detalla la navegación en el sitio y los objetivos/conversiones alcanzados.

Parámetros
message_id integer	ID numérico del mensaje. Puede ser mensaje de campaña.
action string	La acción que se quiere obtener: “open”, “click”, “bounce”, “blocked”, unsubscribe”, “site_track”.

Valores de retorno

status

“success”.

data

Array de datos con el detalle de las acciones.

name

Nombre de la lista.

from_name

Nombre del remitente de la lista.

from_mail

Dirección de email del remitente de la lista.

subscribers

Array de datos con las estadísticas de suscriptores.

email	Email del suscriptor.
date	Fecha de la acción en formato UNIX.
list_id	ID de la lista.
extra_data	Array con información adicional sobre la acción.

Códigos de error
M05301D	Acción no válida.
M05302D	‘message_id’ inválido o no encontrado
M05303D	No hay información disponible.

/message/list

Obtiene una lista de mensajes de campaña o de automatización.

Parámetros
message_id integer	ID numérico del mensaje. Puede ser mensaje de campaña o de automatización.
type string	El sistema almacena los últimos datos de las estadísticas en memoria cache. Utilice este parámetro en TRUE para volver a calcular las estadísticas. Esto podría demorar un tiempo más en devolver el resultado.
show integer	Número de resultados a devolver. El número debe ser entre 1 y 50. Si se indica número mayor a 50 devolverá error. Por defecto serán 30 resultados. (opcional)
start_at integer	Número del índice del primer resultado. Este es un parámetro de paginación. (opcional)

Valores de retorno

total_results

Número total de mensajes.

returned_results

Número total de mensajes devueltos en esta consulta.

messages

Array con la información de los mensajes devueltos en esta consulta.

ID numérico del mensaje.

name

Nombre del mensaje o campaña.

subject

Asunto del mensaje.

recipients

Número de destinatarios total.

from_name

Nombre del remitente

from_mail

Email del remitente.

track_opens

Opción para seguimiento de aperturas. 1 define activado.

track_clicks

Opción para seguimiento de clicks. 1 define activado.

g_analytics

Opción para integración con Google Analytics. 1 define activado.

clicktale

Opción para integración con ClickTale. 1 define activado.

date_created

Fecha de creación del mensaje en formato UNIX.

date_start

Fecha de inicio del envío del mensaje en formato UNIX. Solo para campañas. Solo aplica a campañas.

date_completed

Fecha de envío completado en formato UNIX, solo para campañas. Solo aplica a campañas.

lists

Array de listas de destinatarios. Solo aplica a campañas.

name	Nombre de la lista.
list_id	ID de la lista.

status

Devuelve el estado actual del mensaje. “completed”, “scheduled”, “stopped”, “saved”, “sending”, “restarting”. Solo aplica a campañas.

stats

Array con las estadísticas del mensaje. Se obtiene la misma estructura de array de datos que en la acción “/message/stats”.

Códigos de error
M05101D	Mensaje no encontrado.

Paginación de resultados

Esta función devolverá un número máximo de 50 resultados por consulta. En caso de necesitar obtener los mensajes siguientes al número 50, se debe utilizar el parámetro “start_at” donde se indica el número de primer resultado. Por ejemplo, de querer obtener los resultados de 51 al 100, se deben definir los parámetros “show”=50 y “start_at”=50.

/message/stats

Obtiene el resumen y estadísticas de una campaña o mensaje de automatización.

Parámetros
message_id integer	ID numérico del mensaje. Puede ser mensaje de campaña o de automatización.
nocache boolean	El sistema almacena los últimos datos de las estadísticas en memoria cache. Utilice este parámetro en TRUE para volver a calcular las estadísticas. Esto podría demorar un tiempo más en devolver el resultado.

Valores de retorno

status

Devuelve el estado actual del mensaje. “completed”, “scheduled”, “stopped”, “saved”, “sending”, “restarting”.

recipients

Número de destinatarios total.

from_name

Nombre del remitente.

from_mail

Email del remitente.

track_opens

Opción para seguimiento de aperturas. 1 define activado.

track_clicks

Opción para seguimiento de clicks. 1 define activado.

g_analytics

Opción para integración con Google Analytics. 1 define activado.

clicktale

Opción para integración con ClickTale. 1 define activado.

date_created

Fecha de creación del mensaje en formato UNIX.

date_start

Fecha de inicio del envío del mensaje en formato UNIX. Solo para campañas.

date_completed

Fecha de envío completado en formato UNIX, solo para campañas.

lists

Array de listas de destinatarios.

name	Nombre de la lista.
list_id	ID de la lista.

stats

Estadísticas del mensaje.

sent

Array con la cantidad de emails enviados.

value	Cantidad numérica.
per	Porcentaje relativo a la cantidad de suscriptores.

not_sent

Array con la cantidad de emails no enviados.

value	Cantidad numérica.
per	Porcentaje relativo a la cantidad de suscriptores.

delivered

Array con la cantidad de emails entregados.

value	Cantidad numérica.
per	Porcentaje relativo a la cantidad de suscriptores.

pending

Array con la cantidad de emails pendientes de envío.

value	Cantidad numérica.
per	Porcentaje relativo a la cantidad de suscriptores.

bounced

Array con la cantidad de emails rechazados.

value

Cantidad numérica.

per

Porcentaje relativo a la cantidad de emails enviados.

type

Array. Tipos de rechazo, “soft”, “hard”, “spam”, “invalid”. (Ver detalles debajo).

soft/hard/spam/invalid Array

value	Valor numérico total
per	Porcentaje relativo a la cantidad de rechazados
abs_per	Porcentaje relativo a la cantidad de emails enviados

unsubscribed

Array con la cantidad de emails desuscriptos.

value	Cantidad numérica.
per	Porcentaje relativo a la cantidad de emails entregados.

opens

Array con la cantidad de aperturas.

value	Cantidad numérica de suscriptores que abrieron el email.
per	Porcentaje relativo a la cantidad de emails entregados.
total	Total de aperturas incluyendo repeticiones.
ratio	Diferencia entre aperturas totales y únicas (suscriptores).
firstDayReads	Dia de la primera apertura. Array.
data	Array con los datos de aperturas por días de la semana y horas del día.

clicks

Array con la cantidad de emails desuscriptos.

unique

Clicks únicos.

total

Porcentaje relativo a la cantidad de emails entregados.

subscribers

Cantidad de suscriptores que hicieron click en uno o más enlaces

data_list

Array con la información de los links y clicks.

link	URL del link html escaped.
url	URL del link.
clicks	Cantidad de suscriptores que hicieron click.
clicks_totales	Cantidad de clicks.
id	ID numérico del link.

per

Porcentaje de clicks/suscriptores relativo a la cantidad de emails entregados.

referred

Array con la cantidad de emails desuscriptos.

value

Cantidad numérica de referidos.

reads

Array con la información de aperturas de los referidos.

value	Cantidad numérica de aperturas.
per	Porcentaje de aperturas relativo a la cantidad de referidos.

per

Porcentaje de clicks/suscriptores relativo a la cantidad de emails entregados.

complaints

Array con la cantidad de emails suscriptores que han marcado el email como spam.

value	Cantidad numérica.
per	Porcentaje relativo a la cantidad de emails entregados.

device

Array con la estadística de dispositivos utilizados para leer los emails.

device_data

Array con la estadística de dispositivos utilizados para leer los emails.

ctr

Porcentaje decimal Click-Through Rate (relativo a los emails entregados).

ctor

Porcentaje decimal Click-Through Open Rate (relativo a las aperturas).

Códigos de error
M05101D	Mensaje no encontrado.

Estados del mensaje de campaña

completed: El mensaje ha sido enviado a toda la lista de suscriptores.
scheduled: El mensaje esta programado para ser enviado en la fecha determinada por el usuario.
stopped: El mensaje se ha detenido y no continua enviándose. Permite reanudar el envío.
sending: El mensaje esta actualmente enviándose a la lista de suscriptores. La estadística de envía indicara la cantidad y porcentaje de enviados.
restarting: El mensaje ha sido reiniciado y esta en espera de continuar su envío.
starting: El mensaje esta iniciando su envío.

Estadística de rechazados

En la variable stats.bounced se detallan los emails rechazados. “type” define el tipo de rechazo, siendo “hard” y “soft” las categorías padre, donde “hard” son rechazados permanentes” y “soft” son rechazados temporales, como podría ser rechazado por casilla llena.

Los tipos “invalid” y “spam” son subcategorías de “hard” y “soft” respectivamente. “invalid” se refiere a los rechazados cuando la casilla de email no existe y “spam” se refiere a cuando el rechazo es a causa de que el email fue interpretado como SPAM. El sistema trata a los rechazados “spam” como temporales.

/subscriber

Manipulación de suscriptores.

Operaciones
subscribe	Suscribe una dirección a la lista o actualiza los datos de un suscriptor.
unsuscribe	Desuscribe una dirección de una lista.
delete	Elimina un suscriptor de una lista.
get	Obtiene datos, estado e historial de eventos y acciones de un suscriptor.

/subscriber/subscribe

Suscribe o actualiza los datos de un suscriptor.

Parámetros

list_id string

ID de la lista.

email string

Dirección de email del suscriptor.

update boolean

Indica si se debe actualizar los datos de un suscriptor existente o suscribir uno nuevo. Si ‘update’ es TRUE y la dirección de email no existe, se suscribirá. (opcional).

name string

Nombre del suscriptor. (Opcional). Si no se ingresa un nombre al actualizar los datos de un suscriptor, se mantendrá el nombre actual.

custom_fields array

Datos de los campos personalizados. Cada elemento del array, contiene un array con name y value. Todos los campos son opcionales. Si no se indican en la actualización, se mantienen los valores actuales. (opcional)

name string	Nombre del campo. (Ej: {{{$pf_ciudad}}}
value string	Valor del campo

subscribed boolean

Al suscribir un email, puede enviarle el email de confirmación para que se valide la dirección, o suscribirlo de forma directa. TRUE suscribirá de forma directa.(Opcional).

Valores de retorno
status	“success”.

Códigos de error
S10001D	La dirección de email no es válida.
S10002D	La dirección de email se encuentra en Blacklist.
S10007D	La dirección de email no es válida.
S10006D	La dirección podrías ser falsa o prohibida.
S10003Q	Su cuenta no dispone de límite suficiente para agregar mas suscriptores.
S10004L	La lista no existe.
S10005E	El email no se encuentra en la lista especificada.

Suscripción y cambio de estado

Si una dirección ya se encuentra en la lista en estado pendiente, podrá activarla utilizando los parámetros “update” y “subscribed” en TRUE.

Cuando actualiza los datos de un suscriptor, el nombre se actualizará únicamente si lo provee. De lo contrario, se mantendrá el actual.

En caso de los campos personalizados, solo se actualizará los datos de los campos que estén en el array, aun si su valor estuviera vacío. Todos los campos personalizados son opcionales. Los campos que no estén en el array, no se actualizarán.

Automatización

Cualquier automatización asociada a la suscripción en esta lista, será ejecutada.

/subscriber/unsubscribe

Desuscribe un suscriptor de una lista especifica.

Parámetros
list_id string	ID de la lista.
email string	Dirección de email del suscriptor.

Valores de retorno
status	“success”.

Códigos de error
S12001L	La lista no existe.
S12002E	El email no se encuentra en la lista especificada.
S12003E	La dirección de email ya se encuentra desuscripta.
S10001D	La dirección de email no es válida.

Automatización

Cualquier automatización asociada a la suscripción en esta lista, será ejecutada.

/subscriber/delete

Elimina un suscriptor de una o mas listas.

Parámetros
list_id string	ID de la lista. (opcional).
email string	Dirección de email del suscriptor.

Valores de retorno
status	“success”.
count	Valor numérico que indica la cantidad de ocurrencias.
deleted_from	Array con nombres de las listas de las que fue eliminada la dirección.

Códigos de error
S13001L	La lista no existe.
S10001D	La dirección de email no es válida.

Eliminar de todas las listas

Si no se especifica el parámetro ‘list_id’ el email será buscado y eliminado de todas las listas

/subscriber/get

Obtiene los datos del suscriptor, el estado y el historial de acciones y eventos.

Parámetros
list_id string	ID de la lista. (opcional).
email string	Dirección de email del suscriptor.

Valores de retorno

status

“success”.

data

Array con los datos del suscriptor.

name	Nombre del suscriptor.
email	Email del suscriptor.
status	Estado de la suscripción. “pending”, “subscribed”, “invalid”, “blocked”.
subscribed	Fecha de suscripción en formato unix.
created	Fecha de creación en formato unix.
*custom_fields*	Valor de cada campo

log

Array con el historial de acciones del suscriptor.

action	Nombre de la acción: “subscribe”, “unsubscribe”, “blocked”, “complaint”, “open”, “click”, “event”, “site_track”.
date	Fecha en formato unix.
list_id	ID de la lista, en caso de que aplique.
message_id	ID de la campaña o mensaje, en caso de que aplique.
data	Array con información adicional sobre la acción.

Códigos de error
S13001L	La lista no existe.
S10001D	La dirección de email no es válida.
S14002E	La dirección no se encuentra en la lista.

Fecha de suscripción y creación

Esta fecha puede diferir según el momento en que el suscriptor confirme su suscripción.

subscribed: define la fecha en que el usuario confirme su suscripción. Si el email fue agregado por el administrador manualmente, esta fecha será la fecha en que fue ingresado a la lista.
created: define la fecha en que el usuario completa el formulario de suscripción. Si el email fue agregado por el administrador manualmente, esta fecha será la fecha en que fue ingresado a la lista.

Historial de acciones

Cada acción tendrá información adicional. Por ejemplo, en una desuscripción, se indicara el origen de la desuscripción, que puede ser vía link de desuscripción, vía denuncia o manualmente vía API.

La acción “click” indica que el suscriptor hizo click en un link. En este caso se van a dar datos adiciones sobre el enlace.

La acción “open” indica que el suscriptor abrió un email o campaña. En “data”, se indican datos adicionales de locación (si estuviera disponibles) como país, región, ciudad, y los datos del dispositivo del cliente (si estuviera disponible) como tipo de dispositivo, sistema operativo, cliente de correo o navegador.

La acción “site_track” registra toda la navegación del suscriptor en su sitio web cuando lo visita desde un email. En datos adicionales se indica la URL de cada pagina visitada. Si la acción es “site_track” también se indicara la el nombre de la conversión/objetivo en caso de haber sido alcanzado.

txnemail

Este modulo esta disponible para cualquier tipo de cuenta de usuario, regular o reseller. Envia emails transaccionales y obtiene sus estadísticas.

Todos los parámetros deben ser pasados con POST.

La respuesta será en formato JSON.

Operaciones
send	Envía un email transaccional.

/txnemail/send

Vea la documentación de SMTP para saber como hacer envíos transaccionales utilizando el protocolo SMTP.

Podrá enviar un email indicando sus parámetros o bien utilizar un email previamente creado o una campaña previamente creada. Para enviar un email con sus propios parámetros, utilice el parámetro “message”. Para enviar un email previamente creado, indique su identificador con el parámetro “templateID”. Para enviar un email de una campaña, indique su identificador con el parámetro “campaignID”.

En caso de que utilice una email previamente creado o una campaña, se obtendrán sus parámetros para crear un nuevo email a enviar.

El parámetro “message_id” le permite agrupar todos los emails del mismo tipo o grupo y así obtener una estadística conjunta de todos los emails enviados del mismo grupo.

Parámetros:

message array

Crea un nuevo mensaje con los siguientes parámetros.

html string

Código HTML del email.

text string

Texto opcional para ser enviado.

subject string

Asunto del email.

from_mail string

Dirección de email del remitente.

from_name string

Nombre del remitente.

track_opens boolean

Si desea o no hacer seguimiento de aperturas.

track_clicks boolean

Si desea o no hacer seguimiento de clicks.

auto_text boolean

Si desea o no generar la parte texto en base al HTML. (salvo que se especifique el texto alternativo).

auto_html boolean

Si desea o no generar la parte HTML en base al texto. (Salvo que se especifique el HTML).

attachments array

Archivos adjuntos. (Opcional).

type string	Tipo de archivo. (Ej. «image/jpeg”).
name string	Nombre del archivo.
content string	Base64_encoded del contenido del archivo.

reply_to

Dirección de email para recibir las respuestas de sus emails (opcional).

campaign_id string

Identificador de la campaña. (Opcional).

to array

Destinatarios. Array con 1 o más elementos.

name string

Nombre del destinatario. (Opcional)

email string

Dirección de email.

custom_fields array

Array de campos personalizados (Opcional).

field string	Nombre del campo
value string	Valor del campo.

message_id string

Identificador del mensaje a enviar. Cadena de texto alfanumérica de 1 a 60 caracteres, incluidos los catacteres “.-_” y espacio.

headers array

Cabeceras adicionales de email. (Opcional)

name string	Nombre de la cabecera.
value string	Valor del campo.

send_at string

Día y horario de envío. Deje en blanco para enviar inmediatamente. Formato: YYYY-MM-DD HH:MM:SS También puede especificar su zona horaria. Por ejemplo: “2017-03-18 15:45:00 +0500” Limite: 30 dias en el futuro

custom_fields array

Definición de campos personalizados en el mensaje. (Opcional)

field string	Nombre del campo.
value string	Valor del campo.

message_id y grupo de mensajes

Cada mensaje que envíe, tendrá un identificador (ID) único. Puede reutilizar este ID para agrupar todos los mensajes que envíe del mismo tipo o grupo y así tener una estadística unificada de todos los envíos.

Este ID es a elección y puede ser cualquier palabra alfanumérica sin espacios ni caracteres especiales.

Campos personalizados

Cuando envía una campaña previamente guardada en el sistema, puede utilizar campos personalizados para luego reemplazarlos por el valor correspondiente.

Los campos personalizados tiene el formato {{{$nombre_campo}}} Por ejemplo, si necesita personalizar el nombre del destinatario, podría hacerlo de la siguiente manera: En el cuerpo del mensaje se encuentra el texto: {{{$nombre}}}

En el parámetro “custom_fields” define:

{“custom_fields”: [ {“field”: “nombre”, “value”: “John Smith”} ]}

De la misma manera que puede tener campos personalizados en el mensaje, también puede personalizar el email por casa destinatario.

Utilice la variable to[][custom_fields]

Ejemplo:

                    
                        { "to":[
                        {
                        "email":"johnsmith@mycompany.com",
                        "name":"John Smith",
                        "cumtom_field":[
                        {
                        "pais":"Canada",
                        "estado":"Toronto",
                        }
                        ]
                        }
                        ],
                        }

Si necesita usar el nombre o dirección de email del destinatario en campos personalizados deberá usar las etiquetas {{{$to_name}}} y {{{$to_email}}} para nombre e email respectivamente.

Ejemplo de parámetros con JSON

El siguiente ejemplo, contiene los parámetros para el envío de un email transaccional.

                    
                        {
                        "user_key":"YOUR_USER_KEY",
                        "message":{
                        "text":"...texto alternativo...",
                        "html":"...html Code...
                        "subject":"Hola {{{$rcpt_name}}}",
                        "from_name":"John Smith",
                        "from_mail":"john@mycompany.com",
                        "reply_to":" john@mycompany.com ",
                        "bounced_to":" bounced@mycompany.com ",
                        "auto_text":"yes",
                        "auto_html":"yes",
                        "track_clicks":"yes",
                        "track_opens":"yes",
                        "custom_fields":[
                        {
                        "field":"pais",
                        "value":"Iceland"
                        }
                        ],
                        "attachments":[
                        {
                        "name":"imagen1.jpg",
                        "type":"image/jpeg",
                        "content":"/9j/77I2ftsq0w4pR9pWVsiusVhkF1KQYFBAYGBQY..."
                        }
                        ]
                        },
                        "to":[
                        {
                        "name":"Some guy",
                        "email":"some@guy.com",
                        "custom_fields":[
                        {
                        "field":"middle_name",
                        "value":"Jerry"
                        },
                        {
                        "field":"pais",
                        "value":"US"
                        }
                        ]
                        },
                        {
                        "name":"Matheu",
                        "email":"matheu@hotmail.com",
                        "custom_fields":[
                        {
                        "field":"middle_name",
                        "value":"Paul"
                        }
                        ]
                        },
                        {
                        "name":"Juan",
                        "email":"juanpablo@hotmail.com",
                        "custom_fields":[
                        {
                        "field":"middle_name",
                        "value":"Pablo"
                        }
                        ]
                        }
                        ],
                        "message_id":"93244347",
                        "custom_fields":[
                        {
                        "field":"actividad",
                        "value":"Comercio"
                        }
                        ],
                        "headers":[
                        {
                        "name":"X-Myheader",
                        "value":"mydata"
                        },
                        {
                        "name":"X-Otherheader",
                        "value":"mydata"
                        }
                        ],
                        "send_at":"2017-12-31 14:30:00 -0400"
                        }

/automation

Manipulación de automatizaciones.

Operaciones
create	Crea una automatización.

/automation/create

Esta acción permite crear tareas automatizadas.

Parámetros
name string	Nombre de para esta automatización.	3 a 60 caracteres alfanuméricos incluidos .,:-_@#!*+%&º
trigger_event string	Evento que dispara la automatización.	subscribe \| unsubscribe \| open \| click \| event \| aniversary.
valid_from integer	Fecha de inicio de validez.	Fecha en formato unix_time.
valid_to integer	Fecha de fin de validez.	Fecha en formato unix_time.
message_id string o array	ID del email o campaña.	Puede ser un string “any” para incluir cualquier mensaje, o un array de mensajes con el o los ID de cada uno.
list_id string o array	IDs de las listas.	Puede ser un string “any” para incluir todas las listas, o un array de listas con el o los ID de cada lista.
custom_field string	Campo a usar para el evento disparados “aniversary”.	Cadena de texto con el nombre del campo según se muestra en la sección de campos personalizados: Por ejemplo “{{{$pf_xdate_aniversario}}}”
event_name string	Nombre del evento externo.	Cadena de texto alfanumérica incluidos .-_
event_value string	Valor del evento externo.

Valores de retorno:
status	“success”.
automation_id	ID alfanumérico de la automatización creada.

Códigos de error:
U10418D	El nombre de la automatización no es válido.
U10430D	La fecha valid_to no puede ser en el pasado.
U10430D	La fecha valid_from no es válida.
U10401D	El evento disparados trigger_event no es válido.
U10416D	No se han definido acciones. Debe definir al menos una acción.
U10402D	Debe proveer al menos un ID de lista list_id para este evento disparador.
U10404D	Una o más listas en list_id no son válidos.
U10403D	list_id debe ser un array de ID’s o una string “any”.
U10405D	Este evento disparador requiere definir list_id.
U10406D	Este evento disparador requiere definir custom_field.
U10408D	El custom_field no se encontró o no tiene un formato válido.
U10407D	El custom_field no se encontró.
U10409D	Uno o más elementos de message_id no son válidos.
U10410D	Uno o más elementos de message_id no son válidos.
U10411D	message_id debe ser “any” o un array con los Id de mensaje.
U10412D	message_id debe ser “any” o un array con los Id de mensaje.
U10412N	No se encontró el enlace definido en link_id o no pertenece a este mensaje.
U10402D	Este evento disparador requiere de list_id.
U10404D	Uno o más elementos de list_id no son válidos.
U10403D	list_id debe ser “any” o un array con los ID de lista.
U10414D	event_name no es válidos.
U10415D	event_value no es válido.
U10426D	Una o más acciones no son válidas.
U10421D	message_id en uno de los elementos de acciones no es válido.
U10425D	send_after id en uno de los elementos de acciones no es válido.
U10422D	list_id en uno de los elementos de acciones no es válido.
U10423D	‘url’ en uno de los elementos de acciones no es una url válida.
U10424D	‘segmentation_id’ en uno de los elementos de acciones no es válido o no fue encontrado.

Ayuda de parámetros

Toda acción de automatización se ejecuta al ocurrir un evento, que es el evento disparador.

El evento disparador se define con el parámetro “trigger_event” y los posibles valores son:

/form

Manipulación formularios de suscripción.

Operaciones
create	Crea un formulario de susripción.

/form/create

Crea un formulario de suscripción.

Parámetros:
list_id string	ID de list a.	String alfanumérico.
include_name boolean	Si desea o no incluir el campo “nombre” en el formulario.
response_url integer	URL para redirigir una vez procesada la solicitud.	Formato válidos de URL.

Valores de retorno
status	“success”.
form_html	HTML del formulario codificado en BASE64.
form_id	ID del formulario creado.
styler_url	URL del modulo para aplicar estilos al formulario.

Códigos de error:
F03301D	No se encontró la lista con el list_id indicado.
F03302D	La URL en ‘response_url” no es válida.

Style

Si lo desea puede utilizar nuestro modulo de estilos para aplicar estilos visuales al formulario. Ingrese a la URL devuelta en ‘styler_url” para cargar el formulario y podes aplicarle estilos.

Los estilos serán aplicados “inline” por lo que el formulario no requerirá de ningún archivo de estilos externo.

Puede copiar y pegar el código HTML resultante o bien obtenerlo vía javascript del elemento <textarea id=” form_html”>

Redireccionamiento

Por defecto, cuando una persona se suscriba vía formulario, será redirigida a una página genérica donde se informará el estado de su suscripción, por ejemplo si la suscripción se realizo o hay algún problema con los datos ingresados en el formulario.

De la misma manera, cuando la persona valide su dirección, también será dirigido a esta página genérica. Si lo desea, puede indicar una URL en ‘response_url’ para que el sistema redirija a esa URL, y de esa manera las personas queden siempre en su sitio.

En esta URL le enviaremos datos adicionales de la operación, como ser la dirección de email y el código de respuesta. Estos datos son llamados Variables de retorno, y se adjuntara en la URL de la siguiente manera:

Si por ejemplo, su URL es «http://www.ejemplo.com/formResponse.php», el sistema direccionara a las personas a una URL de este tipo:

                    http://www.ejemplo.com/formResponse.php?Addr=miemai%40dominio.com&Resp=21

«Addr» será la dirección de email del suscriptor y «Resp» será el código de respuesta.

A continuación puede ver una tabla con los distintos códigos de respuesta y su significado:

1: No es posible procesar su solicitud.
2: Nombre requerido no ingresado.
3: La dirección de email ingresada no es correcta.
6: La dirección de email ingresada ya se encuentra en la lista.
8: La dirección de email a suscribir ya se encuentra en la lista esperando confirmación.
11: La dirección de email a suscribir fue desuscripta en el pasado.
21: Un email le ha sido enviado a su casilla %1 para confirmar la suscripción a la lista.
23: La dirección %1 ha sido suscripta a la lista.
25: Uno o mas datos requeridos no fueron ingresados.

Referencia de API

Conociendo la API

Sobre nuestra API e integración

RESTfull API

URL de la API

Aclaraciones previas

Estructura de la documentación

Llamada a las funciones

Autenticación

Manejo de errores

Errores de API

Ejemplos de request

Módulos y Operaciones

users

list

message

subscriber

txnemail

automation

form

/user

/user/create

/user/edit

/user/delete

/user/credits

/user/list

/user/get

Obtener los detalles de mi cuenta

/user/changeStatus

/user/updateToken

/user/getTokens

/list

/list/create

/list/delete

/list/edit

Datos opcionales

/list/get

/list/list

/list/import

Métodos para cargar los datos

Retorno

/list/importStatus

/list/clone

Estado de la nueva lista

/message

/message/create

Cuerpo del mensaje

Remitente

Listas de destinatarios

Fecha y hora de envío

/message/changeStatus

/message/details

/message/list

Paginación de resultados

/message/stats

Estados del mensaje de campaña

Estadística de rechazados

/subscriber

/subscriber/subscribe

Suscripción y cambio de estado

Automatización

/subscriber/unsubscribe

Automatización

/subscriber/delete

Eliminar de todas las listas

/subscriber/get

Fecha de suscripción y creación

Historial de acciones

txnemail

/txnemail/send

message_id y grupo de mensajes

Campos personalizados

Ejemplo de parámetros con JSON

/automation

/automation/create

Ayuda de parámetros

/form

/form/create

Style

Redireccionamiento