Encode and decode the Outlook Thread-Index email header (MAPI PidTagConversationIndex, Microsoft Graph conversationIndex).

A conversation index is a 22-byte header block followed by one 5-byte child block per reply, base64-encoded when transported in the Thread-Index MIME header. This library decodes both header variants found in the wild and encodes replies byte-compatible with what Outlook/Exchange themselves produce, so threads keep grouping and ordering correctly in Outlook.

Format summary

Header block (22 bytes): 6 time-derived bytes + 16-byte conversation GUID. Two variants exist (MS-OXOMSG 2.2.1.3 and its Appendix A footnote <2>):

• :classic — desktop Outlook 2007-2019, Exchange 2007-2010. Bytes 0-5 hold FILETIME >>> 16 of the original message time (the leading byte is 0x01 for any date between 1829 and 2057 and doubles as the documented "reserved byte"). Base64 starts with Ac/Ad/Ae.

• :modern — Exchange 2013+, Exchange Online, OWA, Graph API. Byte 0 is the reserved 0x01, bytes 1-5 hold FILETIME >>> 24. Base64 starts with AQ (typically AQH).

Child block (5 bytes): 1 bit delta code (DC), 31 bits time delta, 8 bits random. DC=0 stores delta >>> 18 (26.2 ms units, max ~1.78 years), DC=1 stores delta >>> 23 (0.84 s units, max ~57 years).

The two undocumented behaviors this library accounts for

1. Deltas are cumulative. Each child's delta is relative to the accumulated time of the previous child block, not to the header (the MS-OXOMSG prose says "header", Microsoft's own code says otherwise).

2. Deltas chain from the classic read of the header — and wrap. All Microsoft appenders (MAPI cindex.c, Exchange's ConversationIndex) compute the chain anchor by reading the header time bytes the classic way, even for :modern headers, where that read lands around year 1831. The resulting ~195-year virtual delta forces DC=1 and the 31-bit field silently truncates mod 2^31 — i.e. wraps modulo ~57 years (cf. footnote <3>: "Exchange 2013/2016/2019 set the Delta Code field to 1 and do not calculate the Time Delta field based on TimeDiff"). Decoding recovers true reply dates by re-running the same chain arithmetic and adding the minimal number of 2^(31+shift)-tick wrap windows needed to land at or after the header date.

Child timestamps record when each reply was composed (reply draft created), not when it was sent or delivered, so expect them to precede the displayed message times by the composition duration.

Examples

iex> {:ok, index} =
...>   "01CDE90ABFE0D78F0E4280824120B2F1D0E3C07ED0070000CCBA300000114460"
...>   |> Base.decode16!()
...>   |> Base.encode64()
...>   |> ThreadIndex.decode()
iex> {index.format, index.date}
{:classic, ~U[2013-01-02 17:01:04.168550Z]}
iex> Enum.map(index.replies, & &1.date)
[~U[2013-01-02 17:23:58.065254Z], ~U[2013-01-02 17:25:53.932902Z]]

References

• MS-OXOMSG 2.2.1.3 PidTagConversationIndex and its Appendix A footnotes <2> and <3>
• MAPI "Tracking Conversations"
• Microsoft MAPI SDK sample cindex.c; decompiled Microsoft.Exchange.Data.Storage.ConversationIndex
• Meridian Discovery: E-mail Conversation Index Analysis
• Metaspike community: Thread-Index Header Field