Uso de la clase PHPMailer

1 . Introducción
2 . ¿Qué es phpmailer?
3 . ¿Por qué usar phpmailer?
4 . Pasos a seguir para usar phpmailer
5 . Ejemplo sencillo
6 . Ejemplo algo más complicado
7 . Conclusiones y enlaces

Introducción

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	Mail
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: micuenta@HotPOP.com
• Clave: mipassword

La direccion de destino a la que enviaré el mensaje será por ejemplo direccion@destino.com

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 = "micuenta@HotPOP.com"; 
  $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 = "micuenta@HotPOP.com";
  $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("direccion@destino.com");

  //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";
   } 
?>

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 = "micuentaf@HotPOP.com";
      $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 = "micuenta@HotPOP.com";

      $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>
   <?
   }
?>

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.