OKMMail

Basics

On almost methods you’ll see parameter named “mailId”. The value of this parameter can be some valid mail UUID or path.

Tip

Example of mailId:

• Using UUID -> “c52f9ea0-0d6c-45da-bae4-d72b66f42da3”;
• Using path -> “/okm:root/2937b81d-0b10-4dd0-a426-9acbd80be1c9-some subject”

About the parameter named “fldId”,  the value of this parameter can be some valid folder UUID or path or record node.

Tip

Example of fldId:

• Using UUID -> “c52f9ea0-0d6c-45da-bae4-d72b66f42da3”;
• Using path -> “/okm:root/test”

Also on all methods you’ll see parameter named “token”. When accessing application across SOAP the login process returns a token, what is used to identify the user on all the exposed methods. From default application execution context you must use “null” value what indicates to the application must use the “user session”.

Tip

On special cases you might be “promoted as Administrator” using the “administrator token”.

String systemToken = DbSessionManager.getInstance().getSystemToken();

Methods

create

Description:

Method	Return values	Description
create(String token, Mail mail)	Mail	Creates a new mail and returns as a result an object Mail.

Note

Mai accounts allowed formats:

• “\“John King\” jking@mail.com”
• “jking@mail.com”

Note

Mail path allowed is:

MSGID + “-” + sanitized(subject).

Note

MIME types values:

• Mail.MIME_TEXT for text mail format.
• Mail.MIME_HTML for html mail format.

Origin values:

• Mail.ORIGIN_MSG for .msg mail format.
• Mail.ORIGIN_EML for .eml mail format.
• Mail.ORIGIN_API for mail format created from API.
• Mail.ORIGIN_POP3 for mail imported from pop3 account.
• Mail.ORIGIN_IMAP for mail imported from imap account.

Caution

The other variables of Mail ( mail ) will not take any effect on mail creation.

• The variable path into the parameter mail, must be initializated. It indicates the folder path into OpenKM.
• Other mandatory variables:

Example:

package com.openkm;

import java.util.Arrays;
import java.util.Calendar;

import org.owasp.encoder.Encode;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            Mail mail = new Mail();

            // Mail path = msgId + escaped(subject)
            String msgId = "2937b81d-0b10-4dd0-a426-9acbd80be1c9";
            String subject = "some subject";
            String mailPath = "/okm:root/"+ msgId + "-" + escape(subject);
            mail.setPath(mailPath);

            // Other format for mail "some name <no_reply@openkm.com>"
            mail.setFrom("<no_reply@openkm.com>");
            mail.setTo((String[])Arrays.asList("anonymous@gmail.com").toArray());

            // You should set real dates
            mail.setSentDate(Calendar.getInstance());
            mail.setReceivedDate(Calendar.getInstance());
            mail.setContent("some content");
            mail.setMimeType(Mail.MIME_TEXT);
            mail.setSubject(subject);
            mail.setOrigin(Mail.ORIGIN_API);

            // Get only as an approximation of real size for these sample
            mail.setSize(mail.toString().getBytes("UTF-8").length);
            OKMMail.getInstance().create(null, mail);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static String escape(String name) {
        String ret = cleanup(name);

        // Fix XSS issues
        ret = Encode.forHtml(ret);

        return ret;
    }

    private static String cleanup(String name) {
        String ret = name.replace("/", "");
        ret = ret.replace("*", "");
        ret = ret.replaceAll("\\s+", " ").trim();
        return ret;
    }
}

getProperties

Description:

Method	Return values	Description
getProperties(String token, String mailId)	Mail	Returns the mail properties.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            Mail mail = OKMMail.getInstance().getProperties(null, "064ff51a-b815-4f48-a096-b4946876784f");
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

createAttachment

Description:

Method	Return values	Description
createAttachment(String token, String mailId, String docName, InputStream is)	Document	Add a attachment into the mail.

Example:

package com.openkm;

import java.io.FileInputStream;
import java.io.InputStream;

import org.apache.poi.util.IOUtils;

import com.openkm.api.OKMMail;
import com.openkm.bean.Document;

public class Test {
    public static void main(String[] args) {
        InputStream is = null;
        try {
            is = new FileInputStream("/home/test/sample.pdf");
            Document doc = OKMMail.getInstance().createAttachment(null, "064ff51a-b815-4f48-a096-b4946876784f", "sample.pdf", is);
            System.out.println(doc);
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
    }
}

deleteAttachment

Description:

Method	Return values	Description
deleteAttachment(String token, String mailId, String docId)	void	Delete a attachment into the mail.

Example:

package com.openkm;

import java.io.InputStream;

import org.apache.poi.util.IOUtils;

import com.openkm.api.OKMMail;

public class Test {
    public static void main(String[] args) {
        InputStream is = null;
        try {
            OKMMail.getInstance().deleteAttachment(null, "064ff51a-b815-4f48-a096-b4946876784f", "f123a950-0329-4d62-8328-0ff500fd42db");
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
    }
}

getAttachments

Description:

Method	Return values	Description
getAttachments(String token, String mailId)	List	Returns a list of all attachments of a mail.

Example:

package com.openkm;

import java.io.InputStream;

import org.apache.poi.util.IOUtils;

import com.openkm.api.OKMMail;
import com.openkm.bean.Document;

public class Test {
    public static void main(String[] args) {
        InputStream is = null;
        try {
            for (Document doc : OKMMail.getInstance().getAttachments(null, "064ff51a-b815-4f48-a096-b4946876784f")) {
                System.out.println(doc);
            }
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
    }
}

delete

Description:

Method	Return values	Description
delete(String token, String mailId)	void	Delete a mail.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Folder;

public class Test {
    public static void main(String[] args) {
        try {
            OKMMail.getInstance().delete(null, "064ff51a-b815-4f48-a096-b4946876784f");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

purge

Description:

Method	Return values	Description
purge(String token, String mailId)	void	The mail is definitely removed from the repository.

Caution

When a mail is purged, it will  only be able to be restored from a previously repository backup. The purge action removes the mail definitely from the repository.

• Usually you will purge mails into /okm:trash/userId - the personal trash user locations - but it is possible to directly purge any mail from the whole repository.

Example:

package com.openkm;

import com.openkm.api.OKMMail;

public class Test {
    public static void main(String[] args) {
        try {
            OKMMail.getInstance().purge(null, "064ff51a-b815-4f48-a096-b4946876784f");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

rename

Description:

Method	Return values	Description
rename(String token, String mailId, String newName)	Mail	Rename a mail.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Folder;

public class Test {
    public static void main(String[] args) {
        try {
            OKMMail.getInstance().rename(null, "064ff51a-b815-4f48-a096-b4946876784f", "newname");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

move

Description:

Method	Return values	Description
move(String token, String mailId, String dstId)	void	Moves mail into some folder or record

• The values of the dstId parameter should be a folder or record UUID or path.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Folder;

public class Test {
    public static void main(String[] args) {
        try {
            OKMMail.getInstance().move(null, "064ff51a-b815-4f48-a096-b4946876784f", "/okm:root/move/destination");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

copy

Description:

Method	Return values	Description
copy(String token, String mailId, String dstId)	void	Copies a mail into a folder or record.

Caution

Only the security grants are copied to destination, the metadata, keywords, etc. of the mail are not copied.

See “extendedCopy” method for this feature.

• The values of the dstId parameter should be a folder or record UUID or path.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Folder;

public class Test {
    public static void main(String[] args) {
        try {
            OKMMail.getInstance().copy(null, "064ff51a-b815-4f48-a096-b4946876784f", "/okm:root/move/destination");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

copy

Description:

Method	Return values	Description
copy(String token, String mailId, String dstId, String newName)	void	Copies a mail into a folder or record.

Caution

Only the security grants are copied to destination, the metadata, keywords, etc. of the mail are not copied.

See “extendedCopy” method for this feature.

• The values of the dstId parameter should be a folder or record UUID or path.
• When parameter newName value is null, mail will preservate the same name.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Folder;

public class Test {
    public static void main(String[] args) {
        try {
            OKMMail.getInstance().copy(null, "064ff51a-b815-4f48-a096-b4946876784f", "/okm:root/move/destination", "newname");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

extendedCopy

Description:

Method	Return values	Description
extendedCopy(String token, String mailId, String dstId, ExtendedAttributes extAttr)	void	Copies a mail with the associated data into some folder or record.

Note

By default only the binary data and the security grants, the metadata, keywords, etc. of the mail are not copyed.

Additional extended attributes parameters:

• When the category parameter is true the original values of the categories will be copied.
• When the keywords parameter is true the original values of the keywords will be copied.
• When the propertyGroups parameter is true the original values of the metadata groups will be copied.
• When the notes parameter is true the original values of the notes will be copied.
• When the wiki parameter is true the original values of the wiki will be copied.

• The values of the dstId parameter should be a folder or record UUID or path.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.ExtendedAttributes;

public class Test {
    public static void main(String[] args) {
        try {
            ExtendedAttributes extAttr = new ExtendedAttributes();
            extAttr.setKeywords(true);
            OKMMail.getInstance().extendedCopy(null, "064ff51a-b815-4f48-a096-b4946876784f","/okm:root/test", extAttr);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

extendedCopy

Description:

Method	Return values	Description
extendedCopy(String token, String mailId, String dstId, ExtendedAttributes extAttr, String newName)	void	Copies a mail with the associated data into some folder or record.

Note

By default only the binary data and the security grants, the metadata, keywords, etc. of the mail are not copyed.

Additional extended attributes parameters:

• When the category parameter is true the original values of the categories will be copied.
• When the keywords parameter is true the original values of the keywords will be copied.
• When the propertyGroups parameter is true the original values of the metadata groups will be copied.
• When the notes parameter is true the original values of the notes will be copied.
• When the wiki parameter is true the original values of the wiki will be copied.

• The values of the dstId parameter should be a folder or record UUID or path.
• When parameter newName value is null, mail will preservate the same name.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.ExtendedAttributes;

public class Test {
    public static void main(String[] args) {
        try {
            ExtendedAttributes extAttr = new ExtendedAttributes();
            extAttr.setKeywords(true);
            OKMMail.getInstance().extendedCopy(null, "064ff51a-b815-4f48-a096-b4946876784f","/okm:root/test", extAttr, "new_name");

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getChilds

Description:

Method	Return values	Description
getChilds(String token, String fldId)	List	Returns a list of all mails which their parent is mailId.

Danger

This method is deprecated in favour of getChildren method. We encourage do not using it, because on nearly future will be removed.

• The parameter mailId can be a folder or a record node.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            for (Mail mail : OKMMail.getInstance().getChilds(null, "/okm:root/test")) {
                System.out.println(mail);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getChildren

Description:

Method	Return values	Description
getChildren(String token, String fldId)	List	Returns a list of all mails which their parent is mailId.

• The parameter mailId can be a folder or a record node.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            for (Mail mail : OKMMail.getInstance().getChildren(null, "/okm:root/test")) {
                System.out.println(mail);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

isValid

Description:

Method	Return values	Description
isValid(String token, String mailId)	boolean	Returns a boolean that indicates if the node is a mail or not.

Example:

package com.openkm;

import com.openkm.api.OKMMail;

public class Test {
    public static void main(String[] args) {
        try {
            boolean valid =  OKMMail.getInstance().isValid(null, "064ff51a-b815-4f48-a096-b4946876784f");
            System.out.println(valid);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getPath

Description:

Method	Return values	Description
getPath(String token, String uuid)	String	Convert folder UUID to mail path.

Example:

package com.openkm;

import com.openkm.api.OKMMail;

public class Test {
    public static void main(String[] args) {
        try {
            String path =  OKMMail.getInstance().getPath(null, "064ff51a-b815-4f48-a096-b4946876784f");
            System.out.println(path);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendMail

Description:

Method	Return values	Description
sendMail(String token, List recipients, String subject, String body)	void	Sends a mail.

Example:

package com.openkm;

import java.util.ArrayList;
import java.util.List;

import com.openkm.api.OKMMail;

public class Test {
    public static void main(String[] args) {
        try {
            StringBuffer body = new StringBuffer();
            body.append("Test message body.");
            List<String> recipients = new ArrayList<>();
            recipients.add("some@mail.com");
            OKMMail.getInstance().sendMail(null, recipients, "Testing sending mail from OpenKM", body.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

setTitle

Description:

Method	Return values	Description
setTitle(String token, String mailId, String title)	void	Sets the mail title.

Example:

package com.openkm;

import com.openkm.api.OKMMail;

public class Test {
    public static void main(String[] args) {
        try {
            OKMMail.getInstance().setTitle(null, "064ff51a-b815-4f48-a096-b4946876784", "new title");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendMailWithAttachments

Description:

Method	Return values	Description
sendMailWithAttachments(String token, List toRecipients, String subject, String body, List docsId, String dstId)	Mail	Send mail message with attachement.

• The values of the dstId parameter should be a folder or record UUID or path. The dstId parameter indicate where the mail will be stored in the repository after is sent.
• Other parameters:

Example:

package com.openkm;

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

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            List<String> toRecipients = Arrays.asList("destination@mail.com");
            List<String> docsId = Arrays.asList("f123a950-0329-4d62-8328-0ff500fd42db","/okm:root/logo.png");
            Mail mail = OKMMail.getInstance().sendMailWithAttachments(null, toRecipients, "some subject", "some body", docsId, "/okm:root/tmp");
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendMailWithAttachments

Description:

Method	Return values	Description
sendMailWithAttachments(String token, List toRecipients, List ccRecipients, List bccRecipients, String subject,             String body, List docsId, String dstId)	Mail	Send mail message with attachement.

• The values of the dstId parameter should be a folder or record UUID or path. The dstId parameter indicate where the mail will be stored in the repository after is sent.
• Other parameters:

Example:

package com.openkm;

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

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            List<String> toRecipients = Arrays.asList("destination@mail.com");
            List<String> ccRecipients = new ArrayList<>();
            List<String> bccRecipients = new ArrayList<>();
            List<String> docsId = Arrays.asList("f123a950-0329-4d62-8328-0ff500fd42db","/okm:root/logo.png");
            Mail mail = OKMMail.getInstance().sendMailWithAttachments(null, toRecipients, ccRecipients, bccRecipients, "some subject", "some body", docsId, "/okm:root/tmp");
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendMailWithAttachments

Description:

Method	Return values	Description
sendMailWithAttachments(String token, List toRecipients, List ccRecipients, List bccRecipients,             List replyToMails, String subject, String body, List docsId, String dstId)	Mail	Send mail message with attachement.

• The values of the dstId parameter should be a folder or record UUID or path. The dstId parameter indicate where the mail will be stored in the repository after is sent.
• Other parameters:

Example:

package com.openkm;

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

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        try {
            List<String> toRecipients = Arrays.asList("destination@mail.com");
            List<String> ccRecipients = new ArrayList<>();
            List<String> bccRecipients = new ArrayList<>();
            List<String> replyToMails = new ArrayList<>();
            List<String> docsId = Arrays.asList("f123a950-0329-4d62-8328-0ff500fd42db","/okm:root/logo.png");
            Mail mail = OKMMail.getInstance().sendMailWithAttachments(null, toRecipients, ccRecipients, bccRecipients, replyToMails, "some subject", "some body", docsId, "/okm:root/tmp");
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

importEml

Description:

Method	Return values	Description
importEml(String path, String title, InputStream is)	Mail	Import a mail in EML format.

• The values of the path parameter should be a folder or record path. The path parameter indicate where the mail will be stored in the repository after is imported.

Example:

package com.openkm;

import java.io.FileInputStream;
import java.io.InputStream;

import org.apache.commons.io.IOUtils;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        InputStream is = null;
        try {
            is = new FileInputStream("/home/files/test.eml");
            Mail mail = OKMMail.getInstance().importEml("d88cff0d-903a-4c5a-82ea-8e6dbd100d65", "some title", is);
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
    }
}

importMsg

Description:

Method	Return values	Description
importMsg(String path, String title, InputStream is)	Mail	Import a mail in MSG format.

• The values of the path parameter should be a folder or record path. The path parameter indicate where the mail will be stored in the repository after is imported.

Example:

package com.openkm;

import java.io.FileInputStream;
import java.io.InputStream;

import org.apache.commons.io.IOUtils;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;

public class Test {
    public static void main(String[] args) {
        InputStream is = null;
        try {
            is = new FileInputStream("/home/files/test.msg");
            Mail mail = OKMMail.getInstance().importMsg("d88cff0d-903a-4c5a-82ea-8e6dbd100d65", "some title", is);
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
    }
}