Skip to content

# 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`

    1

    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:

    1
    2
    3

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

Constraints:

    1
    2

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

##### Attributes

###### `` body_text `instance-attribute`

    1

    body_text: str

Extracted plain-text body content of the message.

###### `` from_email `instance-attribute`

    1

    from_email: str

Sender email address.

###### `` from_name `instance-attribute`

    1

    from_name: Optional[str]

Optional human-readable sender name.

###### `` message_id `instance-attribute`

    1

    message_id: str

Provider-specific message identifier.

###### `` raw_headers `instance-attribute`

    1

    raw_headers: Dict[str, str]

Normalized mapping of message headers (header name → value).

###### `` snippet `instance-attribute`

    1

    snippet: str

Short provider-supplied preview snippet of the message.

###### `` subject `instance-attribute`

    1

    subject: str

Raw subject line of the message.

###### `` thread_id `instance-attribute`

    1

    thread_id: str

Provider-specific thread identifier to which this message belongs.

###### `` timestamp `instance-attribute`

    1

    timestamp: datetime

Message timestamp as a timezone-naive UTC datetime.

#### `` MailIntakeThread `dataclass`

    1

    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:

    1
    2
    3
    4
    5

    - 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`

    1

    last_activity_at: Optional[datetime] = None

Timestamp of the most recent message in the thread.

###### `` messages `class-attribute` `instance-attribute`

    1

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

Ordered list of messages belonging to this thread.

###### `` normalized_subject `instance-attribute`

    1

    normalized_subject: str

Normalized subject line used to group related messages.

###### `` participants `class-attribute` `instance-attribute`

    1

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

Set of unique participant email addresses observed in the thread.

###### `` thread_id `instance-attribute`

    1

    thread_id: str

Provider-specific thread identifier.

##### Functions

###### `` add_message

    1

    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:

    1
    2
    3

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