El objeto de este escrito es presentar al lector la clase PHPMailer con la que podrá realizar todas aquellas cosas que nunca ha podido realizar con la funcion mail() de PHP.
En primer lugar se tratará de explicar qué es y las ventajas que ofrece PHPMailer, a continuación se describirán las propiedades y métodos principales de esta clase. Para aclarar las posibles dudas se expondrán dos ejemplos en los que se verá como enviar correo a través de una cuenta gratuita creada en hotpop.
¿Qué es phpmailer?
PHPMailer es una clase php para enviar emails basada en el componente active server ASPMail. Permite de una forma sencilla tareas complejas como por ejemplo:
- Enviar mensajes de correo con ficheros adjuntos (attachments)
- enviar mensajes de correo en formato HTML
Con PHPMailer se pueden enviar emails via sendmail, PHP mail(), o con SMTP. Lo más recomendable es usando smtp por dos razones:
- Con phpmailer se pueden usar varios servidores SMTP. Esto permite repartir la carga entre varias computadoras, con lo que se podrán enviar un mayor número de mensajes en un tiempo menor.
- Además los servidores SMTP permiten mensajes con múltimples to's (destinatarios), cc's (Las direcciones que aparezcan en este campo recibirán el mensaje. Todos los destinatarios verán las direcciones que aparecen en la sección Cc), bcc's (Las direcciones que aparezcan en el campo Bcc recibirán el mensaje. Sin embargo, ninguno de los destinatarios podrá ver las direcciones que fueron incluidas en la sección Bcc) y Reply-tos (direcciones de respuesta)
¿Por qué usar phpmailer?
Es posible enviar email con la funcion mail() de php, pero dicha función no permite algunas de las más populares características que proporcionan los clientes de correo usados actualmente. Entre estas características se encuentran el envío de email con ficheros adjuntos.
PHPMailer hace fácil esta difícil tarea de enviar correos con estas características y puedes incluso utilizar tu propio servidor smtp aunque éste requiera autenticación (un nombre de usuario y contraseña), con lo que se podrá usar una cuenta gratuita de correo obtenida por ejemplo en hotpop.
Pasos a seguir para usar phpmailer
- Necesitamos el fichero
class.phpmailer.php que es la clase PHPMailer
propiamente dicha y también el fichero class.smtp.php que nos permite el envío de
emails a través de un servidor smtp.
- El siguiente trozo de código es necesario para instanciar desde nuestra página php a la clase PHPMAiler. En la primera línea incluimos el fichero
class.phpmailer.php y en la segunda creamos un objeto de la clase PHPMailer:
require("class.phpmailer.php"); $mail = new PHPMailer(); - Una vez instanciado el objeto de la clase PHPMailer es necesario configuar sus propiedades y llamar a sus métodos. A continuación enumero propiedades y métodos principales de la clase PHPMailer.
Propiedades:
| Nombre | Descripción | Valor por defecto |
|---|---|---|
| AltBody | Establece el cuerpo del mensaje como sólo de texto | "" |
| Body | Establece el cuerpo del mensaje.Puede ser texto simple o con formato HTMl. Si es con formato HTMl hay que ejecutar el método IsHTML(True) | "" |
| ConfirmReadingTo | Establece la dirección de correo a la que se enviará una Confirmación de que el correo ha sido leido | "" |
| ErrorInfo | Informa del error más reciente producido al intentar enviar un email | "" |
| From | Establece la dirección de correo de origen del Mensaje | root@localhost |
| FromName | Establece el nombre de quien envía el mensaje | Root User |
| Host | Establece el servidor SMTP. Pueden ser varios separados por ; | Localhost |
| Mailer | Establece el método para enviar el mensaje puede ser mail, senmail o smtp. Se recomienda usar smtp siempre que sea posible | |
| Password | Establece la contraseña del servidor SMTP | "" |
| PluginDir | Establece el directorio donde están incluidos los plugins de phpmailer. Muy útil para indicar el directorio en el que se encuentra la clase SMTP | "" |
| Port | Establece el puerto por defecto del servidor SMTP | 25 |
| ReplyTo | Establece todas las direcciones Reply-To | Array() |
| SMTPAuth | Establece la autentificación SMTP | False |
| Subject | Establece el asunto del mensaje | "" |
| Timeout | Establece el timeout del servidor STMP en segundos | 10 |
| Username | Establece el nombre de usuario SMTP | "" |
| WordWrap | Establece el word Wrapping del cuerpo de un mensaje a un número determinado de caracteres | 0 |
Métodos:
| Nombre | Sintaxis | Descripción |
|---|---|---|
| AddAddress | void AddAddress ( $address, $name ) | Añade una dirección de destino del mensaje. El parámetro $name es opcional |
| AddAttachment | bool AddAttachment ( $path, $name, [$encoding = "base64"], [$type = "application/octet-stream"] ) | Añade un fichero adjunto al mensaje. Retorna false si el fichero no pudo ser encontrado. $path, es la ruta del archivo puede ser relativa al script php (no a la clase PHPMailer) o una ruta absoluta. Se aconseja usar rutas relativas $name, nombre del fichero $encoding, tipo de codificación. Se aconseja dejar la predeterminada $type, el valor por defecto funciona con cualquier clase de archivo. Se puede usar un tipo específico como por ejemplo image/jpeg |
| AddBBC | void AddBCC ( $address, $name ) | Añade una dirección BCC. |
| AddCC | void AddCC ( $address, $name ) | Añade una dirección CC |
| AddReplyTo | void AddReplyTo ( $address, $name ) | Añade una dirección Reply-To |
| ClearAddresses | void ClearAddresses () | Borra todas las direcciones de destino establecidas anteriormente |
| ClearAttachments | void ClearAttachments () | Borra todos los ficheros adjuntos establecidos anteriormente |
| IsHTML | void IsHTML ( $bool ) | Establece el tipo de mensaje a HTML |
| Send | bool Send ( ) | Envía el mensaje, devuelve false si ha habido algún problema. Consultando la propiedad ErrorInfo se puede saber cuál ha sido el problema |
Ejemplo sencillo
Esta primera aplicación de ejemplo aplicacion1.zip va a estar formada por:
- Una página principal llamada ejemplo.php
- Un subdirectorio llamado includes donde estarán los ficheros class.phpmailer.php y class.smtp.php
El objetivo de la aplicación es mandar un mensaje de prueba mediante una cuenta de correo gratuita de hotpop. Así pues, el primer paso será crear una cuenta en hotpop, como nombre de usuario y password para dicha cuenta pondré por ejemplo micuenta y mipassword respectivamente, al acabar de crear la cuenta nos dará la bienvenida y nos dirá que el servidor SMTP es smtp.hotpop.com. Por tanto, para enviar emails mediante phpmailer tendremos una cuenta gratuita en http://www.hotpop.com con estas características:
- SMTP Server: smtp.hotpop.com
- Usuario: [email protected]
- Clave: mipassword
La direccion de destino a la que enviaré el mensaje será por ejemplo [email protected]
Código de ejemplo.php:
<? // primero hay que incluir la clase phpmailer para poder instanciar //un objeto de la misma require "includes/class.phpmailer.php"; //instanciamos un objeto de la clase phpmailer al que llamamos //por ejemplo mail $mail = new phpmailer(); //Definimos las propiedades y llamamos a los métodos //correspondientes del objeto mail //Con PluginDir le indicamos a la clase phpmailer donde se //encuentra la clase smtp que como he comentado al principio de //este ejemplo va a estar en el subdirectorio includes $mail->PluginDir = "includes/"; //Con la propiedad Mailer le indicamos que vamos a usar un //servidor smtp $mail->Mailer = "smtp"; //Asignamos a Host el nombre de nuestro servidor smtp $mail->Host = "smtp.hotpop.com"; //Le indicamos que el servidor smtp requiere autenticación $mail->SMTPAuth = true; //Le decimos cual es nuestro nombre de usuario y password $mail->Username = "[email protected]"; $mail->Password = "mipassword"; //Indicamos cual es nuestra dirección de correo y el nombre que //queremos que vea el usuario que lee nuestro correo $mail->From = "[email protected]"; $mail->FromName = "Eduardo Garcia"; //el valor por defecto 10 de Timeout es un poco escaso dado que voy a usar //una cuenta gratuita, por tanto lo pongo a 30 $mail->Timeout=30; //Indicamos cual es la dirección de destino del correo $mail->AddAddress("[email protected]"); //Asignamos asunto y cuerpo del mensaje //El cuerpo del mensaje lo ponemos en formato html, haciendo //que se vea en negrita $mail->Subject = "Prueba de phpmailer"; $mail->Body = "<b>Mensaje de prueba mandado con phpmailer en formato html</b>"; //Definimos AltBody por si el destinatario del correo no admite email con formato html $mail->AltBody = "Mensaje de prueba mandado con phpmailer en formato solo texto"; //se envia el mensaje, si no ha habido problemas //la variable $exito tendra el valor true $exito = $mail->Send(); //Si el mensaje no ha podido ser enviado se realizaran 4 intentos mas como mucho //para intentar enviar el mensaje, cada intento se hara 5 segundos despues //del anterior, para ello se usa la funcion sleep $intentos=1; while ((!$exito) && ($intentos < 5)) { sleep(5); //echo $mail->ErrorInfo; $exito = $mail->Send(); $intentos=$intentos+1; } if(!$exito) { echo "Problemas enviando correo electrónico a ".$valor; echo "<br/>".$mail->ErrorInfo; } else { echo "Mensaje enviado correctamente"; } ?>
| Comentarios al ejemplo |
|---|
|
Tres cosas a destacar: Al usar un servidor smtp para el envío del mensaje es muy importante definir la propiedad PluginDir que indica donde se encuentra el fichero class.smtp.php que contiene la clase SMTP, en este caso se encuentra en el subdirectorio includes El uso simultáneo de las propiedades Body y AltBody. Se debe hacer cuando queremos mandar un mensaje con formato Html ya que es posible que el destinatario acepte sólo correos en formato texto. Al definir las dos propiedades, Body y AltBody, no es necesario ejecutar el método IsHTML(True) cuando a Body se le asigna un mensaje en formato Html La tercera y más importante a tener en cuenta es el hecho de que el éxito en el envio del mail no depende sólo de la clase PHPMailer sino que es vital el tiempo que el servidor smtp necesita para autenticar al usuario así como el tiempo que tarda dicho servidor en enviar un correo. Por tanto es fundamental proporcionarle al servidor el tiempo que le hace falta, ello se cosigue de dos formas: Por un lado aumentando el valor de la propiedad Timeout pasando por ejemplo de 10 a 30 segundos; Y por otro lado reintentando el envío del mensaje un número razonable de veces (por ejemplo 5), dejando un tiempo de espera (por ejemplo 5 segundos), entre cada intento. Mediante la combinación de estos 3 factores: Propiedad Tiemout, numero de intentos para enviar el mensaje y tiempo de espera entre cada intento evitaremos los dos mensajes de error más frecuentes que nos puede dar la clase PHPMailer, relacionados con el tiempo que necesita el servidor smtp para realizar su función, y que son:
|
Ejemplo algo más complicado
El objetivo de esta segunda aplicación de ejemplo aplicacion2.zip va a ser enviar un correo con
un fichero adjunto a 2 direcciones de destino diferentes (al menos debe haber una direccion de destino, el envio de un fichero
adjunto será opcional. Por simplificar no compruebo que la sintaxis de
las direcciones de correo introducidas en los campos de texto sea correcta).
Esta aplicación va a estar formada por:
- Una página principal llamada ejemplo2.php
- Un subdirectorio llamado includes donde estarán los ficheros class.phpmailer.php y class.smtp.php
En la página principal ejemplo2.php vamos a tener un formulario como el que se ve a continuación
Para poder enviar el fichero adjunto vamos a emplear en el formulario una etiqueta INPUT de tipo FILE que es soportada por Netscape Navigator 2.0 en adelante e Internet Explorer 4.0 en adelante. Para que funcione es necesario:
- Que el formulario use el método post
- Que el atributo enctype tenga el valor multipart/form-data
- Además al formulario hay que añadirle un campo oculto de nombre MAX_FILE_SIZE, al cuál le daremos el valor en bytes del tamaño máximo del archivo a descargar. Dado que voy a emplear la cuenta gratuita de hotpop empleada en el ejemplo anterior y dicha cuenta no permite enviar mensajes de más de 500kb voy a limitar a 300kb (307200 bytes) el tamaño máximo del archivo.
Código de ejemplo2.php:
<?
//Es necesario que al menos halla una dirección de destino
$error="";
if ($enviar) {
if ((!$email1) && (!$email2)) {
$error.="Debe indicar al menos una dirección de destino";
}
}
if ($enviar && !$error) {
//creamos un array que estará formado por las direcciones de destino
if ($email1) {
$direcciones["direccion1"]=$email1;
}
if ($email2) {
$direcciones["direccion2"]=$email2;
}
//pasamos a enviar el correo
// primero hay que incluir la clase phpmailer para poder instanciar
//un objeto de la misma
require "includes/class.phpmailer.php";
//instanciamos un objeto de la clase phpmailer al que llamamos
//por ejemplo mail
$mail = new phpmailer();
//Definimos las propiedades y llamamos a los métodos
//correspondientes del objeto mail
//Con PluginDir le indicamos a la clase phpmailer donde se
//encuentra la clase smtp que como he comentado al principio de
//este ejemplo va a estar en el subdirectorio includes
$mail->PluginDir = "includes/";
//Con la propiedad Mailer le indicamos que vamos a usar un
//servidor smtp
$mail->Mailer = "smtp";
//Asignamos a Host el nombre de nuestro servidor smtp
$mail->Host = "smtp.hotpop.com";
//Le indicamos que el servidor smtp requiere autenticación
$mail->SMTPAuth = true;
//Le decimos cual es nuestro nombre de usuario y password
$mail->Username = "[email protected]";
$mail->Password = "mipassword";
//Indicamos cual es nuestra dirección de correo y el nombre que
//queremos que vea el usuario que lee nuestro correo
$mail->From = "[email protected]";
$mail->FromName = "Eduardo Garcia";
//Asignamos asunto y cuerpo del mensaje
//El cuerpo del mensaje lo ponemos en formato html, haciendo
//que se vea en negrita
$mail->Subject = "Prueba de phpmailer";
$mail->Body = "<b>Mensaje de prueba mandado con phpmailer en formato html</b>";
//Definimos AltBody por si el destinatario del correo no admite
//email con formato html
$mail->AltBody ="Mensaje de prueba mandado con phpmailer en formato texto";
//el valor por defecto 10 de Timeout es un poco escaso dado que voy a usar
//una cuenta gratuita y voy a usar attachments, por tanto lo pongo a 120
$mail->Timeout=120;
//Indicamos el fichero a adjuntar si el usuario seleccionó uno en el formulario
if ($achivo !="none") {
$mail->AddAttachment($archivo,$archivo_name);
}
//Indicamos cuales son las direcciones de destino del correo y enviamos
//los mensajes
reset($direcciones);
while (list($clave, $valor)=each($direcciones)) {
$mail->AddAddress($valor);
//se envia el mensaje, si no ha habido problemas la variable $success
//tendra el valor true
$exito = $mail->Send();
//Si el mensaje no ha podido ser enviado se realizaran 4 intentos mas
//como mucho para intentar enviar el mensaje, cada intento se hara 5 s
//segundos despues del anterior, para ello se usa la funcion sleep
$intentos=1;
while((!$exito)&&($intentos<5)&&($mail->ErrorInfo!="SMTP Error: Data not accepted")){
sleep(5);
//echo $mail->ErrorInfo;
$exito = $mail->Send();
$intentos=$intentos+1;
}
//La clase phpmailer tiene un pequeño bug y es que cuando envia un mail con
//attachment la variable ErrorInfo adquiere el valor Data not accepted, dicho
//valor no debe confundirnos ya que el mensaje ha sido enviado correctamente
if ($mail->ErrorInfo=="SMTP Error: Data not accepted") {
$exito=true;
}
if(!$exito)
{
echo "Problemas enviando correo electrónico a ".$valor;
echo "<br/>".$mail->ErrorInfo;
}
else
{
//Mostramos un mensaje indicando las direccion de
//destino y fichero adjunto enviado en el mensaje
$mensaje="<p>Has enviado un mensaje a:<br/>";
$mensaje.=$valor." ";
if ($archivo !="none") {
$mensaje.="Con un fichero adjunto llamado ".$archivo_name;
}
$mensaje.="</p>";
echo $mensaje;
}
// Borro las direcciones de destino establecidas anteriormente
$mail->ClearAddresses();
}
echo "<a href='$PHP_SELF'> VOLVER AL FORMULARIO</a>";
}
else {
?>
<HTML>
<BODY>
<? If ($error) echo "<font color='red'>$error</font>";?>
<FORM ENCTYPE="multipart/form-data" METHOD="post" ACTION="<?=$PHP_SELF?>">
<TABLE BORDER=0 ALIGN="CENTER">
<TR>
<TD>Direccion de destino1:</TD>
<TD><INPUT TYPE="text" NAME="email1" MAXLENGTH="30" SIZE="35"></TD>
</TR>
<TD>Direccion de destino2:</TD>
<TD><INPUT TYPE="text" NAME="email2" MAXLENGTH="35" SIZE="35"></TD>
</TR>
<TD>Fichero adjunto:</TD>
<input type="hidden" name="MAX_FILE_SIZE" value="307200">
<TD><INPUT TYPE="file" NAME="archivo" SIZE="35"></TD>
</TR>
<TR>
<TD COLSPAN="2" ALIGN="CENTER"><INPUT TYPE="submit" VALUE="Enviar" name="enviar"></TD>
</TR>
</TABLE>
</FORM>
</BODY>
</HTML>
<?
}
?>
| Comentarios al ejemplo 2 |
|---|
|
En el caso de que halla dos direcciones de destino, en lugar de añadir las dos direcciones a la vez mediante llamadas consecutivas al método AddAddresses lo que hago es enviar uno a uno cada correo:
La ventaja de hacerlo uno a uno y no los dos a la vez es que tengo un mayor control sobre los posibles errores que puedan suceder, identificando en cada momento a qué direccion se le ha podido enviar el mail y a cuál no Aumento el Timeout a 120 ya que enviar un fichero adjunto requiere más tiempo que enviar un mensaje corto Quizá lo que llame más la atención es el trato que he dado al error SMTP Error: Data not accepted. Dicho error aparece siempre que enviamos un fichero adjunto pero no debe incomodarnos ya que el mensaje llega perfectamente, se trata de un bug de la clase PHPMailer y como tal hay que tratarlo, es decir, si aparece ese error no lo tendremos en cuenta. |
Conclusiones y enlaces
Como se ha podido observar en los dos ejemplos anteriores con PHPMailer es posible el envío de un email tan complejo o tan simple como se quiera. Hemos visto los 3 errores más frecuentes que se pueden dar al usar la clase phpmailer:
- SMTP Error: The following recipientes failed ......
- SMTP Error: Could not authenticate
- SMTP Error: Data not accepted
La solucion a los 2 primeros es la que ya apunté en Comentarios al ejemplo, y se trata de buscar la mejor combinación de los factores Timeout, numero de intentos para enviar el mensaje e intervalo de tiempo entre cada intento. Los valores que he utilizado son orientativos no deben tomarse al pie de la letra ya que para realizar los ejemplos me parecía adecuado usar una cuenta gratuita obtenida en la Web, pero el lector seguramente usará una cuenta que le halla proporcionado su proveedor de Internet y dicha cuenta puede requerir unos valores para esos factores que coincidan o no con los que yo he propuesto, también dependerá del uso que quiera dar a la cuenta, no es lo mismo si la va a usar para enviar correos con formato sólo texto a pocos destinatarios que si quiere enviar correos con ficheros adjuntos a muchos destinatarios.
La solución al tercero es la ya apuntada en Comentarios al ejemplo 2, es decir, ignorar dicho error porque el mensaje llega correctamente.
He comentado los aspectos más importantes de la clase PHPMailer, para una mayor información sugiero consultar la web de los creadores de esta estupenda clase.