Models

mail_intake.models

Domain models for Mail Intake.

---

Summary

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.

---

Public API

MailIntakeMessage
MailIntakeThread

---

Classes

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.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message
- It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing

Constraints:

- No provider-specific identifiers, payloads, or API semantics should appear in this model

Attributes

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.

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