Guía completa de configuración de PHPMailer

En esta guía que traemos hoy en Ayuda Hosting te estaremos brindando una guía completa de configuración de PHPMailer.

Cuando queremos agregar más funciones de correo electrónico a nuestra aplicación PHP, es importante hablar de PHPMailer. Esta herramienta es compatible con una gran parte de los frameworks PHP. PHPMailer se podría decir que es uno de los elementos más potentes para crear correos electrónicos HTML con archivos adjuntos y enviar los distintos destinatarios por medio de SMTP o utilizando un servidor local.

¿Qué es PHPMailer?

PHPMailer es una de las clásicas bibliotecas de envío de correo electrónico para PHP. Cuenta con distintas formas para enviar mensajes de correo electrónico como Qmail, Sendmail y el envío directo de servidores SMTP. Además, estará contando con distintas características como las siguientes:

• Autenticación SMTP.
• Soporte para protocolos SSL y TLS.
• MIME / Cifrado seguro.
• Distintos archivos fs, string y binarios.
• Contenido HTML con texto sin formato.
• Soporte para imágenes incrustadas.

Envío de correo electrónico por medio de PHPMailer y SMTP

Para comenzar a enviar correos electrónicos por medio de PHPMailer y SMTP, en primer lugar tendremos que llevar a cabo la instalación de PHPMailer y realizar la configuración de SMTP.

IMPORTANTE: para emplear PHPMailer es necesario tener configurado SMTP.

También le puedes echar un vistazo a nuestras guías de configuración de correos SMTP para WordPress y PrestaShop.

Cómo llevar a cabo la instalación de PHPMailer

Anteriormente hasta su versión 5, PHPMailer cuenta con un archivo «PHPMailerAutoload.php» por lo que todo lo que necesitabas venía incluido en un script que te permitía crear una instancia de PHPMailer. Luego de que se llevó a cabo el lanzamiento de PHPMailer 6.0 en 2017, se debe instalar, preferiblemente utilizando Composer como administrador de dependencia para PHP. Luego de que lleves a cabo la instalación de Composer, debes agregar la línea de código que mostramos a continuación en tu archivo composer.json:

"phpmailer/phpmailer": "~6.0"

o

composer require phpmailer/phpmailer

Por el contrario, si no deseas instalar Composer, debido a que estas trabajando en un entorno de prueba por ejemplo, podrás agregar PHPMailer de forma manual. Tienes que descargar los archivos con el código fuente de PHPMailer, y luego copiarlos directamente en el contenido de la carpeta PHPMailer en los directorios include_path que estén especificados en la configuración PHP. Luego se debe cargar cada archivo de clase de forma manual.

<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'path/to/PHPMailer/src/Exception.php';
require 'path/to/PHPMailer/src/PHPMailer.php';
require 'path/to/PHPMailer/src/SMTP.php';

Se debe agregar una excepción de clase para que puedas solucionar ciertos errores y depurarlos correctamente. En PHP estará funcionando de forma similar a otros lenguajes de programación. Es por ello, que sin él, si existe un error en el código de envío de correo electrónico, estarás visualizando un mensaje que dice que no se ha podido encontrar la excepción de clase, pero no se te proporcionaran proporcionando los detalles para depurarla.

Para contar con  opciones mucho más detallada sobre la instalación, puedes dirigirte a la documentación oficial de PHPMailer en Github.

Configurar SMTP

Antes de continuar con este paso, es importante contar con un certificado SSL para tu sitio web, así evitarás problemas con la configuración. En caso de que no lo tengas, le puedes echar un vistazo a nuestra guía para activar el modo seguro en tu sitio web.

Una vez cuentes con el certificado SSL puedes seguir adelante y crear una cuenta de correo electrónico directamente desde el cPanel. Para ello puedes emplear un correo de prueba para así no inundar la bandeja de entrada de nuestros clientes con correos que no tienen alguna finalidad por el momento. Al terminar la fase de prueba y observes que todo este correcto, puedes utilizar el correo con el que quieres realizar el envío de correos electrónicos.

Ahora que has creado el correo que vas a utilizar, vamos a proceder a la autenticación SMTP. Para ello debemos ir al listado de correos en el aparto de Correo electrónico en cPanel y hacer clic en Cuentas de correo electrónico.

Al hacer clic allí, nos estará apareciendo una lista con todos los correos que hemos creado. Para continuar debemos hacer clic en Connect Devices.

En este apartado estarás encontrando los datos que necesitas para autenticar PHPMailer con SMTP como lo son: servidor, usuario, contraseña y puerto.

Ahora debes copiar los siguientes valores en la pestaña de configuración SMTP a tu script PHPMailer:

• Servidor: ( $ mail-> Host = ‘ mail.ayudawordpress.online’ ).
• Usuario: ( $ mail-> Username = ‘1a2b3c4d5e6f7g’ ).
• Contraseña: ( $ mail-> Password = ‘1a2b3c4d5e6f7g’ ).
• Puerto: ( $ mail-> Port = 465 ).

Hay otro punto que no se debe dejar de mencionar sobre SMTP: POP-before-SMTP para la autenticación. Este método se encarga de reemplazar casi por completo la autenticación SMTP. Una de sus principales ventajas, es la transparencia que ofrece al usuario que envió un correo electrónico.

Envió de correo electrónico HTML por medio de SMTP utilizando PHPMailer

Una de las cuestiones más probables es que estés utilizando HTML para diseñar la notificación por correo electrónico. Es por ello, que podemos realizar algunos ejemplos del uso de métodos y atributos HTML.

Mensaje HTML básico

Si has empleado Composer para llevar a cabo la instalación, debes incluir el archivo autoload.php el cual es generado por Composer.

require 'path/to/composer/vendor/autoload.php';

En el caso de que hayas instalado PHPMailer de forma manual, deberás iniciarlo llevando a cabo los siguientes pasos:

require path/to/PHPMailer/src/PHPMailer.php'; 
require path/to/PHPMailer/src/SMTP.php'; 
require path/to/PHPMailer/src/Exception.php';

Luego debes crear la clase PHPMailer:

<?php
use PHPMailer\PHPMailer\PHPMailer;

Ahora deberás continuar con el siguiente paso y crear un nuevo objeto PHPMailer:

$mail = new PHPMailer();

Pasemos ahora a la configuración SMTP:

$mail->isSMTP();
$mail->Host = 'smtp.mailtrap.io';
$mail->SMTPAuth = true;
$mail->Username = '1a2b3c4d5e6f7g'; //paste one generated by Mailtrap
$mail->Password = '1a2b3c4d5e6f7g’ //paste one generated by Mailtrap
$mail->SMTPSecure = 'tls';
$mail->Port = 2525;

Tendrás que especificar los encabezados de PHPMailer:

$mail->setFrom('info@mailtrap.io', 'Mailtrap');
$mail->addReplyTo('info@mailtrap.io', 'Mailtrap');
$mail->addAddress('recipient1@mailtrap.io', 'Tim'); 
$mail->addCC('cc1@example.com', 'Elena');
$mail->addBCC('bcc1@example.com', 'Alex');

Para distintas direcciones, debes especificar cada una de ellas empleando un nuevo comando:

$mail->AddBCC('bcc2@example.com', 'Anna');
$mail->AddBCC('bcc3@example.com', 'Mark');

Con PHPMailer, cuenta con la posibilidad de repetir el mensaje y enviarlo a distintos destinatarios. Revisaremos los ejemplos más adelante en esta publicación, por el momento nos enfocaremos en el mensaje básico.

Debes establecer un tema:

$mail->Subject = 'Test Email via Mailtrap SMTP using PHPMailer';

Luego, tenemos que establecer el formato de correo electrónico en HTML utilizando la propiedad isHTML.

$mail->isHTML(true);

Ahora tienes que ingresar el contenido que deseas:

$mailContent = "<h1>Send HTML Email using SMTP in PHP</h1>
    <p>This is a test email I’m sending using SMTP mail server with PHPMailer.</p>";
$mail->Body = $mailContent;

Al utilizar PHPMailer, puedes crear un correo electrónico HTML, con formato personalizado, imágenes y enviar los correos electrónicos con los archivos adjuntos. También cuenta con una opción para leer el cuerpo del mensaje HTML de un archivo externo, convertir las imágenes referenciadas en incrustadas, así como hacer la conversión HTML en un cuerpo alternativo básico de texto plano. Así estarás haciendo que no se sobrecargue el código de envío de mensaje con HTML y podrás llevar a cabo la actualización de la plantilla HTML de manera independiente. Si quieres agregar un archivo HTML por separado, deberás agregar los siguientes atributos:

$mail->msgHTML(file_get_contents('contents.html'), __DIR__);

Al final, se debe especificar los atributos de envío de correo electrónico:

if($mail->send()){
    echo 'Message has been sent';
}else{
    echo 'Message could not be sent.';
    echo 'Mailer Error: ' . $mail->ErrorInfo;
}

El resultado “mensaje enviado” estará informando que el código se ha ejecutado de forma correcta.

Correo electrónico HTML con archivos adjuntos

Cuentas con dos opciones para colocar archivos en tu mensaje:

• Adjuntar un archivo del sistema de archivos, como puedes hacerlo desde el cliente de correo electrónico. En este caso, los archivos deberán guardarse en el mismo directorio que el script. Además, podrás insertar un archivo en el mensaje.
• Puedes agregar un archivo adjunto de cadena: para este caso, los datos almacenados en una variable se adjuntan directamente en el mensaje. Se pueden extraer de una base de datos, por lo que no es necesario guardarlos como un archivo.

Para adjuntar un archivo, sólo requiere especificar su ruta. Además, puedes agregar el nombre del archivo pero esto es opcional: el script debe utilizar el nombre real del archivo.

$mail->addAttachment('path/to/invoice1.pdf', 'invoice1.pdf');

Si deseas agregar otro archivo, tienes que repetir el comando:

$mail->addAttachment('path/to/calculation1.xlsx', 'calculation1.xlsx');

Para colocar un archivo adjunto de la cadena, debes utilizar el comando addStringAttachment () . Deberás pasar el contenido y el nombre del archivo.

$mysql_data = $mysql_row['blob_data'];
$mail->addStringAttachment($mysql_data, 'db_data.db');

Este sería un ejemplo para agregar datos almacenados como BLOB en la base de datos MySQL.

De forma alternativa, también puedes utilizar una URL remota como la que mostramos a continuación:

$mail->addStringAttachment(file_get_contents($url), 'myfile.pdf');

Para colocar una imagen, tendremos que utilizar un código CID aquí:

$mail->addEmbeddedImage('path/to/image_file.jpg', 'image_cid');
$mail->isHTML(true);
$mail->Body = '<img src="cid:image_cid">';

Para finalizar, tendremos que revisar un ejemplo del mensaje completo junto con la imagen y el cuerpo HTML.

<?php

use PHPMailer\PHPMailer\PHPMailer;
require 'path/to/composer/vendor/autoload.php';
$mail->isSMTP();
$mail->Host = 'smtp.mailtrap.io';
$mail->SMTPAuth = true;
$mail->Username = 'paste one generated by Mailtrap';
$mail->Password = 'paste one generated by Mailtrap’
$mail->SMTPSecure = 'tls';
$mail->Port = 2525;

$mail->setFrom('from@example.com', 'First Last');
$mail->addReplyTo('towho@example.com', 'John Doe';

$mail->isHTML(true);

$mail->Subject = "PHPMailer SMTP test";
$mail->addEmbeddedImage('path/to/image_file.jpg', 'image_cid');
$mail->Body = '<img src="cid:image_cid"> Mail body in HTML';
$mail->AltBody = 'This is the plain text version of the email content';

if(!$mail->send()){
    echo 'Message could not be sent.';
    echo 'Mailer Error: ' . $mail->ErrorInfo;
}else{
    echo 'Message has been sent';

El resultado “mensaje enviado” te estará informando que el código se ejecuta de forma correcta.

Cuando verifiques que el resultado del envío de PHPMailer coincide con las expectativas, podrás cambiar el envío de correo electrónico regular por medio de cualquier servidor SMTP que prefieras.

Enviar correos electrónicos a distintos destinatarios

En el caso de que queramos enviar un mensaje modificado a una lista de diferentes destinatarios, que en la mayor parte de los casos se requiere para correos electrónicos de empresas. No debes preocuparte por ello, ya que al emplear PHPMailer cuentas con estas opciones.

<?php
use PHPMailer\PHPMailer\PHPMailer;
require 'path/to/composer/vendor/autoload.php';
$mail = new PHPMailer;
$body = file_get_contents('contents.html');
$mail->isSMTP();
$mail->Host = 'smtp.mailtrap.io';
$mail->SMTPAuth = true;
$mail->Username = '1a2b3c4d5e6f7g'; //generated by Mailtrap
$mail->Password = '1a2b3c4d5e6f7g'; //generated by Mailtrap
$mail->SMTPSecure = 'tls';
$mail->Port = 2525; 
$mail->SMTPKeepAlive = true; // add it to keep SMTP connection open after each email sent

$mail->setFrom('list@example.com', 'List manager');
$mail->Subject = "New Mailtrap mailing list";

$users = [
  ['email' => 'max@example.com', 'name' => 'Max'],
  ['email' => 'box@example.com', 'name' => 'Bob']
];

foreach ($users as $user) {
  $mail->addAddress($user['email'], $user['name']);

  $mail->Body = "<h2>Hello, {$user['name']}!</h2> <p>How are you?</p>";
  $mail->AltBody = "Hello, {$user['name']}! \n How are you?";

  try {
      $mail->send();
      echo "Message sent to: ({$user['email']}) {$mail->ErrorInfo}\n";
  } catch (Exception $e) {
      echo "Mailer Error ({$user['email']}) {$mail->ErrorInfo}\n";
  }

  $mail->clearAddresses();
}

$mail->smtpClose();

Cómo utilizar PHPMailer en Gmail

Gmail es uno de los servidores SMTP más populares del momento, el cual te permite enviar correos electrónicos de forma gratuita. Por otra parte, requiere de algunos ajustes en la configuración para su autenticación.

Cifrado

A continuación, te mostramos las credenciales básicas de Gmail para SMTP:

$mail->SMTPSecure = 'tls';
$mail->Host = 'smtp.gmail.com';
$mail->Port = 587;

o

$mail->SMTPSecure = 'ssl';
$mail->Host = 'smtp.gmail.com';
$mail->Port = 465;

Si no utilizas la verificación de los pasos para tu cuenta, tendrás que utilizar la dirección de correo electrónico que empleas para Gmail y la contraseña.

Debes permitir aplicaciones menos seguras en la configuración de tu cuenta. Es importante tomar en cuenta que se debe emplear de una a dos horas para que la configuración se haga por completo. Incluso, en algunos casos existe la posibilidad de que debas realizar los cambios necesarios en la página de bloqueo de CAPTCHA.

En el caso de que algo salga mal y aparezca un error “5.7.14 inicie sesión a través de su navegador web y luego vuelva a intentarlo” o “nombre de usuario y contraseña no aceptado”. Debes seguir las instrucciones donde se indica cómo solucionarlo.

Verificación de dos pasos

En el caso de que la verificación de dos pasos se encuentre habilitada en tu cuenta de Gmail, deberás emplearla también con PHPMailer. Tienes que crear una contraseña para la aplicación y así continuar. Este consta de un código de acceso de 16 dígitos y se debe colocar como valor a $ mail-> Password. Esto es muy sencillo de configurar si seguimos las instrucciones de Google.

OAuth2

OAuth2 es uno de los métodos más complicados pero sigue siendo el más recomendado. Por fortuna, existe oauth2-google. Este consta de un paquete compatible con Google OAuth 2.0 para el cliente OAuth 2.0. Este es compatible con PHP 7.0 y PHP 7.3. Para utilizarlo, primero se debe obtener un ID de cliente de Google y el cliente secreto. Es importante seguir esta guía de Google donde se te indica cómo configurar todo. Una vez termines, deberás instalar el paquete Composer y colocar los detalles de autorización de la siguiente forma:

composer require league/oauth2-google

use League\OAuth2\Client\Provider\Google;
$provider = new Google([
    'clientId'     => '{google-client-id}',
    'clientSecret' => '{google-client-secret}',
    'redirectUri'  => 'https://example.com/callback-url',
]);

Enviar un correo electrónico utilizando PHPMailer sin servidor SMTP

La opción sin servidor SMTP es una de las más populares y que se puede utilizar con PHPMailer. Por otra parte, como hemos mencionado anteriormente, también es compatible con otra forma de hacerlo.

En el caso de localhost, podrás emplear el programa Sendmail:

// Set mailer with this method 
$mailer->isSendmail();
// And send mail as usual
$mailer->send();

En el caso de que prefieras Unix, debes implementar Qmail:

// Set mailer with this method 
$mailer->isQmail();
// And send mail as usual
$mailer->send();

Depuración

En el caso de que llegues a experimentar algún problema al enviar un correo electrónico por medio de un servidor SMTP, el comando SMTPDebug te estará ayudando a explorar cualquier tipo de error y descubrir cómo se debe corregir.

Debes habilitar la depuración SMTP y establecer el nivel de depuración en el script de la forma siguiente:

$mail->SMTPDebug = 2;

Nivel 1: cliente; estará mostrando los mensajes enviados por el cliente.

Nivel 2: cliente y servidor; estará agregando los mensajes del servidor. Por defecto, está es la configuración recomendada.

Nivel 3: cliente, servidor y conexión; se encargará de agregar datos sobre la información inicial y podría ser útil para descubrir fallas STARTTLS.

Nivel 4: información de bajo nivel.

Utiliza el nivel 3 o 4 en el caso de que no puedas conectarte. Si se establece el nivel 0, se estará desactivando la depuración.

Para entender de mejor forma cómo funciona la depuración en PHPMailer, podemos ver el siguiente ejemplo:

Ejemplo 1. 

Nombre de host SMTP no válido

2018-12-12 14:51:32	Connection: opening to mailtrap.io:2525, timeout=10, options=array()
2018-12-12 14:51:42	Connection failed. Error #2: stream_socket_client(): unable to connect to mailtrap.io:2525 (Operation timed out) [/Users/xxxx/Downloads/PHPMailer/src/SMTP.php line 326]
2018-12-12 14:51:42	SMTP ERROR: Failed to connect to server: Operation timed out (60)
2018-12-12 14:51:42	SMTP connect() failed. 
Mailer Error: SMTP connect() failed.

Para este ejemplo, tenemos que ingresar el nombre de host no válido: mailtrap.io y no smtp.mailtrap.io y de forma instantánea estarás recibiendo un mensaje donde se te indica que se ha producido un error en la primera etapa de comunicación con el servidor.

Ejemplo 2.

Credenciales inválidas 

2018-12-12 14:49:26	Connection: opening to smtp.mailtrap.io:2525, timeout=300, options=array()
2018-12-12 14:49:26	Connection: opened
2018-12-12 14:49:26	SMTP INBOUND: "220 mailtrap.io ESMTP ready"
2018-12-12 14:49:26	SERVER -> CLIENT: 220 mailtrap.io ESMTP ready
...
2018-12-12 14:49:30	SMTP INBOUND: "535 5.7.0 Invalid login or password"
2018-12-12 14:49:30	SERVER -> CLIENT: 535 5.7.0 Invalid login or password
2018-12-12 14:49:30	SMTP ERROR: Username command failed: 535 5.7.0 Invalid login or password
2018-12-12 14:49:30	SMTP Error: Could not authenticate.
2018-12-12 14:49:30	CLIENT -> SERVER: QUIT
2018-12-12 14:49:30	SMTP INBOUND: "221 2.0.0 Bye"
2018-12-12 14:49:30	SERVER -> CLIENT: 221 2.0.0 Bye
2018-12-12 14:49:30	Connection: closed
2018-12-12 14:49:30	SMTP connect() failed. 
Mailer Error: SMTP connect() failed.

Por medio de este ejemplo se demuestra donde se produce el error: ahora el SMTP, el nombre de host y el puerto correspondiente son válidos, pero no se ha encontrado la combinación correspondiente al inicio de sesión y contraseña. Por esa razón, se deben verificar y modificar las credenciales.

¿Qué más debes conocer sobre PHPMailer?

Por medio de esta guía hemos realizado algunos de los casos de uso de PHPMailer que más se utilizan: creación de correo electrónico HTML junto con imágenes y archivos adjuntos, enviar correos por medio de SMTP o localhost a distintos destinatarios empleando opciones de depuración.

También puedes echarle un vistazo a nuestra guía donde mostramos cómo activar la vista de errores de PHP en WordPress.