Nomad MIME Mail 1.6 - Documentación.

Copyright (C) 2003 - 2007 Alejandro García González.
Web: http://www.developarts.com
Correo: nexus at developarts dot com

Tabla de Contenidos.

1. Descripción.
2. Referencia Rápida.
3. Referencia de las Funciones.
4. Cambios en Versiones.
5. Por hacer.
6. Colaboradores.
7. Licencia.

1. Descripción.

Nomad MIME Mail (antes conocido como Nexus MIME Mail), es una clase para el manejo y envío de correos tipo MIME, con soporte para el envío por SMTP y Auth SMTP

Actualmente este clase soporta:

Texto Plano
HTML
Texto Plano con Adjuntos
HTML con Adjuntos
HTML con Imágenes Embebidas
HTML con Adjuntos e Imágenes Embebidas

También soporta múltiples direcciones de correo de envío (to), con copia (cc) y con copia oculta (bcc), así como varias imágenes embebidas en HTML y varios adjuntos

2. Referencia Rápida.

Adjunto a esta clase y documentación se encuentra un archivo llamado 'nomad_mimemail.test.php' donde se encuentra un script con un ejemplo de envío de correo con Texto, HTML, Adjunto e Imágen Embebida enviado por vía SMTP.

Para usar Nomad MIME Mail es necesario declarar el objeto de la siguiente forma:

include ('nomad_mimemail.inc.php');
$mimemail = new nomad_mimemail();

Texto Plano

Normalmente así es como funcionaría la función 'mail()' de PHP, sin embargo en esta versión se crea de forma un poco distinta ya que se envían las cabeceras y cuerpo del mensaje de tipo MIME

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Texto y HTML

Ejemplo de envío de correo con Texto y HTML

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + HTML");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- HTML");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML</BODY></HTML>");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Texto Plano + Adjuntos

Ejemplo para crear un correo con Texto plano y un adjunto. Se pueden agregar mas de un adjunto agregándolos con la función 'add_attachment'. Para más información, revisar la referencia de la función.

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + Attachment");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- Attachment");
$mimemail->add_attachment("test_attachment.tar.gz", "file.tar.gz");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Texto Plano + HTML + Adjuntos

Ejemplo para crear un correo con Texto Plano, HTML y un adjunto. Se pueden agregar mas de un adjunto usando la función 'add_attachment'.

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + HTML + Attachment");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- HTML\n- Attachment");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML- Attachment</BODY></HTML>");
$mimemail->add_attachment("test_attachment.tar.gz", "file.tar.gz");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Texto Plano + HTML + Imagen Embebida

Ejemplo para crear un correo con HTML, texto plano y una Imagen Embebida. Para que la imagen embebida funcione, el archivo adjunto debe tener el mismo nombre que se indique en el tag 'IMG' del HTML del mensaje.

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + HTML + Embedded Image");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- HTML\n- Embedded Image");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML- Embedded Image<img src='image.gif' border='0'></BODY></HTML>");
$mimemail->add_attachment("test_image.gif", "image.gif");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Texto Plano + HTML + Imagen Embebida + Adjunto

Ejemplo para crear un correo con HTML, texto plano, una Imagen Embebida y adjunto. Para que la imagen embebida funcione, el archivo_adjunto debe tener el mismo nombre que se indique en el tag 'IMG'

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + HTML + Embedded Image + Attachment");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- HTML\n- Embedded Image\n- Attachment");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML- Embedded Image- Attachment<img src='image.gif' border='0'></BODY></HTML>");
$mimemail->add_attachment("test_image", "image.gif");
$mimemail->add_attachment("test_attachment.tar.gz", "file.tar.gz");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Envío por SMTP Autentificado

Para envíar el correo vía SMTP es necesario llamar a la función 'set_smtp_host' y para enviar el correo usando la auteticación del SMTP es necesario usar la función 'set_smtp_auth'.

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: HTML + Auth SMTP");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML</BODY></HTML>");

$mimemail->set_smtp_host("domain.com");
$mimemail->set_smtp_auth("user", "pass");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Por el momento esta versión se encuentra en pruebas y agradeceré toda la ayuda posible para que esta clase soporte una gran cantidad de SMTP's. En caso de tener un error es posible revisar toda la conversación que hace este script con el SMTP. para ello antes del 'send' llamaremos a la función 'set_smtp_log' a true, y en el fallo podemos traer todo por medio de 'get_smtp_log' como a continuación se ejemplifica:

$mimemail->set_smtp_log(true);

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo $mimemail->get_smtp_log();
}

Si es el caso, le pido que deje su reporte en El Foro de esta clase en donde trataré de adaptar en lo posible las respuestas obtenidas del SMTP.

3. Referencia de las Funciones.

add_attachment	Agrega un archivo adjunto
add_bcc	Agrega un correo con copia al carbón oculto
add_cc	Agrega un correo con copia al carbón
add_content_attachment	Agrega un archivo adjunto enviando directamente el contenido
add_reply_to	Agrega un correo de respuesta
add_to	Agrega un correo destino
get_eml	Entrega el formato EML del correo
get_smtp_log	Entrega la Conversación con el SMTP
get_version	Entrega el numero de versión de esta clase
new_mail	Crea un correo nuevo
nomad_mimemail	Constructor
send	Envía el correo MIME
set_bcc	Establece un correo con copia al carbón oculto
set_charset	Establece el juego de caracteres usados en el correo
set_cc	Establece un correo con copia al carbón
set_from	Establece el correo del remitente
set_html	Establece el contenido del correo en HTML
set_reply_to	Establece el correo de respuesta
set_return_path	Establece el correo de retorno
set_smtp_auth	Establece el nombre de usuario y contraseña para el envío por Auth SMTP
set_smtp_host	Establece el host donde se enviará el correo por SMTP
set_smtp_log	Estblece si se captura el log de conversación entre esta clase y el SMTP
set_subject	Establece el asunto del correo
set_text	Establece el contenido del correo texto plano
set_to	Establece un correo destino

add_attachment

bool add_attachment(string file, string name, [string type])

Descripción

Agrega un archivo adjunto al correo electrónico

En el parámetro 'file' se debe de proporcionar la ubicación (ruta y nombre) del archivo que se quiere adjuntar. Este método abre el archivo con fopen.

Cuando se hace el envío de un archivo por medio de un método POST, PHP inicializa una variable superglobal con información que puede ser usada directamente con este método. Por ejemplo:

$_FILES['userfile']['name'] es el nombre original del archivo
$_FILES['userfile']['type'] es el tipo mime del archivo proporcionado por el navegador
$_FILES['userfile']['tmp_name'] es la ubicación del archivo temporal almacenado

En el particular caso de necesitar embeber una imagen dentro de un correo, es necesario crear el "Tag" correspondiente en el HTML del mensaje haciendo la correcta referencia entre el "name" del archivo gráfico y su vínculo "src". Para mayor información puede revisar los ejemplos que acompañan a esta clase.

Parámetros

file

Ubicación del archivo que se quiere adjuntar

name

Nombre con el que se enviará el archivo

type

Typo MIME del archivo que se quiere adjuntar

Ejemplos

$mimemail->add_attachment($_FILES['userfile']['tmp_name'], $_FILES['userfile']['name'], $_FILES['userfile']['type']);
$mimemail->add_attachment('img/image_test.gif', 'myimage.gif');

add_bcc

bool add_bcc(string mail_bcc, [string name])

Descripción

Agrega una dirección de correo como copia al carbón oculto a las ya existentes, la cual debe ser sintacticamente correcta devolviendo 'true' si se añade con éxito o 'false' en caso contrario. Opcionalmente se puede especificar un nombre de contacto.

Parámetros

mail_bcc

Correo electrónico del destinatario

name

Nombre o texto del contacto

Ejemplos

$mimemail->add_bcc('foo@mail.com', 'Mr. Foo');
$mimemail->add_bcc('bar@mail.com', 'Mr. Bar');

add_cc

bool add_cc(string mail_cc, [string name])

Descripción

Agrega una dirección de correo como copia al carbón a las ya existentes, la cual debe ser sintácticamente correcta devolviendo 'true' si se añade con éxito o 'false' en caso contrario. Opcionalmente se puede especificar un nombre de contacto.

Parámetros

mail_cc

Correo electrónico del destinatario

name

Nombre o texto del contacto

Ejemplos

$mimemail->add_cc('foo@mail.com', 'Mr. Foo');
$mimemail->add_cc('bar@mail.com', 'Mr. Bar');

add_content_attachment

bool add_content_attachment(string content, string name, [string type])

Descripción

Agrega un archivo adjunto al correo electrónico pasando directamente el contenido. Esta función es especialmente útil cuando se generan contenidos directamente en código, como podría ser archivos xml, pdf, imagenes, etc. que se quiera adjuntar.

En el parámetro 'content' se debe pasar el contenido directo. A diferencia de 'add_attachment' en este método no se abrirá ningun archivo externo, ya que el contenido se pasa directamente.

Parámetros

content

Contenido a adjuntar como archivo

name

Nombre con el que se enviará el archivo

type

Typo MIME del archivo que se quiere adjuntar

Ejemplos

$mimemail->add_content_attachment("This is the content of text file", "textfile.txt");

add_reply_to

bool add_reply_to(string mail_reply_to, [string name])

Descripción

Agrega una dirección de correo electrónico al cual se responderá cuando el usuario pulse sobre su opcion de responder (reply) de su cliente de correo electronico.

Parámetros

mail_reply_to

Correo electrónico de Respuesta

name

Nombre o texto del contacto

Ejemplos

$mimemail->add_reply_to('foo@mail.com', 'Mr. Foo');
$mimemail->add_reply_to('bar@mail.com', 'Mr. Bar');

add_to

bool add_to(string mail_to, [string name])

Descripción

Agrega una dirección de correo destino a las ya existentes, la cual debe ser sintácticamente correcta devolviendo 'true' si se añade con éxito o 'false' en caso contrario. Opcionalmente se puede especificar un nombre de contacto.

Parámetros

mail_to

Correo electronico del destinatario

name

Nombre o texto del contacto

Ejemplos

$mimemail->add_to('foo@mail.com', 'Mr. Foo');
$mimemail->add_to('bar@mail.com', 'Mr. Bar');

get_eml

string get_eml()

Descripción

Devuelve el contenido del correo formado en formato EML que puede servir para archivarlo en una base de datos o archivos de texto.

Ejemplos

$correo_eml = $mimemail->get_eml();

get_smtp_log

string get_smtp_log()

Descripción

Devuelve el contenido de la conversación entre esta clase y el SMTP.

Para hacer uso de esta función es necesario establecer previamente la propiedad 'set_smtp_log' a 'true'. Esto es especialmente útil cuando se tiene algún problema con el envío por SMTP y se desea revisar todos los comandos enviados y las respuestas del servidor SMTP.

Ejemplos

$mimemail->set_smtp_log(true);

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo $mimemail->get_smtp_log();
}

get_version

string get_version()

Descripción

Devuelve el numero de versión de esta clase.

Ejemplos

echo "Nomad MIME Mail, version: " . $mimemail->get_version();

new_mail

void new_mail([string from], [string to], [string subject], [string text], [string html])

Descripción

Esta función es una vía rápida para borrar todas las variables generadas por un antiguo envío de correo sobre el mismo objeto y/o para asignar de forma rápida algunas de las opciones para el envío de un correo MIME

Todos los parámetros son opcionales

Parámetros

from

Correo electrónico del remitente

Correo electrónico del destinatario

subject

Asunto del correo

text

Mensaje en Texto Plano

html

Mensaje en HTML

Ejemplos

$from = "me@mail.com";
$to = "friend@mail.com";
$subject = "Hello friend";
$text = "This is my Text Plain Message";
$html = "This is mi message in HTML";

$mimemail->new_mail($from, $to, $subject, $text, $html);

nomad_mimemail

void nomad_mimemail()

Descripción

Este es el constructor de la clase

Parámetros

No tiene parámetros

Ejemplos

$mimemail = new nomad_mimemail();

send

bool send()

Descripción

Envía el correo MIME con las características agregadas en la composición del mensaje.

Si el envío se ha realizado con éxito devuelve 'true' en caso contrario 'false'

Parámetros

No tiene parametros

Ejemplos

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

set_bcc

bool set_bcc(string mail_bcc, [string name])

Descripción

Establece una dirección de correo como copia al carbón oculta 'bcc', el cual debe ser sintácticamente correcto devolviendo 'true', en caso contrario devuelve 'false'. Opcionalmente se puede especificar un nombre de contacto

Nota: Este método borra cualquier correo o correos existentes anteriormente en la variable 'mail_bcc'

Parámetros

mail_bcc

Correo electrónico del destinatario

name

Nombre o texto del contacto

Ejemplos

$mimemail->set_bcc('jhon@mail.com', 'Mr. Doe');

set_charset

void set_charset(string charset)

Descripción

Establece el juego de caracteres que será usado al momento de generar el correo electrónico

Parámetros

charset

Juego de Caracteres válido

Ejemplos

$mimemail->set_charset("ISO-8859-1");

set_cc

bool set_cc(string mail_cc, [string name])

Descripción

Establece una dirección de correo como copia al carbón 'cc', el cual debe ser sintácticamente correcto devolviendo 'true', en caso contrario devuelve 'false'. Opcionalmente se puede especificar un nombre de contacto

Nota: Este método borra cualquier correo o correos existentes anteriormente en la variable 'mail_cc'

Parámetros

mail_cc

Correo electrónico del destinatario

name

Nombre o texto del contacto

Ejemplos

$mimemail->set_cc('jhon@mail.com', 'Mr. Doe');

set_from

void set_from(string mail_from, [string name])

Descripción

Establece la dirección de correo del remitente, el cual debe ser sintácticamente correcto. Opcionalmente se puede especificar un nombre de contacto

Parámetros

mail_from

Correo electrónico del remitente

name

Nombre o texto del contacto

Ejemplos

$mimemail->set_from('fake@mail.com', 'No Reply');

set_html

void set_html(string html)

Descripción

Establece el mensaje del correo en HTML

Parámetros

html

Mensaje en HTML

Ejemplos

$mimemail->set_html('This is mi message in HTML');

set_reply_to

bool set_reply_to(string mail_reply_to, [string name])

Descripción

Establece el correo electrónico al cual se responderá cuando el usuario pulse sobre su opcion de responder (reply) de su cliente de correo electronico.

Parámetros

mail_reply_to

Correo electrónico de Respuesta

name

Nombre o texto del contacto

Ejemplos

$mimemail->set_reply_to('me@mail.com', 'Your Nightmare');

set_return_path

bool set_return_path(string mail_return_path)

Descripción

Establece la dirección del regreso de correo, en muchas ocaciones se usa para indicar a que correo se debe de enviar en caso de error o de no existir un correo destino.

Parámetros

mail_return_path

Correo electrónico del regreso del correo

Ejemplos

$mimemail->set_return_path('hostmaster@mail.com');

set_smtp_auth

bool set_smtp_auth(string user, string pass)

Descripción

Establece el nombre de usuario y contraseña requerído por el servidor SMTP. Para que este Metodo funcione, es necesario llamar a 'set_smtp_host', en el cual se declara cual es el host que tiene el SMTP a utilizar.

Solo es necesario llamar a este método cuando se requiera usar SMTP con autentificación,

Parámetros

user

Nombre de usuario del SMTP con autenticación, en muchos casos el nombre de usuario es el correo.

pass

Contraseña de la cuenta de correo en el SMTP

Ejemplos

$mimemail->set_smtp_host("domain.com");
$mimemail->set_smtp_auth("user", "pass");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

set_smtp_host

bool set_smtp_host(string host, [int port])

Descripción

Establece el host donde se conectará por SMTP para enviar el correo. Llamar a este método establece automáticamente que el correo se enviará vía SMTP.

En caso de no necesitar envíar el correo por SMTP, no es necesario llamar a este método, y dejar que el correo se envíe por la función 'mail' de PHP.

Si requiere de autenticación por SMTP deberá de llamar tambien a la función 'set_smtp_auth'

Parámetros

host

El nombre de dominio o IP a la que esta clase se conectará para enviar el correo.

port

Opcionalmente puede declarar el puerto a conectarse en el servidor, por defecto el puerto esta establecido al 25

Ejemplos

set_smtp_log

void set_smtp_log(bool log)

Descripción

Establece que se guarde toda la conversación entre esta clase y un SMTP, que despues podrá ser recuperador por medio de la función 'get_smtp_log'. Esto es especialmente útil cuando se tiene algún problema con el envío por SMTP y se desea revisar todos los comandos enviados y las respuestas del servidor SMTP.

Parámetros

log

Si se desea recuperar la conversación con el SMTP debe declararse en true. Se encuentra por defecto en 'false'.

Ejemplos

$mimemail->set_smtp_log(true);

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo $mimemail->get_smtp_log();
}

set_subject

bool set_subject(string subject)

Descripción

Establece el asunto del correo

Parámetros

subject

Asunto del correo

Ejemplos

$mimemail->set_subject('Contact mail from my page');

set_text

void set_text(string text)

Descripción

Establece el contenido del correo en texto plano

Parámetros

text

Mensaje en texto plano

Ejemplos

$mimemail->set_text('This is mi message in plain text');

set_to

bool set_to(string mail_to, [string name])

Descripción

Establece una dirección de correo destino, el cual debe ser sintácticamente correcto y devuelve 'true', en caso contrario devuelve 'false'. Opcionalmente se puede especificar un nombre de contacto

Nota: Este método borra cualquier correo o correos existentes anteriormente en la variable 'mail_to'

Parámetros

mail_to

Correo electrónico del destinatario

name

Nombre o texto del contacto

Ejemplos

$mimemail->set_to('jhon@mail.com', 'Mr. Doe');

4. Cambios en Versiones.

Versión 1.0

Versión de publicación en phpclasses.org. Clase totalmente escrita en español

Versión 1.2

Traducción de la clase al inglés. Se descarta la versión en Español
Creación de la ducumentación en Español
Variable de charset
Se arregló un bug que no permitía que una misma imagen embebida se repitiera varias veces en el HTML
Soporte para nombres largos de windows en los adjuntos

Versión 1.3

Soporte para 'Return Path'
Soporte de imagenes de 'background'
Soporte para CSS embebido
Soporte para correo de Respuesta (reply)
Agregado el metodo get_eml
Corrección de gran parte de la sintaxis del codigo
Optimización en la búsqueda de Imagenes embebidas
Corrección de algunos bugs

Versión 1.4

Cambio de nombre de "Nexus MIME Mail" a "Nomad MIME Mail"
Soporte para agregar contenido como adjunto 'add_content_attachment'
Soporte para más de un correo de respuesta 'add_reply_to'
Soporte para envío por SMTP 'set_smtp_host'
Soporte para envío por SMTP autenticado 'set_smtp_auth'
Soporte para debugear la conversación entre el script y el SMTP 'set_smtp_log' y 'get_smtp_log'
Codigo ducumentado estilo Doxygen
Corrección de algunos bugs
Actualización de la documentación

Versión 1.5

Arreglado problema de error "UNDISCLOSED RECIPIENTS"
Arreglado error de sintaxis en "_build_headers"
Arreglado problemas de charset de texto plano en "_build_body"
Se agregó el método "set_charset()"
Nuevo logotipo y página del proyecto
Actualización de la documentación

Versión 1.6

Cambio de Cabeceras de la Librería
Arreglado problema de saltos de linea en Qmail
Cambio de estilo de comentarios a phpDocumentor
Arreglado problema con _php_version_check()
Arreglado problema con Correos Duplicados
Actualización de la documentación

5. Por hacer.

Revisar que no se repitan correos electrónicos en to, cc y bcc
Un parser para convertir de HTML a texto plano mas sofisticado
Que no se repitan mismos nombres en adjuntos

6. Colaboradores.

Agradecemos a las personas que han dado su apoyo y soporte para el desarrollo de esta clase.

7. Licencia.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA