Apache Sling Commons Messaging Mail

This module is part of the Apache Sling project.

This module provides a simple layer on top of Jakarta Mail 2.0 (package jakarta.mail) including a message builder and a service to send mails via SMTPS.

• Mail Service: sends MIME messages
• Message Builder: builds plain text and HTML messages with attachments and inline images
• Message ID Provider: allows overwriting default message IDs by custom ones

Examples

Configuration

MailService

Example factory configuration (SimpleMailServiceConfiguration) for SimpleMailService:

{
  "mail.smtps.from": "envelope-from@example.org",
  "mail.smtps.host": "smtp.example.org",
  "mail.smtps.port": 465,
  "username": "SMTP-USERNAME-PLAIN",
  "password": "SMTP-PASSWORD-ENCRYPTED",
  "messageIdProvider.target": "(names=hostname)"
}

Optional MessageIdProvider

Example factory configuration (SimpleMessageIdProviderConfiguration) for optional SimpleMessageIdProvider:

{
  "names": [
    "hostname"
  ],
  "host": "author.cms.example.org"
}

Usage

Create a multipart MIME message with an attachment (filename: song.flac) where the HTML part contains an inline image (cid: ska) and send it:

    @Reference
    MailService mailService;

    String subject = "Rudy, A Message to You";
    String text = "Stop your messing around\nBetter think of your future\nTime you straighten right out\nCreating problems in town\n…";
    String html = […];
    byte[] attachment = […];
    byte[] inline = […];

    MimeMessage message = mailService.getMessageBuilder()
        .from("dandy.livingstone@kingston.jamaica.example.net", "Dandy Livingstone")
        .to("the.specials@coventry.england.example.net", "The Specials")
        .replyTo("rocksteady@jamaica.example.net");
        .subject(subject)
        .text(text)
        .html(html)
        .attachment(attachment, "audio/flac", "song.flac")
        .inline(inline, "image/png", "ska")
        .build();

    mailService.sendMessage(message);

Dependencies

• Sling Commons Messaging (API)
• Sling Commons Crypto (for decrypting encrypted SMTP passwords)
• Sling Commons Threads
• Jakarta Mail 2.0 and Jakarta Activation 2.0 (OSGified, e.g. org.apache.servicemix.specs.activation-api-2.0.1)

Integration Tests

Integration tests require a running SMTP server. By default a GreenMail server is started.

An external SMTP server for validating messages with real mail clients can be used by setting required properties:

mvn clean install\
  -Dsling.test.mail.smtps.server.external=true\
  -Dsling.test.mail.smtps.ssl.checkserveridentity=true\
  -Dsling.test.mail.smtps.from=envelope-from@example.org\
  -Dsling.test.mail.smtps.host=localhost\
  -Dsling.test.mail.smtps.port=465\
  -Dsling.test.mail.smtps.username=username\
  -Dsling.test.mail.smtps.password=password\
  -Dsling.test.mail.from.address=from@example.org\
  -Dsling.test.mail.from.name=From\ Sender\
  -Dsling.test.mail.to.address=to@example.org\
  -Dsling.test.mail.to.name=To\ Recipient\
  -Dsling.test.mail.replyTo.address=replyto@example.org\
  -Dsling.test.mail.replyTo.name=Reply\ To