MailUtils

MailUtils is a Spring service that provides methods for sending email messages with optional OpenKM document attachments, forwarding stored mails, and parsing mail addresses.

Note

MailUtils is a Spring bean — access it via ContextWrapper.getContext().getBean(MailUtils.class) or inject it with @Autowired.

Sending messages

sendMessage (single recipient, no FROM)

Description:

Method	Return values	Description
sendMessage(String toAddress, String subject, String content)	void	Sends an email to a single recipient using the system-configured sender address.

• toAddress: The recipient email address.
• subject: The email subject.
• content: The email body (HTML supported).

Example:

package com.openkm;

import com.openkm.util.ContextWrapper;
import com.openkm.util.MailUtils;

public class Test {

    public static void main(String[] args) {
        try {
            MailUtils mailUtils = ContextWrapper.getContext().getBean(MailUtils.class);
            mailUtils.sendMessage("user@example.com", "Hello", "This is the message body.");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendMessage (multiple recipients, no FROM)

Description:

Method	Return values	Description
sendMessage(Collection toAddress, String subject, String content)	void	Sends an email to multiple recipients using the system-configured sender address.

Example:

import java.util.Arrays;
import com.openkm.util.ContextWrapper;
import com.openkm.util.MailUtils;

MailUtils mailUtils = ContextWrapper.getContext().getBean(MailUtils.class);
mailUtils.sendMessage(Arrays.asList("user1@example.com", "user2@example.com"), "Hello", "Message body.");

sendMessage (single recipient, with FROM)

Description:

Method	Return values	Description
sendMessage(String fromAddress, String toAddress, String subject, String content)	void	Sends an email with an explicit From address.

• fromAddress: The sender email address.
• toAddress: The recipient email address.
• subject: The email subject.
• content: The email body.

Example:

package com.openkm;

import com.openkm.util.ContextWrapper;
import com.openkm.util.MailUtils;

public class Test {

    public static void main(String[] args) {
        try {
            MailUtils mailUtils = ContextWrapper.getContext().getBean(MailUtils.class);
            mailUtils.sendMessage("noreply@openkm.com", "user@example.com", "Hello", "Message body.");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendMessage (multiple recipients, with FROM)

Description:

Method	Return values	Description
sendMessage(String fromAddress, List toAddress, String subject, String content)	void	Sends an email to a list of recipients with an explicit From address.

sendMessage (with CC and BCC)

Description:

Method	Return values	Description
sendMessage(String fromAddress, String toAddress, List replyToAddress, List ccAddress, List bccAddress, String subject, String content)	void	Sends an email with full control over From, To, Reply-To, CC, and BCC headers.

sendAdminMessage

Description:

Method	Return values	Description
sendAdminMessage(String subject, String content)	void	Sends an email to the OpenKM administrator user. The message is silently dropped and a warning is logged in two cases: if the admin user does not exist, or if the admin user has no email address configured.

Example:

MailUtils mailUtils = ContextWrapper.getContext().getBean(MailUtils.class);
mailUtils.sendAdminMessage("Low disk space", "Free space below 10%.");

Sending documents as attachments

sendDocument

Description:

Method	Return values	Description
sendDocument(String fromAddress, List toAddresses, String subject, String text, String docPath)	MimeMessage	Sends a single OpenKM document as an email attachment. The document is identified by its repository path or UUID.

• fromAddress: The sender email address.
• toAddresses: The list of recipient email addresses.
• subject: The email subject.
• text: The email body.
• docPath: The OpenKM repository path or UUID of the document to attach.

sendDocuments (list of documents)

Description:

Method	Return values	Description
sendDocuments(String fromAddress, List toAddresses, String subject, String text, List docsPath)	MimeMessage	Sends multiple OpenKM documents as email attachments. Each document is identified by its repository path or UUID.

• fromAddress: The sender email address.
• toAddresses: The list of recipient email addresses.
• subject: The email subject.
• text: The email body.
• docsPath: The list of OpenKM repository paths or UUIDs of documents to attach.

Example:

package com.openkm;

import com.openkm.util.ContextWrapper;
import com.openkm.util.MailUtils;

import java.util.Arrays;
import java.util.List;

public class Test {

    public static void main(String[] args) {
        try {
            MailUtils mailUtils = ContextWrapper.getContext().getBean(MailUtils.class);
            List<String> recipients = Arrays.asList("user@example.com");
            List<String> docs = Arrays.asList(
                "/okm:root/documents/report.pdf",
                "/okm:root/documents/annex.pdf"
            );
            mailUtils.sendDocuments("noreply@openkm.com", recipients, "Monthly report", "Please find the reports attached.", docs);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendDocuments (with CC and BCC)

Description:

Method	Return values	Description
sendDocuments(String fromAddress, List replyToAddresses, List toAddresses, List ccAddresses, List bccAddresses, String subject, String text, List docsPath)	MimeMessage	Sends multiple OpenKM documents as attachments with full control over all address headers.

Forwarding and utilities

forwardMail

Description:

Method	Return values	Description
forwardMail(String token, String fromAddress, Collection toAddress, String message, String mailId)	MimeMessage	Forwards a stored OpenKM mail to the given recipients. The forwarded body is prepended with the supplied message text and a forwarding separator. The subject is prefixed with Fwd: .

• token: Authentication token.
• fromAddress: The sender email address.
• toAddress: The recipient email addresses.
• message: Text to prepend before the forwarded content.
• mailId: The OpenKM path or UUID of the stored mail to forward.

parseMailList

Description:

Method	Return values	Description
parseMailList(String mails)	List	Parses a comma-separated string of email addresses and returns a list containing only the valid ones. Invalid entries are silently ignored.

• mails: A comma-separated string of email addresses.

Example:

MailUtils mailUtils = ContextWrapper.getContext().getBean(MailUtils.class);
List<String> addresses = mailUtils.parseMailList("user@example.com, invalid-email, other@example.com");
System.out.println(addresses); // ["user@example.com", "other@example.com"]

Static helpers

getMailFileName

Description:

Method	Return values	Description
getMailFileName(Mail mail)	String	Returns the appropriate file name for the given mail: <subject>.msg for Outlook origin mails, or <subject>.eml for others.

getMailMimeType

Description:

Method	Return values	Description
getMailMimeType(Mail mail)	String	Returns the MIME type for the given mail: Outlook MIME for MSG origin mails, EML MIME for others.

genMessageId

Description:

Method	Return values	Description
genMessageId()	String	Generates a unique message identifier string incorporating the repository UUID and a random component. Used internally for the X-Message-Id mail header.

Repository path helpers

getUserMailPath

Description:

Method	Return values	Description
getUserMailPath(String user)	String	Returns the standard mail inbox repository path for the given user. The path follows the pattern /okm:mail/{user}.

• user: The username whose mail path to return.

getMailName

Description:

Method	Return values	Description
getMailName(String subject)	String	Generates a unique, repository-safe node name for an imported mail. The name is formed by escaping the subject (or using the literal (Message without subject) if blank), followed by a hyphen and an 8-character random suffix. Used when importing mails into the repository to avoid name collisions.

• subject: The mail subject. If null or empty, a default placeholder is used.

Example:

package com.openkm;

import com.openkm.util.ContextWrapper;
import com.openkm.util.MailUtils;

public class Test {

    public static void main(String[] args) {
        MailUtils mailUtils = ContextWrapper.getContext().getBean(MailUtils.class);
        System.out.println(mailUtils.getUserMailPath("jsmith")); // /okm:mail/jsmith
        System.out.println(mailUtils.getMailName("Invoice Q1 2024")); // Invoice Q1 2024-3f8a1b2c
        System.out.println(mailUtils.getMailName(null)); // (Message without subject)-3f8a1b2c
    }
}

Address helpers

addressToString (single Address)

Description:

Method	Return values	Description
addressToString(Address a)	String	Converts a javax.mail.Address to a display string. Returns "Name" <email> if a personal name is set and differs from the address, otherwise returns the bare email address. Returns an empty string if the input is null.

addressToString (Address array)

Description:

Method	Return values	Description
addressToString(Address[] addresses)	String[]	Converts an array of javax.mail.Address objects to an array of display strings using the same formatting as the single-address overload. Returns an empty array if the input is null.

addressToString (name and email)

Description:

Method	Return values	Description
addressToString(String name, String email)	String	Formats an email address from a display name and an address string. Returns "Name" <email> when the name is non-empty and different from the address, otherwise returns just the email address.

• name: The display name. May be null or empty.
• email: The email address.

Message creation

saveMessage

Description:

Method	Return values	Description
saveMessage(String fromAddress, String toAddress, String subject, String content, File out)	void	Creates an email message and writes it to the given output file in MIME format. Useful for generating .eml files programmatically without sending them.

• fromAddress: The sender email address.
• toAddress: The recipient email address.
• subject: The email subject.
• content: The email body.
• out: The output file to write the MIME message to.

create

Description:

Method	Return values	Description
create(String token, Mail mail)	MimeMessage	Converts an OpenKM Mail bean into a javax.mail.MimeMessage, including all repository attachments stored under the mail node. Supports both plain-text and HTML mail content. The resulting message has standard headers set (X-Mailer, X-Message-Id, X-Host-Name).

• token: Authentication token used to access the mail’s attachments in the repository.
• mail: The OpenKM Mail bean to convert.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;
import com.openkm.util.ContextWrapper;
import com.openkm.util.MailUtils;

import jakarta.mail.internet.MimeMessage;

public class Test {

    public static void main(String[] args) {
        try {
            MailUtils mailUtils = ContextWrapper.getContext().getBean(MailUtils.class);
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);

            // Convert a stored mail to MimeMessage (e.g. to forward or save it)
            Mail mail = okmMail.getProperties(null, "/okm:mail/jsmith/inbox/invoice.eml");
            MimeMessage msg = mailUtils.create(null, mail);
            System.out.println("Subject: " + msg.getSubject());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}