Use of the mail service is done via session. You need to configure a session factory that will be able to find the correct server parameter to connect to. Then, the session can use the mail server. The simplest scenario is to have mails sent and received using the credential of one user (see property fetcher for more complex use).

To pass the server parameter in your extension point, use a simple properties fetcher. For a server using TLS connection with SMTP and IMAP, a configuration could look like:

<extension target="org.nuxeo.ecm.platform.MailService"
   point="sessionFactory">
   <sessionFactory name="mysession" fetcherName="simple">
     <properties>
       <property name="mail.store.protocol">imap</property>
       <property name="mail.transport.protocol">smtp</property>
       <property name="mail.smtp.port">587</property>
       <property name="mail.host">mail.mycompany.com</property>
       <property name="mail.smtp.host">mail.mycompany.com</property>
       <property name="mail.imap.starttls.enable">true</property>
       <property name="mail.imap.ssl.protocols">TLS</property>
       <property name="mail.smtp.ssl.protocols">TLS</property>
       <property name="mail.user">[email protected]</property>
       <property name="mail.from">[email protected]</property>
       <property name="mail.imap.port">143</property>
       <property name="password">myuserpassword</property>
       <property name="user">[email protected]</property>
     </properties>
   </sessionFactory>
 </extension>

With such a configuration you can send mails using the mail service, passing the text of the mail as a String.

MailService mailService = Framework.getService(MailService.class);
mailService.sendMail("My interesting mail.", "The subject of the mail",
        "mysession", new Address {internetAddress});

To process mails in mail folders, you need to create a pipe and add actions to it. Each action in the pipe will be applied to each mail in the folder. A typical pipe will include action to set the delete flag so the mail is deleted when the pipe exits, transforms the mail, stores it, and maybe answers it. For all those actions to communicate with each other, you can pass objects into the context. Context is passed from action to action.

The package org.nuxeo.ecm.platform.mail.action contains a set of Action classes you can use or extend. Note that some actions expect objects to be in the map.

A MessageAction is an action done on a message:

public interface MessageAction {
   boolean execute(ExecutionContext context) throws Exception;
   void reset(ExecutionContext context) throws Exception;
}

Message message = context.getMessage();
String infoFromPreviousAction = context.get("info.from.previous.action");
context.put("info.for.next.action", "don't save this message");

If the returned value of an action is false, then the processing of this message is stopped and the next message will be processed.

The MailBoxAction enables using those service in a simple way, a typical use would be:

MailBoxActions mba = mailService.getMailBoxActions("mySimpleFactory", "INBOX");
mba.addAction(new ConvertToDocumentModelAction());
mba.addAction(new StoreDocumentModelAction());
mba.addAction(new SendMailReplyAction());
mba.execute();