MAILING SERVER
HTTP GATEWAY
Versión 1.7
Esta API permite el acceso a todas las características de 360nrs usando Json.
[Link] 1
ÚLTIMOS CAMBIOS
Versión 1.4 18/09/2017 Añadidas las funcionalidades para listar, actualizar y eliminar
envíos programados, Corrección de errores
Versión 1.5 07/11/2017 Añadidos parámetros campaignName y tags
Versión 1.6 16/04/2018 Añadidos ejemplos Python, Java y C#
Versión 1.7 04/01/2019 Añadido parámetro templateId
[Link] 2
ÍNDICE
INTRODUCCIÓN Pág. 4
PLATAFORMA TÉCNICA Pág. 4
Petición de envío de email Pág. 5
Parámetros Pág. 5
Ejemplo de petición básica Pág. 6
Ejemplo de petición CURL Pág. 6
Ejemplo de petición PHP Pág. 6
Ejemplo de petición PYTHON Pág. 7
Ejemplo de petición JAVA Pág. 7
Ejemplo de petición C# Pág. 8
Ejemplos de respuesta Pág. 10
Gestión de mensajes programados Pág. 11
Listado Pág. 11
Parámetros Pág. 11
Ejemplos de petición Pág. 11
Ejemplos de respuesta Pág. 11
Actualización Pág. 12
Parámetros Pág. 12
Ejemplos de petición Pág. 12
Ejemplos de respuesta Pág. 12
Borrado Pág. 13
Parámetros Pág. 13
Ejemplos de petición Pág. 13
Ejemplos de respuesta Pág. 13
Ejemplos de respuesta (errores) Pág. 14
[Link] 3
INTRODUCCIÓN
La plataforma http server permite al usuario enviar mensajes a través de esta plataforma.
Para poder acceder a sus estadísticas y datos de facturación puede acceder a la web
[Link] con sus datos de usuario.
La comunicación entre el cliente no se realizará a través de ningún API proporcionado por
la Empresa, sino que simplemente se realizará una comunicación HTTP, con algunos
parámetros a la URL indicada. Este proceso se detalla a continuación.
PLATAFORMA TÉCNICA
Antes de poder realizar un envío a través de la plataforma API es necesario validar la
dirección de email de remitente a utilizar en el envío. Para esto se debe acceder al
dashboard de usuario “Herramientas” > “Verificación de emails” y seguir los pasos
indicados en el asistente para la verificación.
Cada petición que se realice tendrá que incluir en la cabecera de la petición http la
autenticación del cliente. Para ello se utiliza la autenticación de acceso básica de HTTP.
La cabecera de autorización se construye combinando la cadena “usuario: contraseña” y
codificándola en base64. A esta cadena se antepone la cadena “Authorization: Basic”
Por ejemplo, para el usuario “miuser” y el password “mipass” la cabecera resultante sería:
Authorization: Basic bWl1c2VyOm1pcGFzcw==
A continuación se detallará las opciones de envío disponibles, la URL a la que se debe
llamar, y los parámetros que admite.
[Link] 4
PETICIÓN ENVÍO DE EMAIL
URL: [Link]
MÉTODO: POST
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
body string No Cuerpo del email en formato
HTML y codificación UTF-8.
Requerido sin templateId
templateId integer No ID de plantilla para enviar como
cuerpo del email. Requerido sin
body.
to array Sí emails de los destinatarios del
envío. Este campo permite
indicar multiples destinatarios.
fromEmail string Sí Email del remitente. La dirección
de correo indicada debe estar
validada en la plataforma de
360NRS.
subject string Sí Breve resumen del tema del
mensaje.
fromName string No Nombre del remitente del envío.
replyTo string Sí Dirección que debe utilizarse
para responder al mensaje.
scheduleDate string No Fecha de envío del mensaje en
formato UTC. Si se necesita enviar
mensajes programados se puede
especificar la fecha de envío
indicando la fecha en formato
YYYYmmddHHiiss (Ej:
20130215142000 sería el 15 de
febrero de 2013 a las 14:20:00). En
caso de envío inmediato no se tiene
que especificar este parámetro.
campaignName string No Nombre de campaña. Si se
especifica se creará una
campaña con el nombre indicado
en el dashboard que contendrá
las estadísticas del envío. Si una
campaña con este nombre ya
existe, las estadísticas de envío
se añadirán a la campaña
existente.
tags array No campaignName es requerido si
se especifica este parámetro.
[Link] 5
Listado de tags a añadir a la
campaña. Los tags pueden ser
utilizados para filtrar las
estadísticas en el dashboard.
EJEMPLO DE PETICIÓN BÁSICA
{"body":"Test api", "to":["myemail@[Link]"], "subject":"HELLO", "fromEmail":
"info@[Link]"}
Nota: Para generar una URL de baja hay que añadir: [unsubscribe_link] dentro del href de un link
en el parámetro “body”. Por ejemplo: <a href="[unsubscribe_link]">Enlace</a>
EJEMPLO DE PETICIÓN CURL
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic
bWl1c2VyOm1pcGFzcw==" -d "{\"body\":\"Test api\", \"to\":[\"myemail@[Link]\"],
\"subject\":\"HELLO\", \"fromEmail\": \"info@[Link]\"}"
[Link]
EJEMPLO DE PETICIÓN PHP
<?php
$post["to"] = array("myemail@[Link]");
$post["body"] = "Test api";
$post["subject"] = "HELLO";
$post["fromEmail"] = "info@[Link]";
$post["replyTo"] = "info@[Link]";
$user ="miuser";
$password = "mipass";
try {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "[Link]
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post));
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Accept: application/json",
"Authorization: Basic " . base64_encode($user . ":" . $password)));
$result = curl_exec($ch);
var_dump($result);
} catch (Exception $exc) {
echo $exc->getTraceAsString();
}
[Link] 6
EJEMPLO DE PETICIÓN PYTHON
import base64
import json
import pycurl
if __name__ == "__main__":
url = "[Link]
usrPass = "miuser:mipass"
data = [Link]({\
"to":["myemail@[Link]"],
"fromEmail":"info@[Link]",
"subject":"HELLO",
"body":"Test Api",
"campaignName":"Nombre Campana",
"replyTo":"info@[Link]"})
b64Val = base64.b64encode(usrPass)
headers = ["Accept:Application/json", "Authorization:Basic %s" % b64Val]
c = [Link]()
[Link]([Link], url)
[Link]([Link], headers)
[Link]([Link], 1)
[Link]([Link], data)
[Link](pycurl.SSL_VERIFYHOST, 0)
[Link](pycurl.SSL_VERIFYPEER, 0)
[Link]()
http_code = [Link](pycurl.HTTP_CODE)
print(http_code)
EJEMPLO DE PETICIÓN JAVA
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
import [Link];
public class ApiMail {
public static void main(String args[]) throws IOException {
String url = "[Link]
URL obj = new URL(url);
HttpsURLConnection con = (HttpsURLConnection) [Link]();
//add request header
[Link] 7
[Link]("POST");
String userpass = "miuser" + ":" + "mipass";
String basicAuth = "Basic " +
[Link].printBase64Binary([Link]("UTF-8"));
[Link]("Authorization", basicAuth);
[Link]("Accept", "application/json");
JSONObject data = new JSONObject();
JSONArray to = new JSONArray();
[Link]("myemail@[Link]");
[Link]("to", to);
[Link]("fromEmail", "info@[Link]");
[Link]("subject", "HELLO");
[Link]("body", "Test Api");
[Link]("campaignName", "Nombre Campaña");
[Link]("replyTo", "info@[Link]");
String jsonText = [Link]();
// Send post request
[Link](true);
try (DataOutputStream wr = new DataOutputStream([Link]())) {
[Link](jsonText);
[Link]();
[Link]();
int responseCode = [Link]();
String mensaje = [Link]();
[Link]("\nSending 'POST' request to URL : " + url);
[Link]("Post parameters : " + data);
[Link]("Response Code : " + responseCode);
[Link]("Mensaje : " + mensaje);
BufferedReader in = new BufferedReader(
new InputStreamReader([Link]()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = [Link]()) != null) {
[Link](inputLine);
}
[Link]();
//print result
[Link]([Link]());
// read this input
[Link] 8
}
EJEMPLO DE PETICIÓN C#
using [Link];
using System;
using [Link];
using [Link];
namespace nrs_api
{
class Program
{
static void Main(string[] args)
{
var httpWebRequest =
(HttpWebRequest)[Link]("[Link]
;
[Link] = "POST";
[Link] = "application/json";
String username = "miuser";
String password = "mipass";
String encoded =
[Link].ToBase64String([Link]("ISO-8859-1").GetBy
tes(username + ":" + password));
[Link]("Authorization", "Basic " + encoded);
using (var streamWriter = new
StreamWriter([Link]()))
{
string[] to = new string[1];
to[0] = "myemail@[Link]";
var fromEmail = "info@[Link]";
var subject = "HELLO";
var body = "Test Api";
var campaignName = "Nombre Campaña";
var replyTo = "info@[Link]";
var data = new
{
to = to,
fromEmail = fromEmail,
subject = subject,
body = body,
campaignName = campaignName,
replyTo = replyTo
};
string json = [Link](data);
[Link] 9
[Link](json);
[Link]();
[Link]();
}
var httpResponse = (HttpWebResponse)[Link]();
using (var streamReader = new
StreamReader([Link]()))
{
var result = [Link]();
[Link](result);
[Link]();
}
}
}
La clave de acceso (password) y el código del cliente (username) serán proporcionados
por la empresa. Hay que comentar que con objeto de aumentar la seguridad del sistema,
el cliente deberá indicar la IP desde donde se va a conectar, solo se permitirán envíos de
la IP indicada por el cliente.
EJEMPLOS DE RESPUESTA
CÓDIGO ESTADO 202 (ACCEPTED):
[{"accepted":true,"to":"myemail@[Link]","id":"102648819"}]
CÓDIGO ESTADO 207 (MULTI-STATUS):
[{"accepted":true,"to":"myemail@[Link]","id":"102648820"},{"accepted":false,
"to":"[Link]","error":{"code":102,"description":"No valid recipients"}}]
[Link] 10
GESTIÓN DE MENSAJES PROGRAMADOS
LISTADO
Lista todos los envíos programados. Puede filtrarse por tipo (SMS o MAILING) y
puede
especificarse un GUID, varios GUID o ningún GUID (para listar todos).
El contenido del mensaje no se muestra en la lista, a no ser que se especifique un único
GUID.
URL: [Link]
MÉTODO: GET
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
guid integer, array No Identificador del mensaje o
mensajes.
Se le puede pasar un
identificador, un array de
identificadores o ninguno para
mostrarlos todos.
type string No SMS o MAILING
EJEMPLOS DE PETICIÓN
[Link]
[Link]
[Link]
[Link]
[Link]
EJEMPLOS DE RESPUESTA
Con varios GUID o sin GUID:
{"result":[
{"guid":"100","type":"MAILING","created_at":"2017-09-18 10:49:12","updated_at":"2017-09-18
10:49:12","scheduled_at":"2017-11-11 10:10:10"},
{"guid":"101","type":"MAILING","created_at":"2017-09-18 10:49:12","updated_at":"2017-09-18
10:49:12","scheduled_at":"2017-11-11 10:10:10"},
{"guid":"102","type":"SMS","created_at":"2017-09-18 10:49:12","updated_at":"2017-09-18 10:49:12","scheduled_at":"2017-11-11
10:10:10"}
],"total":3}
Especificando un único GUID:
{"result":{"guid":"100","type":"MAILING","content":"Contenido del EMAIL","created_at":"2017-09-18
10:49:12","updated_at":"2017-09-18 10:49:12","scheduled_at":"2017-11-11 10:10:10"},"total":1}
[Link] 11
ACTUALIZACIÓN
Actualiza la fecha de programación un envío, varios envíos o todos los envíos
programados.
Puede filtrarse por GUID y/o tipo.
CUIDADO: Si no se especifica ningún GUID se actualizarán todos los mensajes
programados.
URL: [Link]
MÉTODO: PUT
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
guid integer, array No Identificador del mensaje o
mensajes.
Se le puede pasar un
identificador, un array de
identificadores o ninguno para
mostrarlos todos.
type string No SMS o MAILING
scheduleDate string Sí Fecha de envío del mensaje en
formato UTC. Si se necesita
enviar mensajes programados se
puede especificar la fecha de
envío indicando la fecha en
formato YYYYmmddHHiiss (Ej:
20130215142000 sería el 15 de
febrero de 2013 a las 14:20:00).
En caso de envío inmediato no se
tiene que especificar este
parámetro.
EJEMPLOS DE PETICIÓN
{"guid": 100, "scheduleDate": "20171011093000"}
{"guid": [100,101], "scheduleDate": "20171011093000"}
{"type": "MAILING", "scheduleDate": "20171011093000"}
{"scheduleDate": "20171011093000"}
EJEMPLOS DE RESPUESTA
{"result":true,"updated":1}
{"result":true,"updated":2}
[Link] 12
BORRADO
Elimina un envío, varios envíos o todos los envíos programados.
Puede filtrarse por GUID y/o tipo.
CUIDADO: Si no se especifica ningún GUID se borrarán todos los mensajes
programados.
URL: [Link]
MÉTODO: DELETE
PARÁMETROS
Parámetro Tipo Obligatorio Descripción
guid integer, array No Identificador del mensaje o
mensajes.
Se le puede pasar un
identificador, un array de
identificadores o ninguno para
mostrarlos todos.
type string No SMS o MAILING
EJEMPLOS DE PETICIÓN
{"guid": 100}
{"guid": [100,101]}
{"type": "MAILING"}
EJEMPLOS DE RESPUESTA
{"result":true,"deleted":1}
{"result":true,"deleted":2}
[Link] 13
CÓDIGOS DE RESPUESTA
CÓDIGO ESTADO 400 (BAD REQUEST):
{"error":{"code":102,"description":"No valid recipients"}}
{"error":{"code":104,"description":"Text message missing"}}
{"error":{"code":105,"description":"Text message too long"}}
{"error":{"code":106,"description":"Sender missing"}}
{"error":{"code":107,"description":"Sender too long"}}
{"error":{"code":108,"description":"No valid Datetime for send"}}
{"error":{"code":109,"description":"Notification URL incorrect"}}
{"error":{"code":110,"description":"Exceeded maximum parts allowed or incorrect number of parts"}}
{"error":{"code":113,"description":"Invalid coding"}}
{"error":{"code":120,"description":"Invalid GUID"}}
{"error":{"code":121,"description":"Invalid scheduled date"}}
CÓDIGO ESTADO 401 (UNAUTHORIZED):
{"error":{"code":103,"description":"Username or password unknown"}}
{"error":{"code":111,"description":"Not enough credits"}}
CÓDIGO ESTADO 402 (PAYMENT REQUIRED):
{"error":{"code":111,"description":"Not enough credits"}}
CÓDIGO ESTADO 500 (INTERNAL SERVER ERROR):
{"error":{"code":122,"description":"Update error"}}
{"error":{"code":123,"description":"Delete error"}}
[Link] 14