Utilizando a API Commons-email para enviar E-mails

Introdução

Recentemente, me deparei com a situação em que precisava enviar e-mails de forma automática a partir de minha aplicação web.

A partir daí encontrei, além da já conhecida API JavaMail, uma outra API do projeto Jakarta Apache, o Commons-email.

O Commons-email foi desenvolvido como uma camada mais abstraída da API JavaMail (J2EE-API) o que a tornou mais simples e robusta.

Através do commons-email, é possível enviar e-mails simples, com textos puros, em formato HTML e também e-mail com anexos conforme mostraremos neste tutorial.

Observação: Este tutorial é inteiramente referente à documentação disponível em:

http://jakarta.apache.org/commons/email/userguide.html

Obtendo o commons-email

O commons-email pode ser baixado a partir do endereço:

http://jakarta.apache.org/site/downloads/downloads_commons-email.cgi

Após descompactar o arquivo commons-email-1.0.zip, o arquivo commons-email-1.0.jar deve ser referenciado na pasta lib da sua aplicação.

A API commons-email

·   SimpleEmail – Esta classe é usada para enviar e-mails simples.

·   MultiPartEmail - Esta classe é usada emitir mensagens multipart. Isto permite uma mensagem de texto com anexos.

·   HtmlEmail – Esta classe envia emails formatados como HTML.

·   EmailAttachment – Esta classe é usada para se criar os anexos do email.

Enviando um e-mail simples

Nosso primeiro exemplo criará uma mensagem simples de e-mail para “John Doe” e a enviará através do seu servidor de e-mail.

SimpleEmail email = new SimpleEmail();

email.setHostName("mail.myserver.com"); // o servidor SMTP para envio do e-mail

email.addTo("jdoe@somewhere.org", "John Doe"); //destinatário

email.setFrom("me@apache.org", "Me"); // remetente

email.setSubject("Mensagem de Teste"); // assunto do e-mail

email.setMsg("Teste de Email utilizando commons-email"); //conteudo do e-mail

email.send(); //envia o e-mail

A chamada ao setHostName(“mail.myserver.com”) ajusta o endereço do servidor smtp que será usado emitir a mensagem. Se esta opção não for ajustada, a propriedade “mail.host” do sistema será usada.

Enviando e-mails com anexo 
Para enviar e-mails com anexos deve-se utilizar a classe MultiPartEmail. Essa classe trabalha da mesma forma que a classe SimpleEmail, exceto pela adição do método attach() que será utilizada para adicionar os anexos ao e-mail. Não há limite para o número de anexos (na verdade o servidor de e-mail utilizado que irá impor o limite de anexos).

A maneira mais simples de adicionar um anexo é utilizar a classe EmailAttachment que encapsulará o anexo. 

No exemplo abaixo, será criado e adicionado como anexo ao e-mail anteriormente criado, uma figura.

// cria o anexo.

EmailAttachment attachment = new EmailAttachment();

attachment.setPath("mypictures/john.jpg"); //caminho da imagem

attachment.setDisposition(EmailAttachment.ATTACHMENT);

attachment.setDescription("Picture of John");

attachment.setName("John");

// Cria a mensagem de e-mail.

MultiPartEmail email = new MultiPartEmail();

email.setHostName("mail.myserver.com"); // o servidor SMTP para envio do e-mail

email.addTo("jdoe@somewhere.org", "John Doe"); //destinatario

email.setFrom("me@apache.org", "Me"); //remetente

email.setSubject("Mensagem de teste com anexo"); //Assunto

email.setMsg("Aqui está a Imagem anexada ao e-mail"); //conteudo do e-mail

email.attach(attachment); // adiciona o anexo à mensagem

email.send();// envia o e-mail

Você pode usar a classe EmailAttachment para adicionar anexos remotos através de uma URL válida para arquivos que não estejam localizados localmente. Quando a mensagem é enviada é feito o download e o anexo do arquivo automaticamente. 

O código abaixo mostra como enviar um arquivo localizado remotamente, como anexo.

// cria o anexo.

EmailAttachment attachment = new EmailAttachment();

attachment.setURL(new URL("http://www.apache.org/images/asf_logo_wide.gif"));//endereço remoto

attachment.setDisposition(EmailAttachment.ATTACHMENT);

attachment.setDescription("Apache logo");

attachment.setName("Apache logo");

// Cria a mensagem de e-mail

MultiPartEmail email = new MultiPartEmail();

email.setHostName("mail.myserver.com");

email.addTo("jdoe@somewhere.org", "John Doe");

email.setFrom("me@apache.org", "Me");

email.setSubject("O logoTipo");

email.setMsg("Aqui está o logoTipo da Apache");

email.attach(attachment); // adiciona o anexo

email.send();// envia o e-mail

Enviando e-mails no formato HTML 
O envio de e-mail no formato HTML pode ser feito com a classe HtmlEmail. O funcionamento dessa classe é idêntica ao da classe MultiPartEmail, a não ser pelo fato de possuir um método adicional que configura o content-type da mensagem para text/html.  Além disso, a classe permite alternativamente adicionar o conteúdo da mensagem como texto plano, nos casos onde não é suportado e-mails no formato HTML. 

O código abaixo mostra como enviar um e-mail no formato HTML, incluindo uma imagem no corpo da mensagem.

// Cria o e-mail

HtmlEmail email = new HtmlEmail();

email.setHostName("mail.myserver.com");

email.addTo("jdoe@somewhere.org", "John Doe");

email.setFrom("me@apache.org", "Me");

email.setSubject("Teste de e-mail em formato HTML");

// adiciona uma imagem ao corpo da mensagem e retorna seu id

URL url = new URL("http://www.apache.org/images/asf_logo_wide.gif");

String cid = email.embed(url, "Apache logo");

// configura a mensagem para o formato HTML

email.setHtmlMsg("<html>The apache logo - <img src=\"cid:"+cid+"\"></html>");

// configure uma mensagem alternativa caso o servidor não suporte HTML

email.setTextMsg("Seu servidor de e-mail não suporta mensagem HTML");

// envia o e-mail

email.send();

Primeiramente, observe que a chamada a embed() retorna uma String. Esta String é um identificador aleatório gerado que deve ser usado para referenciar a imagem na Tag da imagem.

URL url = new URL("http://www.apache.org/images/asf_logo_wide.gif");

String cid = email.embed(url, "Apache logo");

email.setHtmlMsg("<html>The apache logo - <img src=\"cid:"+cid+"\"></html>");

Segundo, não havia nenhuma chamada ao setMsg() neste exemplo. O método está ainda disponível na classe HtmlEmail mas não deve ser usado se você estiver usando imagens inline (Como no exemplo). Contudo, o setHtmlMsg() e os métodos do setTextMsg () foram usados.

Debug

A API JavaMail suporta uma opção de debug que pode ser muito útil se você tiver problemas para fazer funcionar. Você pode ativar o debug em qualquer uma das classes de email chamando o setDebug (true). A saída do debug será escrita a System.out.

Autenticação 
Se o seu servidor de envio de e-mails (servidor SMTP) exige autenticação, isso pode ser feito através do método setAuthentication(userName,password) antes do envio do e-mail. 

Você pode executar um método mais complexo de autenticação criando uma subclasse do objeto javax.mail.Authenticator.

Para isso você precisa Sobrescrever o método getPasswordAuthentication() onde você configurará as informações do usuário. Para fazer uso de seu Authenticator use o metodo Email.setAuthenticator();