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.

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).

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<String> 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.

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<String> 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<String> replyToAddress, List<String> ccAddress, List<String> 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<String> 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.

Method

Return values

Description

sendDocument(String fromAddress, List<String> 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<String> toAddresses, String subject, String text, List<String> 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.

Method

Return values

Description

sendDocuments(String fromAddress, List<String> toAddresses, String subject, String text, List<String> 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<String> replyToAddresses, List<String> toAddresses, List<String> ccAddresses, List<String> bccAddresses, String subject, String text, List<String> docsPath)	MimeMessage	Sends multiple OpenKM documents as attachments with full control over all address headers.

Forwarding and utilities

forwardMail

Description:

Method Return values Description

Method	Return values	Description
forwardMail(String token, String fromAddress, Collection<String> 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.

forwardMail(String token, String fromAddress, Collection<String> 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<String>	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

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.

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

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.

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

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.

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();
        }
    }
}

Table of contents [ Hide Show ]