¿Cómo agregar un subscriptor mediante la API?

Hay veces que queremos incorporar funciones de la plataforma de arrobaMail a sistemas propios o internos para tener mayor comodidad o productividad a la hora de realizar esas tareas.

arrobaMail cuenta con una API para integrar funcionalidades de la plataforma a cualquier sitio o sistema que usted disponga. Para ello representaremos un ejemplo de una de las integraciones más sencillas que es agregar un subscriptor mediante la API a una lista previamente creada, pero servirá para mostrar el uso y potencial de las APIs.

Lo primero a realizar es irnos a nuestro panel de arrobaMail y hacer un clic en el botón del margen superior derecho llamado “Herramienta”, luego de eso iremos a “API e integración” y accederemos a un panel como el siguiente:

Ahí se nos otorgará información para el uso de la API, es conveniente revisar que tengamos autorizada la IP del servidor donde se ejecute este script que se conectará con la API, para ello en el campo “Agregar IP/Rango” puede agregar la IP específica de un solo equipo o agregar varias o un rango estableciendo tales valores de direcciones de IP.

Luego debemos tener una Lista creada para agregar subscriptores, para ello nos vamos al botón que se encuentra arriba de “SUBSCRIPTORES” y de ella conocer su “list_id”. Si tiene alguna lista creada le aparecerá algo como esto:

Listas

Si no tiene ninguna lista puede crear una desde el botón “Crear nueva lista” siguiendo los pasos que le muestra el asistente.

Posteriormente volveremos al menú mencionado y daremos clic sobre la lista, al abrirla se nos aparecerá información de la misma y ahí obtendremos el valor del identificador de la lista a utilizar mediante la API.

Vista previa

El tipo de API que usa arrobaMail es de tipo REST, para usarla solo tiene que hacer peticiones web HTTP al servidor con los campos necesarios, y nos devolverá un objeto JSON con un estado de cómo fue la petición. Por supuesto se recomienda tener conocimientos previos de estos lenguajes de programación y web services para el uso de estas herramientas de integración.

A continuación un ejemplo hecho en JavaScript donde se tomarán valores de un formulario hecho en HTML, para mayor facilidad utilizaremos la librería JQuery para realizar las peticiones.

Crearemos un documento con extensión .HTML y un archivo Javascript con los siguientes códigos:

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <title>Agregar subscriptor</title>
</head>
<body>
    <form method="post">
        <label for="name">Nombre</label>
        <input type="text" id="name" name="name">
        <label for="email">Email</label>
        <input type="email" id="email" name="email">
        <button id="send">Enviar</button>

    </form>
</body>
</html>
    'use strict';
    var send = document.getElementById('send');
    send.onclick = function() { 
        var user_key = "779e3e98f9292929292gewt"; 
        var listid = "989865D7F";
        var name = document.getElementById("name").value; 
        var email = document.getElementById("email").value;
        $.ajax({
            url: 'http://su.arrobamail.com/api/2.0/subscriber/subscribe',
            data:{
                'user_key': user_key,
                'list_id' : listid,
                'email' : email,
                'name' : name
            },
            type: 'POST',
            dataType: 'json',
            success : function(json) {
                $('<h1/>').text(json.title).appendTo('body');
                $('<div class="content"/>')
                    .html(json.html).appendTo('body');
                },
            // código a ejecutar si la petición falla;
            error : function(xhr, status) {
                alert('Disculpe, existió un problema');
            },
        
            // código a ejecutar sin importar si la petición falló o no
            complete : function(xhr, status) {
                alert('Petición realizada');
            }
            
            
        })
    }

El código es básico, primero se presenta un formulario HTML desde donde tomaremos los datos de “name” y “email”, luego con Javascript haremos que al presionar el botón se ejecute el script para recibir y enviar los datos mediante la API.

Realizamos la petición AJAX con la línea “$.ajax”, en las líneas siguientes indicamos los campos que se nos solicitan en el objeto “data” para finalmente enviar la petición mediante POST y evaluar el mensaje de estado en caso que falle o no.

Los campos “user_key“” y “list_id” se tendrán que remplazar con los datos de su usuario, son los datos de usuario y contraseña más la información que ya obtuvo en los pasos anteriores. Los valores de “subscribed” o “update” son opcionales pero se le pueden agregar a la petición, el primer valor sirve para confirmar o no como subscrito al cliente que agregue a la lista, el otro valor sirve para determinar si la persona ya estaba en la lista, y en ese caso si se actualicen sus datos o simplemente devuelva un error.

Usar campos personalizados

Si queremos usar campos personalizados en nuestras listas y usar la API para agregar un suscriptor podemos hacerlo de la siguiente manera.

Primero debemos crear un campo personalizado desde nuestro panel de arrobaMail, primero debemos ir a nuestra sección de “SUBSCRIPTORES” como vimos antes, y acceder a una lista. Ya teniendo eso nos vamos a dar en el botón “Campos personalizados” que se encuentra en el panel de la derecha:

 

Con esto lo próximo que debemos hacer es Crear el campo, esto es muy sencillo, hay un  menú en la parte inferior que nos facilitara esto

Podemos utilizar los campos predefinidos  y podemos personalizar uno, a partir de tener esto realizado le damos al botón crear.

Ya con el campo realizado nos aparecerá los campos creados y en unas de las columnas estará el “TAG” para poder llamarlo y así utilizarlo para llamar a la API, a continuación anotaremos ese nombre y lo usaremos para realizar la petición de esta manera, solo debemos modificar nuestro Script JS ya previamente creado:

    $.ajax({
        url: 'http://su.arrobamail.com/api/2.0/subscriber/subscribe',
        data:{
            'user_key': user_key,
            'list_id' : listid,
            'update' : true,
            'email' : email,
            'name' : nombre,
            'custom_fields' : [ // Este es el campo que agregamos
                { // Aca tenemos que agregar los campos personalizados que tengamos 
                    'name': '{{{$pf_campo_personalizado}}}', // Este es el TAG del campo personalizado
                    'value' : value // Y este es el valor que le enviariamos
                
                }
            ]
            
        },
        type: 'POST',
        dataType: 'json',
        success : function(json) {
            $('<h1/>').text(json.title).appendTo('body');
            $('<div class="content"/>')
                .html(json.html).appendTo('body');
            },

        // código a ejecutar si la petición falla;

        error : function(xhr, status) {
            alert('Disculpe, existió un problema');
        },

        // código a ejecutar sin importar si la petición falló o no
        complete : function(xhr, status) {
            alert('Petición realizada');
        }
        
        
    })

 

Esta es una de las formas de hacer uso de las varias funciones que tiene la API de arrobaMail, si quiere conocer más en detalle puede consultar la documentación haciendo clic desde aquí.

Comentarios