Models
mail_intake.models
Domain models for Mail Intake.
This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.
Models in this package: - Represent fully parsed and normalized mail data - Are safe to persist, serialize, and index - Contain no provider-specific payloads or API semantics - Serve as stable inputs for downstream processing and analysis
These models form the core internal data contract of the library.
MailIntakeMessage
dataclass
MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: Optional[str], subject: str, body_text: str, snippet: str, raw_headers: Dict[str, str])
Canonical internal representation of a single email message.
This model represents a fully parsed and normalized email message. It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing.
No provider-specific identifiers, payloads, or API semantics should appear in this model.
body_text
instance-attribute
body_text: str
Extracted plain-text body content of the message.
from_email
instance-attribute
from_email: str
Sender email address.
from_name
instance-attribute
from_name: Optional[str]
Optional human-readable sender name.
message_id
instance-attribute
message_id: str
Provider-specific message identifier.
raw_headers
instance-attribute
raw_headers: Dict[str, str]
Normalized mapping of message headers (header name → value).
snippet
instance-attribute
snippet: str
Short provider-supplied preview snippet of the message.
subject
instance-attribute
subject: str
Raw subject line of the message.
thread_id
instance-attribute
thread_id: str
Provider-specific thread identifier to which this message belongs.
timestamp
instance-attribute
timestamp: datetime
Message timestamp as a timezone-naive UTC datetime.
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.
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.
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.
add_message
add_message(message: MailIntakeMessage) -> None
Add a message to the thread and update derived fields.
This method: - Appends the message to the thread - Tracks unique participants - Updates the last activity timestamp
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message |
MailIntakeMessage
|
Parsed mail message to add to the thread. |
required |