Mails.idl

Go to the documentation of this file.

/**
 * @file   Mails.idl
 * @brief  Work with mails.
 *
 * @author Martin Hosna
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */

/**
 * @defgroup FOLDERS Accessing message folders
 * @{
 */
#import <Structures.idl>
#import <Certificates.idl>

module kerio {
module jsonapi {
module webmail {
module mails {

struct Email {
   string name;
   string address;
   string contactId; ///< [WRITE-ONCE]
};

typedef sequence<Email> EmailList;


struct Attachment {
   string id;        ///< origin ID of attachment or ID from upload response
   string url;       ///< [READ-ONLY] Relative URL from root of web. Eg.: /webmail/api/download/attachment/ba5767a9-7a70-4c90-a6bf-dc8dd62e259c/14/0-1-0-1/picture.jpg
   string name;      ///< [WRITE-ONCE] Filename. Can be empty if attachment is inline.
   string contentType; ///< [WRITE-ONCE]
   string contentId; ///< [WRITE-ONCE] Inline attachment parameter. URI is used in format cid:contentId in HTML parts.
   long size;        ///< [READ-ONLY]
};

/** array of mail attachment */
typedef sequence<Attachment> AttachmentList;

enum DisplayableContentType {
   ctTextPlain,
   ctTextHtml
};

struct DisplayableMimePart {
   kerio::web::KId id;     ///< [READ-ONLY] local identification, 0 = root mime part, 0-0 = sub-mime part, 0.1 = sub-mime part second item...
   DisplayableContentType contentType;
   string content;                  ///< UTF-8 encoded
};

typedef sequence<DisplayableMimePart> DisplayableMimePartList;

enum MimeHeaderType {
   mhMessageID,       ///< [READ-ONLY]
   mhInReplayTo,      ///< The contents of this field identify previous correspondence which this message answers. It contents an original 'Message-ID' value. rfc0822
   mhResentMessageID  ///< The contents of this field identify a forwarded message. It contains an original 'Message-ID' value. rfc0822
};

struct MimeHeader {
   MimeHeaderType type;
   string value;
};

typedef sequence<MimeHeader> MimeHeaderList;

struct SignInfo {
   boolean isSigned;
   boolean isValid;
   kerio::web::LocalizableMessage error;

   kerio::jsonapi::webmail::certificates::Certificate cert;
};

enum DecryptResult {
   DecryptSuccesful,
   DecryptNoKey,
   DecryptError
};

struct EncryptInfo {
   boolean isEncrypted;
   DecryptResult result;
   kerio::web::LocalizableMessage error;
};

/** Constants for composing kerio::web::SearchQuery */
module searchFields {
   const string QUICKSEARCH = "QUICKSEARCH";         ///< [SEARCHABLE] query=( ((subject LIKE $1) OR (from LIKE $1)) AND ((subject LIKE $2) OR (from LIKE $2)) ... OR (body  == $0) ); $0 - whole phrase, $x - tokens of phrase
   const string QUICKSEARCHSENT = "QUICKSEARCHSENT"; ///< [SEARCHABLE] query=( ((subject LIKE $1) OR (to LIKE $1))   AND ((subject LIKE $2) OR (to LIKE $2))   ... OR (body  == $0) ); $0 - whole phrase, $x - tokens of phrase
   const string FULLTEXT = "FULLTEXT";               ///< [SEARCHABLE] Just this field must be alone in search query with comparator 'Like'.
   const string messageId = "messageId";             ///< [SEARCHABLE]
   const string body = "body";                       ///< [SEARCHABLE]
   const string subject = "subject";                 ///< [SEARCHABLE][SORTABLE]
   const string from = "from";                       ///< [SEARCHABLE][SORTABLE]
   const string to = "to";                           ///< [SEARCHABLE][SORTABLE]
   const string cc = "cc";                           ///< [SEARCHABLE][SORTABLE]
   const string hasAttachment = "hasAttachment";     ///< [SEARCHABLE][SORTABLE]
   const string priority = "priority";               ///< [SEARCHABLE][SORTABLE]
   const string sendDate = "sendDate";               ///< [SEARCHABLE][SORTABLE]
   const string receiveDate = "receiveDate";         ///< [SORTABLE]
   const string size = "size";                       ///< [SORTABLE]
   const string modifiedDate = "modifiedDate";       ///< [SORTABLE]
   const string isFlagged = "isFlagged";             ///< [SORTABLE]
   const string isSeen = "isSeen";                   ///< [SORTABLE]
};

struct Mail {
   kerio::web::KId      id;            ///< [READ-ONLY] global identification
   kerio::web::KId      folderId;      ///< global identification
   Watermark         watermark;
   Email          from;       ///< contents of the From header
   Email          sender;        ///< contents of the Sender header. Use it for delegation. It shoudn't be the same as From header.
   EmailList         to;            ///< contents of To header
   EmailList         cc;            ///< contents of Cc header
   EmailList         bcc;        ///< contents of BCc header
   UtcDateTime       sendDate;      ///< contents of Date header (to be displayed in Sent Items). Not set for drafts.
   UtcDateTime       receiveDate;   ///< mail delivery time. Not set for drafts.
   UtcDateTime       modifiedDate;  
   EmailList         replyTo;    ///< contents of Reply-To header
   Email           notificationTo;  ///< contents of Disposition-Notification-To header

   string            subject;    ///< contents of Subject header
   PriorityType      priority;      ///< mail priority (contents of X-Priority header). Defaults to normal priority.
   long           size;       ///< mail size in bytes

   // flags ---------------------------------
   boolean isSeen;
   boolean isAnswered;
   boolean isFlagged;
   boolean isForwarded;
   boolean isJunk;
   boolean isMDNSent;      ///< rfc3503; When saving an unfinished message to any folder client MUST set $MDNSent keyword to prevent another client from sending MDN for the message.
   boolean showExternal;   ///< It means the user confirm to show external sources (eg. images). It's false by default.
   boolean requestDSN;     ///< It is true if should be requested DSN even for successful delivered message. DSN for failure is default. 
   boolean hasAttachment;  ///< [read-only]
   boolean isDraft;     ///< [read-only]
   boolean isReadOnly;      ///< [read-only]
   // ---------------------------------------

   // SMIME ---------------------------------
   SignInfo signInfo;        ///< [read-only]
   EncryptInfo encryptInfo;  ///< [read-only] 
   // ---------------------------------------

   DisplayableMimePartList  displayableParts;
   AttachmentList           attachments;
   MimeHeaderList           headers;

   boolean send;    ///< [WRITE-ONLY] Send mail, beware it invalidate ID of this mail
   boolean sign;    ///< [WRITE-ONLY] Appends a signature as attachment
   boolean encrypt; ///< [WRITE-ONLY] Encypts the email. Certificates of each recipient must be known.
};

typedef sequence<Mail> MailList;


/**
 * Mail store manager class
 */
interface Mails {

   /**
    * Get a list of e-mails.
    *
    * @param list - all found e-mails
    * @param totalItems - number of mails found if there is no limit
    * @param folderIds - list of global identifiers of folders to be listed.
    * @param query - query attributes and limits
    */
   void get(out MailList list, out long totalItems, in kerio::web::KIdList folderIds, in kerio::web::SearchQuery query);

   /**
    * Get a list of e-mails.
    *
    * @param list - all found e-mails
    * @param totalItems - number of mails found if there is no limit
    * @param folderIds - list of global identifiers of folders to be listed
    * @param query - query attributes and limits. Mind that offset is not used
    * @param id - global identifier of requested email
    */
   void getPageWithId(out MailList list, out long start, out long totalItems, in kerio::web::KIdList folderIds, in kerio::web::SearchQuery query, in kerio::web::KId id);

   /**
    * Get one particular email. All members of struct Mail are filed in response.
    *
    * @param errors - list of email that failed to obtain
    * @param result - found emails
    * @param ids - global identifiers of requested emails
    */
   void getById(out kerio::web::ErrorList errors, out MailList result, in kerio::web::KIdList ids);

   /**
    * Save e-mail to folder Templates or send and save to folder Sent Items
    *
    * @param errors - error message list
    * @param result - list of ID of crated mails.
    * @param mails - new mails.
    *
    * Errors:
    *  ErrorCodePartialSuccess - Failed to create mail but mail was successfully sent.
    *  ErrorCodeQuotaReached   - Failed to create mail. Items quota or disk size quota was reached.
     *  ErrorCodeSendingFailed  - Failed to send email and failed to create mail.
    */
   void create(out kerio::web::ErrorList errors, out CreateResultList result, in MailList mails);

   /**
    * Remove a list of mails.
    *
    * @param errors - list of mails that failed to remove
    * @param ids - list of global identifiers of mails to be removed
    */
   void remove(out kerio::web::ErrorList errors, in kerio::web::KIdList ids);

   /**
    * Set existing e-mail in folder Templates or send and save to folder Sent
    *
    * @param errors - error message list
    * @param mails - modifications of mails.
    *
    * Errors:
    *  ErrorCodePartialSuccess - Failed to move mail after update.
    *  ErrorCodeSendingFailed  - Failed to send email and failed to update mail.
    */
   void set(out kerio::web::ErrorList errors, out SetResultList result, in MailList mails);

   /**
    * Set all e-mail in folder as seen.
    *
    * @param folderId - target folder
    */
   void setAllSeen(in kerio::web::KId folderId);

   /**
    * Copy existing e-mails to folder
    *
    * @param errors - error message list
    * @param ids - list of global identifiers of mails to be copied
    * @param folder - target folder
    */
   void copy(out kerio::web::ErrorList errors, out CreateResultList result, in kerio::web::KIdList ids, in kerio::web::KId folder);

   /**
    * Move existing e-mails to folder
    *
    * @param errors - error message list
    * @param ids - list of global identifiers of e-mails to be moved
    * @param folder - target folder
    */
   void move(out kerio::web::ErrorList errors, out CreateResultList result, in kerio::web::KIdList ids, in kerio::web::KId folder);

    /**
    * Export attachments from mail and pack them into zip.
    *
    * @param fileDownload - description of output file
    * @param attachmentIds - list of global identifiers of attachments. All attachments must be from the same e-mail.
    */
    void exportAttachments(out kerio::web::Download fileDownload, in kerio::web::KIdList attachmentIds);
};

}; }; }; }; // end of namespace

/**
 * @}
 */