Models

mail_intake.models

Summary

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.

---

Public API

• MailIntakeMessage
• MailIntakeThread

---

Classes

MailIntakeMessage dataclass

MailIntakeMessage(
    message_id: str,
    thread_id: str,
    timestamp: datetime,
    from_email: str,
    from_name: str | None,
    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: str | None

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: datetime | None = ...,
)

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: datetime | None = 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.