Saltar a: navegación, buscar

Envios mailing transaccionales


Revisión del 10:49 24 ene 2019 de Deneb (discusión | contribuciones) (Cómo enviar desde su plataforma)
(dif) ← Revisión anterior | Revisión actual (dif) | Revisión siguiente → (dif)

Introducción

Los envíos de email transaccionales son envíos que se realizan automáticamente al ejecutarse una acción preestablecida. En esta documentación se detalla la integración que ha de realizar en su plataforma para poder utilizar este servicio. Será necesario:

  • Ser propietario de una base de datos.
  • Configurar una dirección de IP válida desde la que enviar los emails.
  • Configurar un dominio y una dirección de email desde la que enviar.
  • Integrar el código en su plataforma.

Bases de datos

Para poder realizar envíos transaccionales, debe ser propietario de, al menos, una base de datos (BBDD) en Mobeleader. Si no lo es, cree una base de datos en la sección Integración BBDD o consulte con su administrador. Introduzca los datos de su BBDD:

Crear bd.png

Una vez creada, podrá consultar las características de su BBDD desde la sección BBDD del Panel Mobeleader:

Mostrar bds.png

Configuración de IPs válidas

Si ya es propietario de una BBDD, lo siguiente que debe hacer es asociar una dirección IP a la BBDD que quiera usar como referencia. Esta dirección IP ha de coincidir con la dirección IP desde la que envíe el email transaccional, es decir, la dirección IP del servidor en el que se aloje el archivo desde el que se ejecute el envío.

Para asociar una IP a su base de datos, deberá hacerlo desde la sección IPs válidas del Panel Mobeleader. Se mostrará una lista con sus bases de datos (siempre y cuando haya creado una).

Tabla ips.png

Pulse el botón Añadir nueva IP e introduzca el valor de la dirección IP en el cuadro de texto.

Guardar ip.png

Una vez introducida la dirección IP, pulse el botón Guardar IP y ésta quedará asociada a la BBDD. Puede eliminar o cambiar el valor de cualquier dirección IP cuando lo desee.

Mensaje ip.png

Configuración del dominio y la dirección de email de envío

Para que el sistema reconozcan el email adress (dirección de email) desde el que quiera realizar sus envíos transaccionales, debe configurar al menos un dominio y asignar el email adress a ese dominio. Para crear el dominio, deberá hacerlo desde la sección Crear Dominio.

Dominio.png

Al asociar los senders externos al dominio, asegúrese de que al menos uno de ellos pueda realizar envíos transaccionales. Puede comprobar los tipos de envío de cada sender externo en la sección Senders externos.

Una vez tenga asociado el dominio a la BBDD, ha de asignar a ese dominio el email adress desde el cual realizar sus envíos transaccionales. Para crear y asignar el email adress, debe hacerlo desde la sección Crear Email.

Email.png

Al asociar el sender externo al email adress, asegúrese de que éste pueda realizar envíos transaccionales.

Cómo enviar desde su plataforma

Una vez tenga la dirección IP, el dominio y el email configurados correctamente y asociados a una BBDD, deberá descargar el archivo MobeleaderTransaccional e implementarlo al archivo PHP desde el que quiera realizar el envío transaccional. Descargue el archivo desde aquí. Para poder realizar los envíos necesitará:

  • El identificador de la BBDD de referencia.
  • Su identificador de usuario.

Identificador de la BBDD

Obtenga el identificador de la BBDD desde la sección IPs Válidas, pulsando en el icono Eye.png Ver Hash de la BBDD que corresponda.

Hash.png

Identificador de Usuario

Para obtener el identificador de usuario diríjase a la sección Mis Datos del Panel de Mobeleader y pulse en Ver claves RSA. Una vez dentro del popup, copie la cadena perteneciente al campo Public Identifier.

Public id.png

Envío directo

Para enviar directamente los emails, instancie la clase MobeleaderMailing, descargada previamente en el archivo MobeleaderTransaccional, con los argumentos bbdd_id, que incluirá la cadena con el identificador de la BBDD, y user_id, con el identificador de usuario:

include "PATH..../mobeleadermailing.php";
$mobeleaderMailing = new MobeleaderMailing('bbdd_id','user_id');

Envío cifrado

Si desea cifrar los envíos, puede hacerlo utilizando la clase spsApiConnection de Mobeleader.

Uso de la clase spsApiConnection

La clase spsApiConnection, esta pensada para una mayor comodidad del cliente, permitiendo que todo se gestione desde la clase sin necesidad de tener que programar las llamadas y retornos de la API. Puede descargar el archivo desde aquí. A continuación se exponen los pasos a seguir para un correcto funcionamiento de la clase:

Instalación PHPSECLIB

Será necesario disponer de phpseclib versión 2.0.11 o superior. Para instalar esta versión de phpseclib deberá:
- Disponer de la herramienta "composer.phar"
- Ejecutar "composer" en la carpeta donde vaya a instalar nuestra librería.

1.- Descargar composer desde: https://getcomposer.org/composer.phar

curl https://getcomposer.org/composer.phar -o composer.phar


2.- Ejecutar el comando:

php composer.phar --working-dir=. require phpseclib/phpseclib:~2.0


Hecho esto, obtendrá la siguiente salida por consola:

./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Installing phpseclib/phpseclib (2.0.11): Downloading (100%)         
phpseclib/phpseclib suggests installing ext-libsodium (SSH2/SFTP can make use of some algorithms provided by the libsodium-php extension.)
phpseclib/phpseclib suggests installing ext-mcrypt (Install the Mcrypt extension in order to speed up a few other cryptographic operations.)
phpseclib/phpseclib suggests installing ext-gmp (Install the GMP (GNU Multiple Precision) extension in order to speed up arbitrary precision integer arithmetic operations.)
Writing lock file
Generating autoload files


Esto significa que está todo lo necesario instalado en su carpeta vendor.

Clase spsApiConnection

Una vez instalada la librería PHPSECLIB en su carpeta vendor, lo primero que deberá hacer es abrir la clase y modificar la ruta de acceso a dicha carpeta.

require_once 'PATH..../vendor/autoload.php';


Tras modificar la ruta, para poder instanciar la clase, será necesario obtener la clave Private RSA Key, accesible desde la sección Mis Datos del Panel de Mobeleader.

Boton rsa keys.png


Pulsando en Ver claves RSA, se abrirá un popup en el que podrá obtener las claves RSA.

Rsa keys.png

Instancia de la clase para el envío cifrado

Para enviar los emails cifrados, instancie la clase MobeleaderMailing, descargada previamente en el archivo MobeleaderTransaccional, con los argumentos bbdd_id, que incluirá la cadena con el identificador de la BBDD, user_id, con el identificador de usuario y Private_RSA_key obtenida previamente. Es necesario copiar la cadena completa, incluyendo -----BEGIN RSA PRIVATE KEY----- y -----END RSA PRIVATE KEY-----:

require_once "PATH..../mobeleadermailing.php";
require_once "PATH..../api_connection_class.php";
$mobeleaderMailing = new MobeleaderMailing('bbdd_id','user_id','Private_RSA_key');

Etiqueta o Tag del email

Es necesario establecer una etiqueta o tag al objeto MobeleaderMailingantes de realizar los envíos. El tag indicará y clasificará el tipo de email que desea enviar. Puede establecer o modificar el tag que desee para cada envío o grupo de envíos:

$mobeleaderMailing->setTag('Replay to email');

Una vez creado el objeto MobeleaderMailing, tiene dos opciones para realizar los envíos: enviar mensajes en formato raw (raw message), o construir los mensajes con sus campos y enviarlos.

Envíos en formato raw

Para enviar un email en formato raw o raw message, utilice la función sendRaw( ) de la clase Mobeleadermailing. Envíe como argumento de la función la cadena completa del raw message. Puede hacerlo de la siguiente manera:

$rawMessageString = "Date: Mon, 21 Jan 2019 17:25:57 +0200
To: receiver@ receiverdomain.com
From: Mobeleader <tests@emails.mobilesender.com>
Reply-To: Mobeleader <tests@emails.mobilesender.com>
Subject: =?utf-8?Q?My subject?=
X-Mailer: PHPMailer 5.2.14 (https://github.com/PHPMailer/PHPMailer)
MIME-Version: 1.0
Content-Type: multipart/alternative;
	boundary=\"b1_c9b653839eb515afdd16fd1670d086c5\"
Content-Transfer-Encoding: 8bit

This is my email in plain text

--b1_c9b653839eb515afdd16fd1670d086c5
Content-Transfer-Encoding: 8bit
<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">
<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\"><head><meta http-equiv=\"content-type\" content=\"text/html; charset=UTF-8\" /></head><body><div>This is my email in HTML format</div></body></html>
--b1_c9b653839eb515afdd16fd1670d086c5--";

$message = $mobeleaderMailing->sendRaw($rawMessageString);

Envíos en formato array de campos

Para enviar un email construido con sus propios campos, utilice la función send( ) de la clase Mobeleadermailing. Debe crear un array con los campos del email como claves y un string por cada valor de los campos. Los campos a enviar serán los siguientes:

  • html: cadena del código HTML que desee mostrar como contenido del email.
  • txt: contenido del email en formato de texto plano.
  • subject: asunto del email.
  • from_name: alias o nombre de quien envía el email.
  • from_email: dirección de correo desde la que se envía el email.
  • to_email: dirección de correo a la que se envía el email.


Envíe el array construido como argumento de la función. Puede hacerlo de la siguiente manera:

$messageArray = array();
$messageArray['html'] = '<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">
<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\"><head><meta http-equiv=\"content-type\" content=\"text/html; charset=UTF-8\" /></head><body><div>This is my email in HTML format</div></body></html>';
$messageArray['txt'] = 'This is my email in plain text';
$messageArray['subject'] = 'My subject';
$messageArray['from_name'] = 'Mobeleader';
$messageArray['from_email'] = 'tests@emails.mobilesender.com';
$messageArray['to_email'] = 'receiver@receiverdomain.com';

$message = $mobeleaderMailing->send($messageArray);

Retorno

Tanto la función sendRaw( ) como send( ) devuelven un JSON con la información relativa al envío. Mostrará los siguientes campos:

  • mail_sent: indica si el email se ha enviado correctamente. Devolverá true en caso afirmativo, false en caso contrario.
  • error: indica si ha habido algún error en el envío.
  • info: si el email se ha enviado correctamente, se mostrará este campo con los datos del envío.


  • Ejemplo de retorno de un email enviado correctamente:


{
     "mail_sent":true,
     "info":{
          "subject":"My subject",
          "from_email":"tests@emails.mobilesender.com",
          "from_name":"Mobeleader",
          "to_email":"receiver@receiverdomain.com",
          "html":"<html><body><div>This is my email in HTML format<\/div><\/body><\/html>",
          "txt":"This is my email in plain text"
     },
     "error":"Not error found"
}


  • Ejemplo de retorno de un email no enviado:


{
     "mail_sent":false,
     "error":"Client refused. Incorrect data base hash."
}