MailUtils

MailUtils es un servicio de Spring que proporciona métodos para enviar mensajes de correo con adjuntos opcionales de documentos de OpenKM, reenviar correos almacenados y analizar direcciones de correo.

Nota

MailUtils es un bean de Spring — accédase a él vía ContextWrapper.getContext().getBean(MailUtils.class) o inyéctelo con @Autowired.

Enviar mensajes

sendMessage (un solo destinatario, sin FROM)

Descripción:

Método	Valores devueltos	Descripción
sendMessage(String toAddress, String subject, String content)	void	Envía un correo a un único destinatario usando la dirección de remitente configurada en el sistema.

• toAddress: La dirección de correo del destinatario.
• subject: El asunto del correo.
• content: El cuerpo del correo (se admite HTML).

Ejemplo:

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 (varios destinatarios, sin FROM)

Descripción:

Método	Valores devueltos	Descripción
sendMessage(Collection toAddress, String subject, String content)	void	Envía un correo a varios destinatarios usando la dirección de remitente configurada en el sistema.

Ejemplo:

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 (un solo destinatario, con FROM)

Descripción:

Método	Valores devueltos	Descripción
sendMessage(String fromAddress, String toAddress, String subject, String content)	void	Envía un correo con una dirección From explícita.

• fromAddress: La dirección de correo del remitente.
• toAddress: La dirección de correo del destinatario.
• subject: El asunto del correo.
• content: El cuerpo del correo.

Ejemplo:

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 (varios destinatarios, con FROM)

Descripción:

Método	Valores devueltos	Descripción
sendMessage(String fromAddress, List toAddress, String subject, String content)	void	Envía un correo a una lista de destinatarios con una dirección From explícita.

sendMessage (con CC y BCC)

Descripción:

Método	Valores devueltos	Descripción
sendMessage(String fromAddress, String toAddress, List replyToAddress, List ccAddress, List bccAddress, String subject, String content)	void	Envía un correo con control total sobre las cabeceras From, To, Reply-To, CC y BCC.

sendAdminMessage

Descripción:

Método	Valores devueltos	Descripción
sendAdminMessage(String subject, String content)	void	Envía un correo al usuario administrador de OpenKM. El mensaje se descarta silenciosamente y se registra un aviso en dos casos: si el usuario admin no existe, o si el usuario admin no tiene una dirección de correo configurada.

Ejemplo:

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

Enviar documentos como adjuntos

sendDocument

Descripción:

Método	Valores devueltos	Descripción
sendDocument(String fromAddress, List toAddresses, String subject, String text, String docPath)	MimeMessage	Envía un único documento de OpenKM como adjunto de correo. El documento se identifica por su ruta en el repositorio o su UUID.

• fromAddress: La dirección de correo del remitente.
• toAddresses: La lista de direcciones de correo de los destinatarios.
• subject: El asunto del correo.
• text: El cuerpo del correo.
• docPath: La ruta en el repositorio de OpenKM o el UUID del documento a adjuntar.

sendDocuments (lista de documentos)

Descripción:

Método	Valores devueltos	Descripción
sendDocuments(String fromAddress, List toAddresses, String subject, String text, List docsPath)	MimeMessage	Envía varios documentos de OpenKM como adjuntos de correo. Cada documento se identifica por su ruta en el repositorio o su UUID.

• fromAddress: La dirección de correo del remitente.
• toAddresses: La lista de direcciones de correo de los destinatarios.
• subject: El asunto del correo.
• text: El cuerpo del correo.
• docsPath: La lista de rutas en el repositorio de OpenKM o UUIDs de los documentos a adjuntar.

Ejemplo:

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 (con CC y BCC)

Descripción:

Método	Valores devueltos	Descripción
sendDocuments(String fromAddress, List replyToAddresses, List toAddresses, List ccAddresses, List bccAddresses, String subject, String text, List docsPath)	MimeMessage	Envía varios documentos de OpenKM como adjuntos con control total sobre todas las cabeceras de dirección.

Reenvío y utilidades

forwardMail

Descripción:

Método	Valores devueltos	Descripción
forwardMail(String token, String fromAddress, Collection toAddress, String message, String mailId)	MimeMessage	Reenvía un correo almacenado en OpenKM a los destinatarios indicados. Al cuerpo reenviado se le antepone el texto de mensaje proporcionado y un separador de reenvío. Al asunto se le antepone Fwd: .

• token: Token de autenticación.
• fromAddress: La dirección de correo del remitente.
• toAddress: Las direcciones de correo de los destinatarios.
• message: Texto a anteponer antes del contenido reenviado.
• mailId: La ruta o UUID en OpenKM del correo almacenado a reenviar.

parseMailList

Descripción:

Método	Valores devueltos	Descripción
parseMailList(String mails)	List	Analiza una cadena de direcciones de correo separadas por comas y devuelve una lista que contiene solo las válidas. Las entradas inválidas se ignoran silenciosamente.

• mails: Una cadena de direcciones de correo separadas por comas.

Ejemplo:

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"]

Ayudantes estáticos

getMailFileName

Descripción:

Método	Valores devueltos	Descripción
getMailFileName(Mail mail)	String	Devuelve el nombre de fichero apropiado para el correo dado: <subject>.msg para correos de origen Outlook, o <subject>.eml para el resto.

getMailMimeType

Descripción:

Método	Valores devueltos	Descripción
getMailMimeType(Mail mail)	String	Devuelve el tipo MIME para el correo dado: MIME de Outlook para correos de origen MSG, MIME de EML para el resto.

genMessageId

Descripción:

Método	Valores devueltos	Descripción
genMessageId()	String	Genera una cadena de identificador de mensaje único, incorporando el UUID del repositorio y un componente aleatorio. Se usa internamente para la cabecera de correo X-Message-Id.

Ayudantes de ruta de repositorio

getUserMailPath

Descripción:

Método	Valores devueltos	Descripción
getUserMailPath(String user)	String	Devuelve la ruta estándar en el repositorio de la bandeja de correo del usuario dado. La ruta sigue el patrón /okm:mail/{user}.

• user: El nombre de usuario cuya ruta de correo se devuelve.

getMailName

Descripción:

Método	Valores devueltos	Descripción
getMailName(String subject)	String	Genera un nombre de nodo único y seguro para el repositorio para un correo importado. El nombre se forma escapando el asunto (o usando el literal (Message without subject) si está en blanco), seguido de un guion y un sufijo aleatorio de 8 caracteres. Se usa al importar correos al repositorio para evitar colisiones de nombre.

• subject: El asunto del correo. Si es null o está vacío, se usa un marcador de posición por defecto.

Ejemplo:

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
    }
}

Ayudantes de dirección

addressToString (Address único)

Descripción:

Método	Valores devueltos	Descripción
addressToString(Address a)	String	Convierte un javax.mail.Address en una cadena de visualización. Devuelve "Name" <email> si hay un nombre personal establecido y difiere de la dirección; en caso contrario, devuelve solo la dirección de correo. Devuelve una cadena vacía si la entrada es null.

addressToString (array de Address)

Descripción:

Método	Valores devueltos	Descripción
addressToString(Address[] addresses)	String[]	Convierte un array de objetos javax.mail.Address en un array de cadenas de visualización, usando el mismo formato que la variante de dirección única. Devuelve un array vacío si la entrada es null.

addressToString (nombre y correo)

Descripción:

Método	Valores devueltos	Descripción
addressToString(String name, String email)	String	Formatea una dirección de correo a partir de un nombre para mostrar y una cadena de dirección. Devuelve "Name" <email> cuando el nombre no está vacío y es distinto de la dirección; en caso contrario, devuelve solo la dirección de correo.

• name: El nombre para mostrar. Puede ser null o estar vacío.
• email: La dirección de correo.

Creación de mensajes

saveMessage

Descripción:

Método	Valores devueltos	Descripción
saveMessage(String fromAddress, String toAddress, String subject, String content, File out)	void	Crea un mensaje de correo y lo escribe en el fichero de salida indicado en formato MIME. Útil para generar ficheros .eml de forma programática sin enviarlos.

• fromAddress: La dirección de correo del remitente.
• toAddress: La dirección de correo del destinatario.
• subject: El asunto del correo.
• content: El cuerpo del correo.
• out: El fichero de salida en el que escribir el mensaje MIME.

create

Descripción:

Método	Valores devueltos	Descripción
create(String token, Mail mail)	MimeMessage	Convierte un bean Mail de OpenKM en un javax.mail.MimeMessage, incluyendo todos los adjuntos del repositorio almacenados bajo el nodo de correo. Admite contenido de correo tanto en texto plano como en HTML. El mensaje resultante tiene las cabeceras estándar establecidas (X-Mailer, X-Message-Id, X-Host-Name).

• token: Token de autenticación usado para acceder a los adjuntos del correo en el repositorio.
• mail: El bean Mail de OpenKM a convertir.

Ejemplo:

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