Package com.jalios.jcms.mail

Class MailManager

  • All Implemented Interfaces:
    JPropertiesListener
    public class MailManager
extends java.lang.Object
implements JPropertiesListener
    Provides convenient methods to manage Mail (send and receive email)

    • Field Detail

      • MAIL_ACCOUNT_PROP_PREFIX

        public static final java.lang.String MAIL_ACCOUNT_PROP_PREFIX
        See Also:
        Constant Field Values

      • MAIL_ABSOLUTE_URL_CONVERSION_REGEX

        public static final java.lang.String MAIL_ABSOLUTE_URL_CONVERSION_REGEX
        See Also:
        Constant Field Values

      • MAIL_ADD_IMAGES_AUTHKEY_REGEX

        public static final java.lang.String MAIL_ADD_IMAGES_AUTHKEY_REGEX
        See Also:
        Constant Field Values

      • MAIL_SRCSET_REGEX

        public static final java.lang.String MAIL_SRCSET_REGEX
        See Also:
        Constant Field Values

      • MAIL_INCOMING_ENABLED

        public static final java.lang.String MAIL_INCOMING_ENABLED
        See Also:
        Constant Field Values

      • MAIL_PROVIDER_PREFIX

        public static final java.lang.String MAIL_PROVIDER_PREFIX
        See Also:
        Constant Field Values

      • MAIL_SEND_PROVIDER_NAME

        public static final java.lang.String MAIL_SEND_PROVIDER_NAME
        See Also:
        Constant Field Values

      • SET_AUTO_GENERATED

        public static final java.lang.String SET_AUTO_GENERATED
        Name of both JCMS property and context map attribute defining a MailMessage behavior.

        The value is a boolean which defines if MailMessage should be sent using the header Auto-Submitted: auto-generated (RFC 3834 ยง5.2) to indicate mail was automatically generated.

        Value can be specified :

        • in JCMS properties (its default value is true)
        • in context map attribute of MailMessage.send(HashMap) method (this value overrides the behavior of JCMS property)
        Default JCMS behavior (following fix JCMS-9853) is to indicate mail was automatically generated.
        Since:
        JCMS-9853
        See Also:
        Constant Field Values

      • SEND_WITH_SITE_EMAIL

        public static final java.lang.String SEND_WITH_SITE_EMAIL
        Name of both JCMS property and context map attribute defining a MailMessage behavior.

        The value is a boolean which defines if MailMessage should be sent using the Member name and e-mail, or using the user name but with the site e-mail address.
        If set to true, mail are sent using the site default email address, and the original Member is used in the ReplyTo header.
        If set to false, mail are sent using original member email address.

        Value can be specified :

        • in JCMS properties (its default value is true)
        • in context map attribute of MailMessage.send(HashMap) method (this value overrides the behavior of JCMS property)
        Default JCMS behavior (following fix JCMS-3740) is to send mail using the site email address.
        Since:
        JCMS-3740
        See Also:
        Constant Field Values

      • mailHeaderMap

        protected static java.util.Map<java.lang.String,​java.lang.String> mailHeaderMap

      • ADD_IMAGES_AUTHKEY

        public static final java.lang.String ADD_IMAGES_AUTHKEY
        Name of both JCMS property and context map attribute defining a MailMessage behavior.

        The value is a boolean which defines if MailMessage should be modified to add authentication key to all images source URL to allow images to mailer without any authentication.
        If set to true, authkey are added to URL.
        If set to false, default behavior is applied.

        Value can be specified :

        • in JCMS properties (its default value is true)
        • in context map attribute of MailMessage.send(HashMap) method (this value overrides the behavior of JCMS property)
        Default JCMS behavior is to add autkey only when site is private.
        Since:
        JCMS-2677
        See Also:
        Constant Field Values

    • Method Detail

      • addDefaultHeaders

        public static void addDefaultHeaders​(MailMessage msg,
                                     java.util.HashMap<java.lang.String,​java.lang.Object> ctxt)
        An internal method used to add default mail headers configured in properties in the message.

        Mail headers are read from properties mail.header.{Header-Name}: {Header-Value}

        Parameters:
        msg - the MailMessage to modify
        ctxt - the context map attribute of MailMessage.send(HashMap), MUST NOT be null
        Since:
        jcms-10.0.7 / JCMS-9854

      • getInstance

        public static MailManager getInstance()

      • propertiesChange

        public void propertiesChange​(JProperties properties)
        Description copied from interface: JPropertiesListener
        Invoked after properties have been modified in JCMS and save on disk.

        You cannot alter the value received in parameters.

        Note that properties parameter may be null, a limited set of site properties, or all site properties.

        To check that a property has been modified, reload the "current" property instead using channel.getProperties or channel.getProperty.

        Specified by:
        propertiesChange in interface JPropertiesListener
        Parameters:
        properties - the properties which have been submitted to change

      • isIncomingMailEnabled

        public boolean isIncomingMailEnabled()

      • isEnabled

        public boolean isEnabled()

      • getSrcLinkPattern

        protected java.util.regex.Pattern getSrcLinkPattern()

      • getUrlPattern

        protected java.util.regex.Pattern getUrlPattern()

      • getSrcsetPattern

        protected java.util.regex.Pattern getSrcsetPattern()

      • isSendWithSiteEmail

        protected boolean isSendWithSiteEmail()

      • setAutoGeneratedHeader

        protected boolean setAutoGeneratedHeader()

      • getProviderClassMap

        public java.util.Map<java.lang.String,​java.lang.Class<?>> getProviderClassMap()

      • sendMessage

        public boolean sendMessage​(MailMessage msg,
                           boolean catchMailErrors)
        Send 1 Mail. Do not throw exceptions. Warning: This method only fail and return a list of error when a Message could not be build or sent, but it DOES not failed and return anything when the connection to the remote service cannot be established.
        Parameters:
        msg - the MailMessage to send
        catchMailErrors - set to true to prevent this method to throw exception when sending messages
        Returns:
        true is the mail has been delivered (false if exceptions thrown during sending of mails)

      • sendMessages

        public java.util.List<MailMessage> sendMessages​(java.util.List<MailMessage> msgList,
                                                boolean catchMailErrors)
        Send n Mails. Do not throw exceptions. Warning: This method only fail and return a list of error when a Message could not be build or sent, but it DOES not failed and return anything when the connection to the remote service cannot be established.
        Parameters:
        msgList - the list of MailMessage to send
        catchMailErrors - set to true to prevent this method to throw exception when sending messages
        Returns:
        a list of recipient String that throws exceptions during sending of mails

      • sendMessages

        public java.util.List<MailMessage> sendMessages​(MailMessage[] msgs,
                                                boolean catchMailErrors)
        Send n Mails. Do not throw exceptions. Warning: This method only fail and return a list of error when a Message could not be build or sent, but it DOES not failed and return anything when the connection to the remote service cannot be established.
        Parameters:
        msgs - the array of MailMessage to send
        catchMailErrors - set to true to prevent this method to throw exception when sending messages
        Returns:
        a list of recipient String that throws exceptions during sending of mails

      • getDBMailMessageSet

        public java.util.Set<java.lang.Object> getDBMailMessageSet​(java.lang.String[] ids)
        Returns a Collection of MailMessage or Message-ID (if not found)
        Parameters:
        ids - a list of Message-ID
        Returns:
        Collection of MailMessage or Message-ID

      • getDBMailMessageCount

        public int getDBMailMessageCount()
        Returns the count of DBMailMessage
        Returns:
        int the DBMailMessageCount

      • getDBMailMessageCount

        public int getDBMailMessageCount​(java.lang.String account)
        Returns the count of DBMailMessage for given account
        Parameters:
        account - the account name
        Returns:
        int the DBMailMessageCount

      • getDBMailMessage

        public MailMessage getDBMailMessage​(javax.mail.Message msg)
        Returns the DBMailMessage for the given Message
        Parameters:
        msg - a javax.mail.Message
        Returns:
        a DBMailMessage stored in db

      • getDBMailMessage

        public MailMessage getDBMailMessage​(java.lang.String msgid)
        Returns the DBMailMessage for the given Message Id
        Parameters:
        msgid - the message id
        Returns:
        a DBMailMessage stored in db

      • getDBMailMessageReplies

        public java.util.Collection<? extends MailMessage> getDBMailMessageReplies​(java.lang.String msgid)
        Returns the DBMailMessage for the given Message Id
        Parameters:
        msgid - the message id
        Returns:
        a DBMailMessage stored in db

      • getDBMailMessageThread

        public java.util.Collection<? extends MailMessage> getDBMailMessageThread​(java.lang.String thread)

      • createDBMailMessage

        public MailMessage createDBMailMessage​(javax.mail.Message msg)
        Build a DBMessage from a Message and save in into the DB
        Parameters:
        msg - a javax.mail.Message
        Returns:
        MailMessage instanciate or null if exception appends

      • saveDBMailMessage

        public void saveDBMailMessage​(MailMessage mail,
                              java.util.Map<java.lang.String,​java.lang.Object> context)
        Build a DBMessage from a Message and save in into the DB
        Parameters:
        mail - the MailMessage
        context - the contextual map

      • writeEml

        @Deprecated
public java.io.File writeEml​(javax.mail.Message msg)
        Deprecated.
        The method is deprecated, See MessageUtil.writeEml to the new implementation
        Write a Message to a file
        Parameters:
        msg - the Message
        Returns:
        the File with the message saved in

      • getMailFetcher

        public MailFetcher getMailFetcher()
        Returns the MailFetcher
        Returns:
        MailFetcher

      • getMessageIdQuietly

        public java.lang.String getMessageIdQuietly​(javax.mail.Message msg)
        Convenient method that delegate to MailFetcher method
        Parameters:
        msg - the javax.mail.Message
        Returns:
        String the message Id or null
        See Also:
        MessageUtil.getMessageIdQuietly(Message)

      • improveMailMessageConformity

        public static void improveMailMessageConformity​(MailMessage msg,
                                                java.util.HashMap<java.lang.String,​java.lang.Object> ctxt)
        Improve the specified MailMessage conformity with mail sending best practices (if enabled).

        Implementation details

        If following criterias are met :

        • property mail.send-with-site-email is set to true
        • attribute mail.send-with-site-email is either undefined or set to true in the context map (this attribute overrides behavior of JCMS property)
        • MailMessage.getFromMember() is not null
        • MailMessage.getReplyToMember() is null or is the same member specified in MailMessage.getFromMember()
        The MailMessage is rewriten to use the site e-mail address in the From header :
        • the FromMember is used as the ReplyToMember
        • the From header as "{Member Full Name} ({Site Name}) <{default-email or admin-email}>"
        • the FromMember is removed
        Parameters:
        msg - the MailMessage to modify if criterias are met
        ctxt - the context map attribute of MailMessage.send(HashMap), MUST NOT be null
        Since:
        JCMS-3740, updated with JCMS-9853

      • addAuthKeyToImagesSrc

        public static void addAuthKeyToImagesSrc​(MailMessage msg,
                                         java.util.HashMap<java.lang.String,​java.lang.Object> ctxt)
        Rewrite the HTML content of the specified MailMessage to add an authentication key to all images URL.

        It allows mailer to access images without any authentication.

        Default behavior is to perform this operation only when the site is private.
        Since improvement JCMS-2677, the operation can be forced if :

        • property mail.add-images-authkey is set to true
        • attribute mail.add-images-authkey is set to true in the context map (this attribute overrides behavior of JCMS property)

        Authkeys are added only if the message is sent on one and only one Member.

        Parameters:
        msg - the MailMessage to modify if criterias are met
        ctxt - the context map attribute of MailMessage.send(HashMap), MUST NOT be null
        Since:
        JCMS-2677

      • addAuthKeyToImagesSrc

        public static java.lang.String addAuthKeyToImagesSrc​(java.lang.String contentHtml,
                                                     Member mbr)
        Add an authentication key to all images URL in the specified HTML content.

        All image URL in tag src='...' are modified to add an authkey.

        Parameters:
        contentHtml - html content to update
        mbr - the recipient member
        Returns:
        String the modified content

      • replaceRelativeUrlsWithAbsoluteUrls

        public static java.lang.String replaceRelativeUrlsWithAbsoluteUrls​(java.lang.String contentHtml)
        Convert all relative URLs inside the specified HTML content into absolute URL.

        Uses the current channel URL as prefix of relative URL.

        Parameters:
        contentHtml - the HTML content in which to look for relative URL (in src and href attributes)
        Returns:
        the modified content

      • getIncomingAddress

        public static java.lang.String getIncomingAddress​(java.lang.String localpart,
                                                  Member mbr,
                                                  java.lang.String label)
        Returns JCMS incoming email for the given Member
        Parameters:
        localpart - the mail prefix
        mbr - Member author of the mail
        label - the email label
        Returns:
        String valid incoming email

      • getLocalPartSuffixAuthKey

        public static java.lang.String getLocalPartSuffixAuthKey​(Member mbr)
        Returns a localpart suffix authkey for given Member.
        Parameters:
        mbr - the member
        Returns:
        String localpart sufix authkey (starting with +)

      • getIAFromMemberSet

        public static java.util.Set<javax.mail.internet.InternetAddress> getIAFromMemberSet​(java.util.Set<Member> mbrSet)
                                                                             throws javax.mail.MessagingException
        Returns a Set of InternetAddress build from a Set of Members
        Parameters:
        mbrSet - a Set of Members
        Returns:
        Set of InternetAddress
        Throws:
        javax.mail.MessagingException - a base class for all exceptions thrown by the Messaging classes

      • getInvalidEmailSet

        public static java.util.TreeSet<java.lang.String> getInvalidEmailSet​(java.util.Set<java.lang.String> mailSet,
                                                                     java.util.Set<Member> mbrSet)
        Retrieve all INVALID email from the specified mail and member Set.
        Parameters:
        mailSet - a set of email addresses
        mbrSet - a set of Member
        Returns:
        a set of invalid email
        Since:
        jcms-6.1

      • buildContentFromJsp

        public static java.lang.String buildContentFromJsp​(java.lang.String jspPath,
                                                   Member loggedMember,
                                                   java.lang.String language,
                                                   java.util.HashMap<java.lang.Object,​java.lang.Object> requestAttributeMap,
                                                   java.util.HashMap<java.lang.Object,​java.lang.Object> sessionAttributeMap)
        Builds a mail content from a given jsp
        Parameters:
        jspPath - the jsp to process
        loggedMember - the loggedMember
        language - the user language
        requestAttributeMap - Map of request attributes
        sessionAttributeMap - Map of session attributes
        Returns:
        String builded content

      • resolveAddresses

        public static void resolveAddresses​(MailMessage mail)
        Updates the given mailMessage's addresses field.

        String addresses will be resolved to Members if possible.

        optional already set Members will be kept.

        Parameters:
        mail - the mail to resolved String email to Members.
        Since:
        jcms-9.0

      • resolveAddress

        public static Member resolveAddress​(java.lang.String addr)
        Retrieves the Member from the given E-mail.
        Parameters:
        addr - an email address that will be parsed using MailUtil.getInternetAddress(String)
        Returns:
        the Member from E-mail if any
        Since:
        jcms-9.0

      • resolveAddress

        public static java.util.Set<Member> resolveAddress​(java.util.Set<java.lang.String> addressSet)
        Retrieves the set of Members given the set of E-mail addresses.

        Retrieved Member's E-mail will be removed from addressSet when resolved.

        Parameters:
        addressSet - the set of E-mails to retrieve their related Member if any
        Returns:
        the Set of Member
        Since:
        jcms-9.0