email marketing para envios masivos de email

img

Cree o importe una lista de contactos, diseñe un email o utilice alguna de las plantillas existentes y envíelo, así de simple. Tendrá un diagnóstico completo y detallado de todos los resultados.

Documentación de API de arrobaMail (versión 2)

Introducción

La API (Interfaz de Programación de Aplicaciones) de arrobaMail te permitirá interactuar con la plataforma desde tu sitio web o aplicación externa que desee. Esta ofrece un conjunto de funciones y procedimientos que abstraen la lógica interna de arrobaMail para la facilidad de integración con aplicaciones más complejas o personalizadas.

Sin lugar a dudas esta API junto a la gestión de eventos Web poseen una solución extraordinaria aprovechando todo el poderío del eMail Marketing de arrobaMail.

Disponiendo de una cuenta como cliente de arrobaMail.com en el apartado "API e Integración" del set de Herramientas de la plataforma encontrará las credenciales de acceso al servicio tal lo muestra la siguiente imagen.

API de arrobaMail

RESTful 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.


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 esta documentación

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.
Cada acción esta resaltada. En cada apartado de acción, podrá encontrar una descripción o consideraciones a tener en cuenta, seguido de una tabla de parámetros de entrada, luego una tabla con información sobre los valores de retorno.

Más abajo una tabla con los posible errores y finalmente la información necesaria para entender más el uso de la acción. Algunos parámetros podrían necesitar de una ayuda adicional, en ese caso la encontrara 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://envios.arrobamail.com/api/2.0/message/create o al server que le corresponda a su cuenta, el formato seria: 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               

login_username
string

Nombre de usuario de acceso a la cuenta.

login_password
string

Contraseña de la cuenta

listid
string

Es el identificador de la lista. (Esta variable solo es requerida en el modulo de suscripción). **

user_key
string

Cadena alfanumérica que identifica una cuenta de usuario. (Esta variable solo es requerida en el módulo de emails transaccionales).

(**) Puede encontrar el identificador de cada lista en la sección “Herramientas -> API e integración” o en la configuración de la lista.

 

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.

Por ejemplo:

{
"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.

Codigos de error       

001001A

No se ha proporcionado una user_key o la misma es inválida.

001002A

La cuenta de usuario se encuentra suspendida.

001003E

El módulo no existe. Verifique la URL de consulta.

001004E

La acción no existe. Verifique la URL de consulta.

(**) Puede encontrar el identificador de cada lista en la sección “Herramientas -> API e integración” o en la configuración de la lista.

 

Módulos y operaciones

list

Manipulación de listas

create

Crea una nueva lista e importa suscriptores.

delete

Elimina una lista

get

Obtiene los detalles de una lista

message

Manipulación de mensajes y campañas

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

subscribe

Suscribe una dirección a la lista

unsubscribe

Desuscribe una dirección de una lista

delete

Elimina un suscriptor de una lista

search

Busca un suscriptor en una lista y obtiene sus datos e historial de eventos.

import

Importa dirección a una lista de suscriptores

checkQueue

Verifica el estado de importación de una lista.

txnemail

Manipulación de emails transaccionales

send

Envía un email transaccional

stats

Obtiene las estadísticas de un email transaccional

automation

Manipulación automatizaciones

create

Crea una automatización

form

Manipulación formularios de suscripción

create

Crea un formulario de suscripción

 

/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.

/list/create

Parámetros               

Nombre

Descripción

Formato

name
string

Nombre de la lista

Entre 3 y 60 caracteres alfanuméricos incluidos []-_*!@#.,/+

from_name

Nombre del remitente

3 a 60 caracteres alfanuméricos

from_mail

Email del remitente

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

Errores                      

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/get

Parámetros               

Nombre

Descripción

Formato

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

 

Códigos de error

Errores                      

U02401D

No se encontró la lista con el list_id indicado

 

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/delete

Parámetros               

Nombre

Descripción

Formato

list_id
string

ID de list

String alfanumérico

 

Valores de retorno    

status

“success”

 

Códigos de error

Errores                      

U02401D

No se encontró la lista con el list_id indicado

 

/message

/message/create

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

Parámetros               

Variable

Descripción

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
boolean

Si desea o no hacer seguimiento de aperturas (opcional)

track_clicks
boolean

Si desea o no hacer seguimiento de clicks (opcional)

auto_text
boolean

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

auto_html
boolean

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

g_analytics
boolean

Si se desea o no convertir los enlaces para integrarlos con Google Analytics (opcional)

clicktale
boolean

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
array

Destinatarios. Array con 1 o más elementos que contienen los ID de las listas de destinatarios.

segmentation_id
integer

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

Errores                      

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               

Variable

Descripción

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 programado.

 

Valores de retorno    

status

“success”

 

Códigos de error

Errores                      

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/list

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

Parámetros               

Variable

Descripción

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

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”

 

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

 

Códigos de error

Errores                      

M05101D

Mensaje no encontrado

 

/message/stats

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

Parámetros               

Variable

Descripción

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”

name

Nombre del mensaje o campaña

subject

Asunto del mensaje o campaña

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

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

Errores                      

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.

 

/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.

 

/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               

Variable

Descripción

message
array

Crea un nuevo mensaje con los siguientes parámetros

Variable

Descripción

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 de la cabecera

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 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"
}

 

Ejemplo de consulta utilizando la librería net/http de php

(La librería net/http esta disponible en packagist.org para instalación via composer https://packagist.org/packages/net/http).

<?php

$mail_data = array();

$mail_data["user_key"]                = "YOUR_USER_KEY";
$mail_data["message_id"]              = "1234567890";
$mail_data["send_at"]                 = "2017-03-30 14:05:00 -0300";
$mail_data["message"]["auto_text"]    = 1;
$mail_data["message"]["auto_html"]    = 1;
$mail_data["message"]["track_opens"]  = 1;
$mail_data["message"]["track_clicks"] = 1;

$mail_data["message"]["from_name"] = "John Smith";
$mail_data["message"]["from_mail"] = "johnsmith@mycompany.com";

$mail_data["message"]["subject"] = "...asunto...";
$mail_data["message"]["text"]    = "...texto alternativo...";
$mail_data["message"]["html"]    = "...codigo html...";


$mail_data["to"][] = array(
    "name" => "Juan",
    "email" => "juan@dominio.com",
    "cumstom_field" => array(
        0 => array(
            "name" => "ciudad",
            "value" => "Berlin"
        ),
        1 => array(
            "name" => "genero",
            "value" => "Masculino"
        )
    )
);

// archivos adjuntos
$mail_data["message"]["attachments"][] = array(
    "name" => "image1.jpg",
    "type" => "image/jpeg",
    "content" => base64_encode(file_get_contents("/path/to/imagen1.jpg"))
);

// conexion con la API
$client = new Net_Http_Client();
$client->post("http://{SERVERURL}/api/2.0/txnemail/send", $mail_data);
$responseCode = $client->getStatus();
if ($responseCode != 200) {
    
    $json_str     = $client->getBody();
    $resposeArray = @json_decode($json_str, true);
    
    // ... print_r($resposeArray); ...
}

 

/automation

/automation/create

Esta acción permite crear tareas automatizadas

Parámetros               

Nombre

Descripción

Formato

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

Errores                      

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:
subscribe | unsubscribe | open | click | event | aniversary

 

/form

/form/create

Crea un formulario de suscripción

Parámetros               

Nombre

Descripción

Formato

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
string

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

Errores                      

F03301D

No se encontró la lista con el list_id indicado

F03302D

La URL en ‘response_url” no es válida.

 
Styler

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