API JavaMail Autor: Sun

Traductor: Juan Antonio Palos (Ozito)

API JavaMail o Introducción al API JavaMail o Revisión de los Protocolos Relacionados

SMTP POP IMAP MIME NNTP y Otros

Instalar el API JavaMail o Instalación

Instalar JavaMail 1.2 Instalar JavaMail 1.1.3 Instalar el Marco de Trabajo de Activación de JavaBeans Usarlo con Java 2 Enterprise Edition

o Configurar Nuestro Entorno JavaMail Paso 1 Paso 2 Paso 3 Paso 4 Paso 5 Paso 6 Paso 7

Las clases Corazón o Revisar las Clases Corazón

Session Message Address Authenticator Transport Store y Folder Más allá

Utilización del API JavaMail o Enviar Mensajes o Leer Mensajes o Borrar Mensajes y Banderas o Autentificación o Responder a Mensajes o Re-Enviar Mensajes o Trabajar con Attachments o Enviar Attachments o Obtener Attachments o Procesar Mensajes HTML o Enviar Mensajes HTML o Includir Imágenes en Nuestos Mensajes

Buscar Con SearchTerm o Búsquedas con SearchTerm o Recursos

API JavaMail

Introducción al API JavaMail

El API JavaMail es un paquete opcional (extensión estándard) para leer, componer, y enviar mensajes electrónicos.

Usamos este paquete para crear programas del tipo MUA (Mail User Agent), similares a Eudora, Pine, y Microsoft Outlook. Su propósito principal no es transportar, enviar, o re-enviar mensajes como sendmail u otros programas del tipo MTA (Mail Transfer Agent). En otras palabras, los usuarios interactúan con los programas para leer y escribir e-mails. Los programas MUA tratan con los programas MTA para el envío real.

El API JavaMail está diseñado para proporcionar acceso independiente del protocolo para enviar y recibir mensajes dividiendose en dos partes:

La primera parte del API es el foco de este tutor. Basicamente, cómo enviar y recibir mensajes independientemente del proveedor/protocolo.

La segunda parte habla de lenguajes especificos del protocolo como SMTP, POP, IMAP, y NNTP. Con el API, JavaMail para poder comunicar con un servidor, necesitamos un proveedor para un protocolo.

Revisión de los Protocolos Relacionados

Antes de mirar dentro de las especificaciones del API JavaMail, echemos un vistazo a los protocolos usados con el API. Básicamente son cuatro:

SMTP

POP

IMAP

MIME

También ejecutaremos sobre NNTP y algunos otros. Entender lo básico de cada protocolo nos ayudará a entender mejor cómo usar el API JavaMail. Aunque el API sea independiente del protocolo, no podemos evitar las limitaciones de los protocolos subyacentes. Si una capacidad no está soportada por el protocolo elegido, el API JavaMail no hará que esa capacidad aparezca por arte de magia.

(Como veremos pronto, este es un problema normal cuando trabajamos con POP).

SMTP

El protocolo Simple Mail Transfer Protocol (SMTP) está definido por la RFC 821. Define el mecanismo para enviar e-mail. En el contexto del API JavaMail, nuestro programa basado en JavaMail comunicará con el servidor SMTP de nuestro proveedor de servicios (ISP). Este servidor SMTP dejará el mensaje en el servidor SMTP del recipiente(s) para que sea recogido por los usuarios a través de POP o IMAP. Esto no requiere que nuestro servidor SMTP sea un rele abierto, pues se utiliza la autentificación, pero es nuestra responsabilidad asegurarnos de que el servidor SMTP se configure correctamente. No hay nada en el API JavaMail sobre tareas como el configuración de un servidor para retransmitir mensajes o para agregar y para quitar cuentas del e-mail.

POP

POP viene de Post Office Protocol. Actualmante en la versión 3, también conocido como POP3, la RFC 1939 define este protocolo.

POP es el mecanismo que la mayoría de la gente usa en Internet para conseguir su correo. Define el soporte de un sólo mailbox por cada usuario. Ésto es todo lo que lo hace, y ésta también es la fuente de la mayoría de la confusión. Muchas de las cosas con que gente se familiariza cuando usa POP, como la capacidad de ver cuántos mensajes de correo nuevos tienen, no lo soporta POP en absoluto. Estas capacidades se construyen en programas como Eudora o Microsoft Outlook, que recuerdan cosas como los últimos correos recibidos y calculan cuántos tenemos nuevos. Así pues, al usar el API JavaMail, si queremos este tipo de información tendremos que calcularla nosotros mismos.

IMAP

IMAP es un protocolo más avanzado para recibir mensajes. Definido en la RFC 2060, IMAP viene de Internet Message Access Protocol, y está actualmente en la versión 4, también conocida como IMAP4. Para usar el IMAP, nuestro servidor de correo debe soportar este protocolo. No podemos simplemente cambiar nuestro programa para usar IMAP en vez de POP y que se soporte todo IMAP. Si asumimos que nuestro servidor de correo soporta IAMP, nuestro programa basado en JavaMail puede aprovecharse de los usuario que tienen carpetas múltiples en el servidor y estas carpetas se pueden compartir por varios usuarios.

Debido a las capacidades más avanzadas, podríamos pensar que IMAP sería utilizado por todos. Pero no es así. Sobrecarga mucho el servidor de correo, requiriendo que el servidor reciba los nuevos mensajes, los entrege a los usuarios cuando sean solicitados, y los mantiene en las distintas carpetas de cada usuario. Aunque que esto centraliza las copias de seguridad, también hace que las carpetas de correo a largo plazo de los usuarios se hagan cada vez más grandes, y todo el mundo sufre cuando se agota el espacio en el disco. Con POP, los mensajes recuperados son eliminados del servidor de correo.

MIME

MIME viene de Multipurpose Internet Mail Extensions. No es un protocolo de transferencia de e-mail. En su lugar, define el contenido de lo que se está transfiriendo: el formato de los mensajes, los attachments, etc. Hay muchos documentos que tienen efecto sobre esto: las RFC 822, RFC 2045, RFC 2046, y RFC 2047. Como usuario del API JavaMail, normalmente no tendremos que preocuparnos sobre estos formatos. Sin embargo, estos formatos existen y son utilizados por nuestros programas.

NNTP y Otros

A causa de la división del API JavaMail entre proveedor y cualquier otra cosa, podemos fácilmente soportar protocolos adicionales. Sun Mantiene una lista de proveedores de terceras partes que se aprovechan de los protocolos para los que Sun no proporciona soporte. Allí encontraremos soporte para NNTP Network News Transport Protocol [newsgroups], S/MIME Secure Multipurpose Internet Mail Extensions, y más.

Instalar el API JavaMail o Instalación

Instalar JavaMail 1.2 Instalar JavaMail 1.1.3 Instalar el Marco de Trabajo de Activación de JavaBeans Usarlo con Java 2 Enterprise Edition

o Configurar Nuestro Entorno JavaMail Paso 1 Paso 2 Paso 3 Paso 4 Paso 5 Paso 6 Paso 7

Instalar el API JavaMail

Instalación

Hay dos versiones del API JavaMail usadas comunmente hoy en dia: la 1.2 y la 1.1.3. Todos los ejemplos de este artículo funcionan con ámbas. Mientras 1.2 es el último, 1.1.3 es la versión incluida en la versión 1.2.1 de la Plataforma Java 2 Enterprise Edition (J2EE), por eso es tan usado. La versión del API que queramos usar afecta a lo que tengamos que descargar e instalar. Todo funcionará con el JDK 1.1.6+, de la Plataforma Java 2, Standard Edition (J2SE) versión 1.2.x, y J2SE versión 1.3.x.

Nota: después de instalar la implementación de JavaMail de Sun, podrás encontrar muchos

programas de ejemplo en el directorio: demo.

Instalar JavaMail 1.2

Para usar el API JavaMail 1.2, descargamos la implementación, JavaMail 1.2,

descomprimimos el fichero javamail-1_2.zip, y añadimos el fichero mail.jar a nuestro CLASSPATH. La implementación 1.2 viene con proveedores para SMTP, IMAP4, y POP3 junto con las clases corazón.

Después de instalar JavaMail 1.2, instalamos el marco de trabajo de activación de JavaBeans.

Instalar JavaMail 1.1.3

Para usar el API JavaMail 1.1.3, descargamos la implementación JavaMail 1.1.3,

descomprimimos el ficherosjavamail1_1_3.zip, y añadimos el fichero mail.jar a nuestro CLASSPATH. La implementación 1.1.3 viene con proveedores para SMTP y IMAP4, junto con las clases corazón.

Si queremos acceder a un servidor POP con JavaMail 1.1.3, descargamos e instalamos un proveedor POP3. Sun tiene uno disponible separado de la implementación de JavaMail.

después de descargar y descomprimir pop31_1_1.zip, también añadimos pop3.jar a nuestro

CLASSPATH.

Después de instalar JavaMail 1.1.3, instalamos el marco de trabajo de activación de JavaBeans.

Instalar el Marco de Trabajo de Activación de JavaBeans

Todas las versiones del API JavaMail requieren el Marco de Trabajo para la Activación de JavaBeans.

El marco de trabajo añade soporte para tecleo arbitrario de bloques de datos y manejarlos correctamente. Esto no suena muy bien, pero es nuestro soporte básico para MIME-type

encontrado en muchos navegadores y herramientas de correo, hoy en día. Después de

descargar el marco de trabajo, descomprimimos el fichero jaf1_0_1.zip, y añadimos el

ficheroactivation.jar a nuestro CLASSPATH.

Para usuarios de JavaMail 1.2, deberíamos tener mail.jar y activation.jar en nuestro CLASSPATH.

Para usuarios de JavaMail 1.1.3, deberíamos tener mail.jar, pop3.jar, y activation.jar en nuestro CLASSPATH. Si no tenemos planes de utilizar POP3, no necesitamos añadirlo a nuestro CLASSPATH.

Si no queremos modificar nuestra variable de entorno CLASSPATH, copiamos los

ficheros JAR a nuestro directorio lib/extbajo el directorio del Java Runtime Environment (JRE). Por ejemplo, para la versión J2SE 1.3, el directorio por defecto

seríaC:\jdk1.3\jre\lib\ext en una plataforma Windows.

Usarlo con Java 2 Enterprise Edition

Si usamos J2EE, no tenemos que hacer nada especial para usar el API básico de JavaMail;

viene con las clases del J2EE. Sólo debemos asegurarnos de que el fichero j2ee.jar está en nuestro CLASSPATH y que tenemos todo configurado.

Para J2EE 1.2.1, el proveedor POP3 viene separado, por eso lo descargamos y seguimos los pasos para incluir el proveedor POP3 como se mostró en Instalar JavaMail 1.1.3. Los usuario de J2EE 1.3 obtienen el proveedor POP3 con el J2EE por eso no requieren una instalación separada. Tampoco se requiere ninguna instalación para el Marco de Trabajo de Activación de JavaBeans.

Configurar Nuestro Entorno JavaMail

Paso 1

Descargar la última versión de la implementación del API JavaMail desde Sun.

Paso 2

Descargar la última versión del Marco de Trabajo de Activación de JavaBeans desde Sun.

Paso 3

Descomprimir los paquetes descargados. Obtendremos un fichero ZIP para todas los plataformas de los dos paquetes.

Podemos usar la herramienta jar para descomprimir los paquetes.

Paso 4

Añadimos los ficheros mail.jar y activation.jar recien descomprimidos a

nuestro CLASSPATH.

Copiamos estos ficheros a nuestro directorio de librerías de extensión. Para Windows, y usando una instalación por defecto, el comando se parecería a esto:

cd \javamail-1.2

copy mail.jar \jdk1.3\jre\lib\ext

cd \jaf-1.0.1

copy activation.jar \jdk1.3\jre\lib\ext

Si no nos gusta copiar los ficheros al directorio de librerías de extensión, en Sun puedes encontrar instrucciones detalladaspara configurar el CLASSPATH sobre Windows NT

Paso 5

Vamos dentro del directorio demo que viene con la implementación del API JavaMail y

compilamos el programa msgsend para enviar un mensaje de prueba:

javac msgsend.java

Paso 6

Ejecutamos el programa pasandole una dirección "from" en la opción -o, nuestro servidor

SMTP con la opción -M, y la dirección "to" (sin opción). Luego introduciremos el subject, el texto de nuestro mensaje y el caracter de fin-de-fichero (CTRL-Z) para indicar el final de la introducción del mensaje.

Debemos asegurarnos de reemplazar las direcciones correctas:

java msgsend -o from@address -M SMTP.Server to@address

Si no estas seguro de tu servidor SMTP, contacta con el administrador de tu sistema o pregunta a tu proveedor de Internet.

Paso 7

Para asegurarnos de que hemos recibido el mensaje, debemos chequearlo con nuestro lector de correo habitual (Eudora, Outlook Express, pine, ...).

Las clases Corazón o Revisar las Clases Corazón

Session Message Address Authenticator Transport Store y Folder Más allá

Las clases Corazón

Revisar las Clases Corazón

Antes de profundizar en las classes de JavaMail, veremos las clases corazón que componen el API: Session, Message,Address, Authenticator, Transport, Store, y Folder. Todas estas

clases se encuentran en el paquete del nivel superior del API JavaMail: javax.mail, aunque

frecuentemente nos veremos utilizando clases del paquete javax.mail.internet.

Session

La clase Session define una sesión de correo básica. Es a través de esta de sesión de la que

todas las demás funcionan. El objeto Session se aprovecha de un

objeto java.util.Properties para obtener información como el servidor de correo, el nombre de usuario, la password, y otra información que puede compartirse a lo largo de toda la aplicación.

El constructor para las clases es privado. Podemos obtener una sola sesión por defecto que

puede ser compartida con el método getDefaultInstance():

Properties props = new Properties();

// fill props with any information

Session session = Session.getDefaultInstance(props, null);

O podemos crear una única sesión con getInstance():

Properties props = new Properties();

// fill props with any information

Session session = Session.getInstance(props, null);

En ambos casos el argumento null es un objeto Authenticator que no se utiliza en este

momento, lo veremos más adelante en Authenticator.

En la mayoría de los casos, es suficiente usar la sesión compartida, incluso si se trabaja con una sesión de correo para múltiples mailboxes de usuario. Podemos añadir una combinación de nombre de usuario y passsword en un paso posterior en el proceso de comunicación, manteniendolo todo separado.

Message

Una vez que tenemos nuestro objeto Session, es hora de empezar a crear un mensaje para

enviar. Esto se hace con un objeto Message.

Siendo una clase abstracta, debemos trabajar con una subcalse, en la mayoría de los casos

serájavax.mail.internet.MimeMessage.

Un MimeMessage es un mensaje de e-mail que entiende los tipos MIME, definidos en las distintas RFCs. Las cabeceras de mensajes están restringidas a caracteres US-ASCII, aunque en ciertos campos de cabecera se pueden codificar caracteres no ASCII.

Para crear un Message, le pasamos el objeto Session al constructor de MimeMessage:

MimeMessage message = new MimeMessage(session);

Nota: Hay otros constructores, como para crear mensajes desde streams de entrada

formateados RFC822.

Una vez que tenemos nuestro mensaje, podemos configurar sus diferentes partes, como Message implementa el interfacePart (con MimeMessage implementando MimePart).

El mecanismo básico para configurar el contenidos es el método setContent(), con los argumentos para el contenido y tipo mime:

message.setContent("Hello", "text/plain");

Sin embargo, si sabemos que estámos trabajando con un MimeMessage y nuestro mensaje es

texto plano, podemos usar su método setText() que sólo requiere el contenido real, dejando

por defecto el tipo MIME a text/plain:

message.setText("Hello");

Para mensajes de texto plano la última forma es el mecanismo preferido para seleccionar el contenido. Para enviar otros tipos de mensajes, como HTML, usaremos el formador, que veremos más adelante.

Para seleccionar el subject, usamos el método setSubject():

message.setSubject("First");

Address

Una vez que hemos creado la Session y el Message, y también hemos rellenado el mensaje

con contenido, es hora de poner dirección a nuestra carta con un objeto Address.

Como Message, Address es una clase abstracta. Usaremos la

clase javax.mail.internet.InternetAddress.

Para crear una dirección con sólo la dirección e-mail, se la pasamos al constructor:

Address address = new InternetAddress("president@whitehouse.gov");

Si queremos que aparezca el nombre junto a la dirección e-mail, también podemos pasárselo al constructor:

Address address = new InternetAddress("president@whitehouse.gov", "George

Bush");

Necesitaremos crear objetos address para los campos from y to del mensaje. A menos que el servidor lo evite, no hay nada que nos impida enviar un mensaje que parezca que viene de otra persona.

Una vez que hemos creado las direcciones, las conectamos al mensaje de una de estas dos

formas. Para identificar al que lo envía, usamos los métodos setFrom() y setReplyTo().

message.setFrom(address)

Si nuestro mensane necesita varias direcciones "from", usamos el método addFrom():

Address address[] = ...;

message.addFrom(address);

Para identificar a los receptores del mensaje, usamos el método addRecipient(). Este método

requiere unMessage.RecipientType junto a la dirección.

message.addRecipient(type, address)

Los tres tipos predefinidos de direcciones son:

Message.RecipientType.TO

Message.RecipientType.CC

Message.RecipientType.BCC

Por eso, si el mensaeje fuera dirigido al vice-presidete, enviando copia a la primera dama, esto sería lo apropiado:

Address toAddress = new InternetAddress("vice.president@whitehouse.gov");

Address ccAddress = new InternetAddress("first.lady@whitehouse.gov");

message.addRecipient(Message.RecipientType.TO, toAddress);

message.addRecipient(Message.RecipientType.CC, ccAddress);

El API JavaMail no proporciona mecanismo para chequear la validez de una dirección e-mail. Pero si podemos hacer que nuestro programa soporte un scan de caracteres válidos (según lo definido en la RFC 822) o verificar nosotros mismos el registro MX (Mai Exchange), esto va más allá del ámbito del API JavaMail.

Authenticator

Como las clases java.net, el API JavaMail peude aprovecharse de un Authenticator para proteger accesos a recursos mediante un nombre de usuario y una password. Para el API

JavaMail, el recursos es el servidor de correo. ElAuthenticator JavaMail se encuentra en el

paquete javax.mail y es diferente de la clase de java.net con el mismo nombre. Las dos no

comparten el mismo Authenticator ya que el API JavaMail funciona con Java 1.1, que no

tenía la veriedad java.net.

Para usar el Authenticator, subclasificamos la clase abstracta y devolvemos un

ejemplar PasswordAuthentication del método getPasswordAuthentication(). Debemos

registrar el Authenticator con la sesión cuando se crea. Luego, nuestro Authenticator será notificado cuando sea necesaria una autentificación. Podríamos mostrar una ventana o leer el nombre de usuario y la password desde un fichero de configuración (aunque si no está

encriptado no es seguro), devolviendolo al llamador como un objeto PasswordAuthentication.

Properties props = new Properties();

// fill props with any information

Authenticator auth = new MyAuthenticator();

Session session = Session.getDefaultInstance(props, auth);

Transport

La parte final del envío de un mensaje es usar la clase Transport. Estas clase habla el lenguaje específico del protocolo para enviar mensajes (normalmente SMTP). Es una clase

abstracta y funciona como Session.

Podemos usar la versión por defecto de la clase sólo llamando al método estático send():

Transport.send(message);

O, podemos obtener un ejemplar específico desde la sesión para nuestro protocolo, pasándole el nombre de usuario y la password (en blanco si no son necesarias), enviar el mensaje, y cerrar la conexión:

message.saveChanges(); // implicit with send()

Transport transport = session.getTransport("smtp");

transport.connect(host, username, password);

transport.sendMessage(message, message.getAllRecipients());

transport.close();

Esta última forma es mejor cuando necesitamos enviar varios mensajes, porque mantendrá activa la conexión entre mensajes. El mecanismo básico send() hace un conexión separada al

servidor para cada llamada a método.

Nota: Para ver los comandos enviados al servidor de correo activaremos la bandera

debug consession.setDebug(true).

Store y Folder

Obtener los mensajes empieza de forma similar a enviar mensajes, con una Session.

Sin embargo, después de obtener la sesión, conectamos a un Store, probablemente con un

nombre de usuario y una password o Authenticator. Como con Transport, le decimos

al Store qué protocolo utilizar:

// Store store = session.getStore("imap");

Store store = session.getStore("pop3");

store.connect(host, username, password);

Después de conectar al Store, podemos obtener un Folder, que debe estar abierto antes de

poder leer los mensajes que hay en su interior:

Folder folder = store.getFolder("INBOX");

folder.open(Folder.READ_ONLY);

Message message[] = folder.getMessages();

Para POP3, la única carpeta disponible es INBOX. Si estamos usando IMAP, podremos disponer de otras carpetas.

Nota: Los proveedores de Sun se han pensado para ser inteligentes. Mientras

que Message message[] = folder.getMessages(); podría parecer una operación lenta

que lee todos los mensajes del servidor, sólo cuando realmente necesitamos obtener una

parte del mensaje es cuando el contenido es recuperado.

Una vez que tenemos un Message para leer, podemos obtener sus contenidos

con getContent() o escribir sus contenidos en un stream con writeTo(). El

método getContent() sólo obtiene el contenido del mensaje, mientras que la salida

dewriteTo() incluye las cabeceras.

System.out.println(((MimeMessage)message).getContent());

Después de haber leído el e-mail, cerramos la conexión al folder y al store.

folder.close(aBoolean);

store.close();

El valor boolenao pasado al método close() del folder significa si actualizamos o no la carpeta

eliminando los mensajes borrados.

Más allá

Esencialmente, entender cómo usar las siete clases es todo lo que necesitamos para manejar el API JavaMail. La mayoría de las otras capacidades del API JavaMail construidas desde estas siete clases hacen algo un poco diferente o de una forma particular, como si el contenido es un attachment. Ciertas tareas, como las búsquedas, están aisladas y se describen en la sección Busquedas por SearchItem.

Utilización del API JavaMail o Enviar Mensajes o Leer Mensajes o Borrar Mensajes y Banderas o Autentificación o Responder a Mensajes o Re-Enviar Mensajes o Trabajar con Attachments o Enviar Attachments o Obtener Attachments o Procesar Mensajes HTML o Enviar Mensajes HTML o Includir Imágenes en Nuestos Mensajes

Utilización del API JavaMail

Ya hemos visto como trabajar con las partes principales del API JavaMail. En esta página encontraremos aproximaciones de cómo conectar las piezas para realizar tareas específicas.

Enviar Mensajes

Enviar un mensaje de e-mail implica obtener una sesión, crear y rellenar un mensaje y enviarlo. Podemos especificar nuestro servidor SMTP configurando la propiedad mail.smtp.host del

objeto Properties cuando se obtuvo la Session:

String host = ...;

String from = ...;

String to = ...;

// Get system properties

Properties props = System.getProperties();

// Setup mail server

props.put("mail.smtp.host", host);

// Get session

Session session = Session.getDefaultInstance(props, null);

// Define message

MimeMessage message = new MimeMessage(session);

message.setFrom(new InternetAddress(from));

message.addRecipient(Message.RecipientType.TO,

new InternetAddress(to));

message.setSubject("Hello JavaMail");

message.setText("Welcome to JavaMail");

// Send message

Transport.send(message);

Deberíamos situar el código dentro de un bloque try-catch, porque la configuración del mensaje y su envío pueden lanzar excepciones.

Aquí tienes el código fuente MailExample.java completo.

Leer Mensajes

Para leer mensajes, obtenemos una sesión, y nos conectamos con el store apropiado para nuestro mailbox, abrimos la carpeta apropiada, y obtenemos nuestros mensajes. También, no debemos olvidarnos de cerrar la conexión cuando hayamos terminado.

String host = ...;

String username = ...;

String password = ...;

// Create empty properties

Properties props = new Properties();

// Get session

Session session = Session.getDefaultInstance(props, null);

// Get the store

Store store = session.getStore("pop3");

store.connect(host, username, password);

// Get folder

Folder folder = store.getFolder("INBOX");

folder.open(Folder.READ_ONLY);

// Get directory

Message message[] = folder.getMessages();

for (int i=0, n=message.length; i<n; i++) {

System.out.println(i + ": " + message[i].getFrom()[0]

+ "\t" + message[i].getSubject());

}

// Close connection

folder.close(false);

store.close();

Lo que hagamos con cada mensaje es cosa nuestra. El bloque de código anterior sólo muestra de quién viene el mensaje y el subject. Técnicamente hablando, la lista de direcciones "from"

podría estar vacía y la llamada a getFrom()[0] podría lanzar una excepción.

Para mostrar el mensaje completo, podemos pedírselo al usuario después de haya visto los

campos subject, y luego llamar al método writeTo() si quiere verlo.

BufferedReader reader = new BufferedReader (

new InputStreamReader(System.in));

// Get directory

Message message[] = folder.getMessages();

for (int i=0, n=message.length; i<n; i++) {

System.out.println(i + ": " + message[i].getFrom()[0]

+ "\t" + message[i].getSubject());

System.out.println("Do you want to read message? " +

"[YES to read/QUIT to end]");

String line = reader.readLine();

if ("YES".equals(line)) {

message[i].writeTo(System.out);

} else if ("QUIT".equals(line)) {

break;

}

}

Aquí tienes el código fuente GetMessageExample.java completo.

Borrar Mensajes y Banderas

Borrar mensajes implica trabajar con lasFlags asociadas con los mensajes. Hay diferentes banderas para diferentes estados, algunas definidas por el sistema y otras definidas por el

usuario. Las banderas predefinidas se definen en forma de clase interna Flags.Flag y se listan

abajo:

Flags.Flag.ANSWERED

Flags.Flag.DELETED

Flags.Flag.DRAFT

Flags.Flag.FLAGGED

Flags.Flag.RECENT

Flags.Flag.SEEN

Flags.Flag.USER

Sólo porque una bandera exista no significa que sea soportada por todos los proveedores/servidores de correo. Por ejemplo, excepto la de mensaje borrado, el protocolo POP no soporta ninguna de ellas. Chequear por nuevo correo no es una tarea de POP pero si está construidad en los clientes de correo. Para conocer las banderas soportadas, solicitamos

la carpeta congetPermanentFlags().

Para borrar mensajes, seleccionamo la bandera DELETED del mensaje:

message.setFlag(Flags.Flag.DELETED, true);

Primero debemos abrir la carpeta en modo READ_WRITE:

folder.open(Folder.READ_WRITE);

Luego, cuando hayamos procesado todos los mensajes, cerramos la carpeta, pasando un valor true para purgar todos los mensajes borrados.

folder.close(true);

Hay un método expunge() de Folder que puede usarse para borrar los mensajes. Sin embargo, no funciona con el proveedor POP3 de Sun.

Otros proveedores podrían o no podrían implementar estas capacidades. Serían más que las implementadas por los proveedores de IMAP. Como POP sólo soporta acceso al mailbox, nosotros tenemos que cerrar la carpeta para borrar los mensajes con el proveedor de Sun.

Para deseleccionar una bandera, sólo pasando false al método setFlag(). Para ver si una

bandera está seleccionada, lo comprobamos con isSet().

Autentificación

Aprendimos anteriormente que podemos usar un Authenticator para pedir un nombre de usuario y una password cuando sea necesario, en vez de pasarlo en strings. Aquí veremos como hacer un uso más útil de la autentificación.

En lugar de conectar al Store con el host, el username, y la password, configuramos

las Properties que tiene el host, y le decimos a la Session el ejemplar

del Authenticator personalizado:

// Setup properties

Properties props = System.getProperties();

props.put("mail.pop3.host", host);

// Setup authentication, get session

Authenticator auth = new PopupAuthenticator();

Session session = Session.getDefaultInstance(props, auth);

// Get the store

Store store = session.getStore("pop3");

store.connect();

Luego subclasificamos Authenticator y devolvemos un

objeto PasswordAuthentication desde el métodogetPasswordAuthentication(). Abajo tenemos una implementación de dicho método, con un sólo campo para ámbos. Sólo debemos introducir las dos partes en un campo, separadas por una coma.

import javax.mail.*;

import javax.swing.*;

import java.util.*;

public class PopupAuthenticator extends Authenticator {

public PasswordAuthentication getPasswordAuthentication() {

String username, password;

String result = JOptionPane.showInputDialog(

"Enter 'username,password'");

StringTokenizer st = new StringTokenizer(result, ",");

username = st.nextToken();

password = st.nextToken();

return new PasswordAuthentication(username, password);

}

}

Como el PopupAuthenticator trata con Swing, arrancará el thread de manejo de eventos para

el AWT. Esto básicamente requiere que añadamos una llamada a System.exit() en nuestro

código para parar el programa.

Responder a Mensajes

La clase Message incluye un método reply() para configurar un nuevo Message con el recipiente apropiado, añadiendo "Re: " al subject si no está ya. Esto no añade nada al contenido del mensaje, sólo copia las cabeceras from o reply-to al nuevo recipiente. El método toma un parámetro booleano indicando si la respuesta va aser a uno (false) o a todos (true).

MimeMessage reply = (MimeMessage)message.reply(false);

reply.setFrom(new InternetAddress("president@whitehouse.gov"));

reply.setText("Thanks");

Transport.send(reply);

Para configurar la dirección reply-to cuando se envía un mensaje, utilizamos el método setReplyTo().

Aquí tienes el código fuente ReplyExample.java completo.

Re-Enviar Mensajes

Re-enviar mensajes es un poco más complicado. No hay una sóla llamada a método, y construimos el mensaje a re-enviar trabajando con las partes que componen un mensaje.

Un mensaje de correo puede estar compuesto de varias partes, cada parte es un BodyPart, o

más específiamente, unMimeBodyPart cuando se trabaja con mensajes MIME. Las diferentes

partes del cuerpo se combinan en un contenedor llamado Multipart o, de nuevo, más

especificamente un MimeMultipart.

Para re-enviar un mensaje, creamos una parte para el texto de nuestro mensaje y una segunda

parte con el mensaje a re-enviar, y las combinamos dentro de un multipart.

Luego añadimos el multipart a un mensaje direccionado apropiadamente y lo enviamos.

Es esto esencialmente. Para copiar el contenido de un mensaje a otro, sólo lo copiamos sobre

su DataHandler, una clase del JavaBeans Activation Framework.

// Create the message to forward

Message forward = new MimeMessage(session);

// Fill in header

forward.setSubject("Fwd: " + message.getSubject());

forward.setFrom(new InternetAddress(from));

forward.addRecipient(Message.RecipientType.TO,

new InternetAddress(to));

// Create your new message part

BodyPart messageBodyPart = new MimeBodyPart();

messageBodyPart.setText(

"Here you go with the original message:\n\n");

// Create a multi-part to combine the parts

Multipart multipart = new MimeMultipart();

multipart.addBodyPart(messageBodyPart);

// Create and fill part for the forwarded content

messageBodyPart = new MimeBodyPart();

messageBodyPart.setDataHandler(message.getDataHandler());

// Add part to multi part

multipart.addBodyPart(messageBodyPart);

// Associate multi-part with message

forward.setContent(multipart);

// Send message

Transport.send(forward);

Trabajar con Attachments

Los Attachments son recursos asociados con un mensaje e-mail, normalmente mantenidos fuera del mensaje, como un fichero de texto, una hoja de cálculo o una imagen. Al igual que con los programas de e-mail normales como Eudora y Pine, podemos adjuntar recursos a nuestros mensajes con el API JavaMail y obtener dichos attachments cuando recibamos el mensaje.

Enviar Attachments

Enviar attachments es bastante sencillo. Construimos las partes de un mensaje completo. Después de la primera parte, el texto del mensaje, añadimos otras partes donde

el DataHandler para cada una es nuestro attachment, en vez de compartir el handler como en el caso de reenvio de mensajes. Si estamos leyendo el attachment desde un fichero, nuestra fuente de datos es un FileDataSource.

Si leemos desde una URL, es una URLDataSource.

Una vez que tenemos nuestro DataSource, se lo pasamos al constructor de DataHandler, y

finalmente lo adjutamos alBodyPart con setDataHandler().

Asumiendo que queremos retener el nombre del fichero original para el attachment, la última cosa a hacer es seleccionar el nombre de fichero asociado con el attachment con el

método setFileName() de BodyPart. Todo esto lo podemos ver aquí:

// Define message

Message message = new MimeMessage(session);

message.setFrom(new InternetAddress(from));

message.addRecipient(Message.RecipientType.TO,

new InternetAddress(to));

message.setSubject("Hello JavaMail Attachment");

// Create the message part

BodyPart messageBodyPart = new MimeBodyPart();

// Fill the message

messageBodyPart.setText("Pardon Ideas");

Multipart multipart = new MimeMultipart();

multipart.addBodyPart(messageBodyPart);

// Part two is attachment

messageBodyPart = new MimeBodyPart();

DataSource source = new FileDataSource(filename);

messageBodyPart.setDataHandler(new DataHandler(source));

messageBodyPart.setFileName(filename);

multipart.addBodyPart(messageBodyPart);

// Put parts in message

message.setContent(multipart);

// Send the message

Transport.send(message);

Cuando incluimos attachments con nuestros mensajes, si nuestro programa es un servlet, los usuarios deben subir el fichero cuando nos digan donde enviar el mensaje. La subida de cada

fichero puede ser manejada con un tipo de formulario codificado multipart/form-data.

<FORM ENCTYPE="multipart/form-data"

method=post action="/myservlet">

<INPUT TYPE="file" NAME="thefile">

<INPUT TYPE="submit" VALUE="Upload">

</FORM>

Nota: El tamaño del mensaje está limitado por el servidor SMTP, no por el API

JavaMail. Si tenemos problemas podemos incrementar el tamaño de la pila seleccionado

los parámetros ms ymx.

Aquí tienes el código fuente MailExample.java completo.

Obtener Attachments

Obtener attachments de nuestros mensajes es un poco más complicado que enviarlos, ya que MIME no tiene la sencilla noción de Attachments. El contenido de nuestro mensaje es un

objeto Multipart cuando tiene attachments. Entonces necesitamos procesar cada Part, para obtener el contenido principal del attachment(s). Las partes marcadas con una disposición

de Part.ATTACHMENT desde part.getDisposition() son claramente attachments. Sin embargo, los attachments también pueden venir sin disposición (y un tipo MIME no texto) o una

disposición de Part.INLINE. Cuando la disposición es Part.ATTACHMENT o Part.INLINE,

podemos grabar el contenido de esa parte del mensaje.

Obtenemos el nombre del fichero original con getFileName() y el stream de entrada

con getInputStream().

Multipart mp = (Multipart)message.getContent();

for (int i=0, n=multipart.getCount(); i<n; i++) {

Part part = multipart.getBodyPart(i));

String disposition = part.getDisposition();

if ((disposition != null) &&

((disposition.equals(Part.ATTACHMENT) ||

(disposition.equals(Part.INLINE))) {

saveFile(part.getFileName(), part.getInputStream());

}

}

El método saveFile() sólo crea un File desde el nombre del fichero, lee los bytes desde el stream de entrada y los escribe en el fichero. En el caso de que el fichero ya exista, se añade un número al final del nombre del fichero hasta que se encuentre uno que no exista.

// from saveFile()

File file = new File(filename);

for (int i=0; file.exists(); i++) {

file = new File(filename+i);

}

El código de arriba cubre el caso más sencillo cuando las partes del mensaje se marcan apropiadamente. Para cubrir todos los casos. Debemos manejar cuando la disposición es null y obtener el tipo MIME de la parte para manejarla de forma apropiada.

if (disposition == null) {

// Check if plain

MimeBodyPart mbp = (MimeBodyPart)part;

if (mbp.isMimeType("text/plain")) {

// Handle plain

} else {

// Special non-attachment cases here of image/gif, text/html, ...

}

...

}

Procesar Mensajes HTML

Enviar mensajes basados en HTML puede dar un poco más de trabajo que enviar mensaje sólo de texto, aunque no demaisado. Todo depende de los requerimientos que especifiquemos.

Enviar Mensajes HTML

Si todo lo que necesitamos hacer es enviar el equivalente de un fichero HTML como el mensaje y dejar que el lector de correo se preocupe de colocar cualquier imagen embebida o piezas

relacionadas, usamos el método setContent() de Message, pasandole el contenido como

un String y selecionando el tipo de contenido como text/html.

String htmlText = "<H1>Hello</H1>" +

"<img src=\"http://www.jguru.com/images/logo.gif\">";

message.setContent(htmlText, "text/html"));

En la parte del receptor, si procesamos el mensaje con el API JavaMail, no hay nada dentro del API para mostrar mensajes HTML. El API JavaMail sólo ve un stream de bytes. Para mostrar el

mensaje HTML, debemos usar un JEditorPane de Swing o cualquier otro componente

visualizador de terceras partes.

if (message.getContentType().equals("text/html")) {

String content = (String)message.getContent();

JFrame frame = new JFrame();

JEditorPane text = new JEditorPane("text/html", content);

text.setEditable(false);

JScrollPane pane = new JScrollPane(text);

frame.getContentPane().add(pane);

frame.setSize(300, 300);

frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);

frame.show();

}

Includir Imágenes en Nuestos Mensajes

Por otro lado, si queremos que nuestro mensaje HTML sea completo, con imagenes embebidas incluidas como parte del mensaje, debemos tratar las imágenes como un attachment y referenciarlas con una URL especial cid, donde el cid es una referencia a la

cabecera Content-ID de la imagen adjunta.

El proceso de embeber imágenes es muy similar a adjuntar un fichero a un mensaje, la única

diferencia es que tenemos que decirle al MimeMultipart que las partes están relacionadas

configurando su subtipo en el constructor (o consetSubType()) y configurando la

cabecera Content-ID de la imagen a un string aleatorio que es usado como el src de la

imagen en la etiqueta img.

Este código explica todo lo anterior:

String file = ...;

// Create the message

Message message = new MimeMessage(session);

// Fill its headers

message.setSubject("Embedded Image");

message.setFrom(new InternetAddress(from));

message.addRecipient(Message.RecipientType.TO,

new InternetAddress(to));

// Create your new message part

BodyPart messageBodyPart = new MimeBodyPart();

String htmlText = "<H1>Hello</H1>" +

"<img src=\"cid:memememe\">";

messageBodyPart.setContent(htmlText, "text/html");

// Create a related multi-part to combine the parts

MimeMultipart multipart = new MimeMultipart("related");

multipart.addBodyPart(messageBodyPart);

// Create part for the image

messageBodyPart = new MimeBodyPart();

// Fetch the image and associate to part

DataSource fds = new FileDataSource(file);

messageBodyPart.setDataHandler(new DataHandler(fds));

messageBodyPart.setHeader("Content-ID","memememe");

// Add part to multi-part

multipart.addBodyPart(messageBodyPart);

// Associate multi-part with message

message.setContent(multipart);

Aquí tienes el código fuente HtmlImageExample.java completo.

Buscar Con SearchTerm o Búsquedas con SearchTerm o Recursos

Buscar Con SearchTerm

Búsquedas con SearchTerm

El API JavaMail incluye un mecanismo de filtrado encontrado en el paquete

javax.mail.search para construir unSearchTerm.

Una vez construido, podemos solicitarel a una Folder qué mensajes concuerdan, recuperar un

array de objetos Message:

SearchTerm st = ...;

Message[] msgs = folder.search(st);

Hay disponibles 22 clases diferentes para ayudarnos a construir un SearchTerm.

AND (clase AndTerm)

OR (clase OrTerm)

NOT (clase NotTerm)

SENT DATE (clase SentDateTerm)

CONTENT (clase BodyTerm)

HEADER (FromTerm / FromStringTerm, RecipientTerm/ RecipientStringTerm, SubjectTerm,

etc.)

Esencialmente, construimos una expresión lógica para concordar mensajes, luegos los buscamos. Por ejemplo, el siguiente término busca los mensajes con uns string (parcial) en el

sibject de ADV o un campo "from" defriend@public.com.

Podríamos considerar la ejecución periódica de esta consulta y borrar automáticamente cualquier mensaje devuelto.

SearchTerm st =

new OrTerm(

new SubjectTerm("ADV:"),

new FromStringTerm("friend@public.com"));

Message[] msgs = folder.search(st);

Recursos

Se pueden hacer muchas más cosas con el API JavaMail que las descritas aquí. Podrás encontrarlas en las sigueintes direcciones:

JavaMail API Home

JavaBeans Activation Framework Home

javamail-interest mailing list

Sun's JavaMail FAQ

jGuru's JavaMail FAQ

Third Party Products List