Jakarta Structured Email provides extensions for the Java Jakarta Mail library for creating and parsing email messages containing structured data (structured email).
- Create and parse structured email data located in the HTML email body or in other MIME body parts
- Parse JSON-LD and Microdata
In addition, this project contains
- An IMAP account scanner which uses this library to extract structured data from messages in an email account
- A collection of example EML files generated with this library
The following examples demonstrate the creating and parsing of structured email based on JSON-LD embedded into the body of HTML emails. This particular approach is currently supported by some ISPs.
Note that there is ongoing discussion about alternative approaches of embedded structured data in emails within in the Structured Email Working Group at the IETF. See the example files documentation for more details.
The goal of this library is to support and showcase multiple possible approaches, allowing users to easily adopt an ultimately standardized approach.
To create structured email messages, simply use the generator to create a MIME message with structured data included in the HTML body via <script> tag:
import com.audriga.jakarta.sml.h2lj.model.StructuredData;
import com.audriga.jakarta.sml.extension.mime.StructuredMimeMessageWrapper;
import com.audriga.jakarta.sml.extension.mime.InlineHtmlMessageBuilder;
import jakarta.mail.MessagingException;
import java.util.ArrayList;
public class Example {
public static void main(String[] args) throws MessagingException {
// Comment email content elements
String emailSubject = "My first structured email";
String textEmailBody = "This is a test email";
String htmlEmailBody = "<html><body>This is a <b>test email</b></body></html>";
// Structured data
String jsonLd = "{\r\n \"@context\": \"http://schema.org\",\r\n \"@type\": \"EventReservation\",\r\n \"reservationId\": \"MBE12345\",\r\n \"underName\": {\r\n \"@type\": \"Person\",\r\n \"name\": \"Noah Baumbach\"\r\n },\r\n \"reservationFor\": {\r\n \"@type\": \"Event\",\r\n \"name\": \"Make Better Email 2024\",\r\n \"startDate\": \"2024-10-15\",\r\n \"organizer\": {\r\n \"@type\": \"Organization\",\r\n \"name\": \"Fastmail Pty Ltd.\",\r\n \"logo\": \"https://www.fastmail.com/assets/images/FM-Logo-RGB-IiFj8alCx1-3073.webp\"\r\n },\r\n \"location\": {\r\n \"@type\": \"Place\",\r\n \"name\": \"Isode Ltd\",\r\n \"address\": {\r\n \"@type\": \"PostalAddress\",\r\n \"streetAddress\": \"14 Castle Mews\",\r\n \"addressLocality\": \"Hampton\",\r\n \"addressRegion\": \"Greater London\",\r\n \"postalCode\": \"TW12 2NP\",\r\n \"addressCountry\": \"UK\"\r\n }\r\n }\r\n }\r\n}";
List<StructuredData> structuredDataList = new ArrayList<>();
structuredDataList.add(new StructuredData(jsonLd));
StructuredMimeMessageWrapper message = new InlineHtmlMessageBuilder()
.subject(emailSubject)
.textBody(textEmailBody)
.htmlBody(htmlEmailBody)
.structuredData(structuredDataList)
.build();
// Use the message as needed
}
}To parse structured email messages, you can use the provided classes and methods to extract structured data from the email content.
import com.audriga.jakarta.sml.extension.mime.StructuredMimeMessageWrapper;
import com.audriga.jakarta.sml.parser.StructuredEmailParser;
import com.audriga.jakarta.sml.h2lj.model.StructuredData;
import jakarta.mail.internet.MimeMessage;
public class Example {
public static void main(String[] args) throws Exception {
MimeMessage message = ... // obtain a MimeMessage instance
StructuredMimeMessageWrapper structuredMessage = new StructuredMimeParser().parseMessage(message);
for (StructuredData data : structuredMessage.getStructuredData()) {
System.out.println(data.getBody());
}
}
}For more complete examples, see the MailProcessingTest class, which demonstrates parsing and creating mails.
Ensure that the following prerequisites are in place:
- Java 8 or higher
- Apache Ant and Apache Ivy
Then, to build the project, use the following command:
ant jarBeyond the Jakarta Mail extension code, there are two further artifacts currently in this repository.
This project contains an IMAP account scanner command line tool, which can be used to find and extract structured email data from existing email accounts. See the IMAP account scanner documentation for details.
The folder test/resources/eml contains several example files generated with this library. Refer to the example files documentation for more information.
Part of the source code of this project can be built as a separate JAR. This can be used to extract structured data from HTML input. It is called Html2JSONLD (Java). See the H2LJ documentation for details.
Contributions are welcome! Please open new issues or pull requests on GitHub.
This project is licensed under the MIT License. See the LICENSE file for details.
This project was partially funded through the NGI0 Core Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101092990. Thank you!
See also Structured Email for Roundcube.