Thread

mail_intake.models.thread

Thread domain models for Mail Intake.

---

Summary

This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.

Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.

Classes

MailIntakeThread dataclass

MailIntakeThread(thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...)

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject and participant set
- It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions
- This model is provider-agnostic and safe to persist

Attributes

last_activity_at class-attribute instance-attribute

last_activity_at: Optional[datetime] = None

Timestamp of the most recent message in the thread.

messages class-attribute instance-attribute

messages: List[MailIntakeMessage] = field(default_factory=list)

Ordered list of messages belonging to this thread.

normalized_subject instance-attribute

normalized_subject: str

Normalized subject line used to group related messages.

participants class-attribute instance-attribute

participants: Set[str] = field(default_factory=set)

Set of unique participant email addresses observed in the thread.

thread_id instance-attribute

thread_id: str

Provider-specific thread identifier.

Functions

add_message

add_message(message: MailIntakeMessage) -> None

Add a message to the thread and update derived fields.

Parameters:

Name	Type	Description	Default
message	MailIntakeMessage	Parsed mail message to add to the thread.	required

Notes

Responsibilities:

- Appends the message to the thread
- Tracks unique participants
- Updates the last activity timestamp