1   package com.atlassian.mail;
2   
3   /**
4    * Used for maintaining thread information in sent emails.
5    */
6   public interface MailThreader
7   {
8       /**
9        * Set the In-Reply-To header for an email, so it will appear threaded.
10       * @param email The unsent mail to alter
11       */
12      void threadEmail(Email email);
13  
14      /**
15       * Store the (MTA-allocated) Message-Id of a <em>sent</em> email, so later
16       * emails 'in reply to' this can be threaded.
17       * <p>
18       * This is considered a bad idea for scalability because it requires applications to store details of every single outgoing email.
19       * For example, see JRA-9979.
20       * If you need to recognise incoming "In-Reply-To" headers, then it is preferred to use {@link #getCustomMessageId(Email)} to
21       * create a parsable custom Message ID.
22       *
23       * @param email The sent mail whose Message-ID we should record
24       *
25       * @deprecated Use {@link #getCustomMessageId(Email)} instead to create a parsable custom Message ID. Since v2.5.0.
26       */
27      void storeSentEmail(Email email);
28  
29      /**
30       * Allows this MailThreader to define a custom Message-ID to be set in the outgoing mail header.
31       * <p>
32       * Returning null means let the library create one automatically.
33       * <p>
34       * Be aware that Message-IDs must be globally unique, and can only contain a limited subset of ASCII characters.
35       * <p>
36       * Do not include the angle-brackets in the returned ID - these will be added for you.
37       *
38       * @param email the unsent email
39       * @return the required custom Message-ID header, or null to let the library create one automatically.
40       */
41      String getCustomMessageId(Email email);
42  }