Skip to content

common_reports.schemas.emails.results

Inspectable outcomes returned by email delivery and mailbox operations.

Classes

AttachmentResult

Bases: EmailOperationResult

The attachment’s bytes ride in content, never in the result’s repr.

Fields and properties declared here; inherited members belong to the bases above.

attachment

attachment: Optional[EmailAttachmentRecord] = None

content

content: Optional[bytes] = Field(default=None, repr=False)

CapabilityResult

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

backend_info

backend_info: dict[str, Any] = Field(default_factory=dict)

capabilities

capabilities: set[EmailCapability] = Field(default_factory=set)

DraftResult

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

draft_id

draft_id: Optional[str] = None

message_id

message_id: Optional[str] = None

thread_id

thread_id: Optional[str] = None

EmailOperationResult

Bases: BaseModel

Shared error and operator-facing fields for mailbox operations.

status is the HTTP status the provider refused with, when it gave one: 404 not found, 429 too many requests, 5xx the provider failing. It is a status, not a diagnosis: Gmail answers both a rate limit and a domain policy with 403, and a service account’s failed sign-in carries no status at all.

Fields and properties declared here; inherited members belong to the bases above.

error

error: Optional[str] = None

error_type

error_type: Optional[str] = None

operator_message

operator_message: str = ''

provider

provider: Optional[str] = None

status

status: Optional[int] = Field(default=None, ge=100, le=599)

success

success: bool

failed

@classmethod
def failed(exc: BaseException, *, provider: Optional[str] = None, operator_message: str = '', **values: Any) -> Self

HistoryResult

Bases: EmailOperationResult

expired marks a start cursor the mailbox no longer keeps: nothing was read, and only a full resynchronization recovers.

Fields and properties declared here; inherited members belong to the bases above.

changes

changes: list[EmailHistoryChange] = Field(default_factory=list)

expired

expired: bool = False

history_id

history_id: Optional[str] = None

next_page_token

next_page_token: Optional[str] = None

LabelBatch

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

labels

labels: list[EmailLabelRecord] = Field(default_factory=list)

MessageBatch

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

count

Read-only property.

count: int

messages

messages: list[EmailMessageRecord] = Field(default_factory=list)

next_page_token

next_page_token: Optional[str] = None

result_size_estimate

result_size_estimate: Optional[int] = Field(default=None, ge=0)

MessageRefBatch

Bases: EmailOperationResult

One page of the messages a search matches, by identity: nothing is fetched.

Fields and properties declared here; inherited members belong to the bases above.

count

Read-only property.

count: int

next_page_token

next_page_token: Optional[str] = None

refs

refs: list[MessageRef] = Field(default_factory=list)

result_size_estimate

result_size_estimate: Optional[int] = Field(default=None, ge=0)

MessageResult

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

message

message: Optional[EmailMessageRecord] = None

MutationResult

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

details

details: dict[str, Any] = Field(default_factory=dict)

target_ids

target_ids: list[str] = Field(default_factory=list)

ProfileResult

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

profile

profile: Optional[MailboxProfile] = None

ReadBatch

Bases: BaseModel

Compatibility result for read()/inbox().

A failed read is explicit: success is False and error/error_type say why — an empty batch never silently stands in for a failure.

Fields and properties declared here; inherited members belong to the bases above.

count

Read-only property.

count: int

error

error: Optional[str] = None

error_type

error_type: Optional[str] = None

folder

folder: str = 'INBOX'

messages

messages: list[ReadResult] = Field(default_factory=list)

success

success: bool = True

ReadResult

Bases: BaseModel

Compatibility read record, now carrying complete normalized mail metadata.

Fields and properties declared here; inherited members belong to the bases above.

attachments

attachments: list[EmailAttachmentRecord] = Field(default_factory=list)

bcc

bcc: str = ''

body_html

body_html: Optional[str] = None

body_text

body_text: Optional[str] = None

cc

cc: str = ''

date

date: str = ''

from_

from_: str = Field(default='', alias='from')

headers

headers: dict[str, str] = Field(default_factory=dict)

history_id

history_id: Optional[str] = None

in_reply_to

in_reply_to: Optional[str] = None

internal_at

internal_at: Optional[datetime] = None

labels

labels: list[str] = Field(default_factory=list)

mailbox

mailbox: Optional[MailboxRef] = None

references

references: tuple[str, ...] = ()

reply_to

reply_to: str = ''

rfc_message_id

rfc_message_id: Optional[str] = None

size_bytes

size_bytes: Optional[int] = Field(default=None, ge=0)

snippet

snippet: str = ''

subject

subject: str = ''

thread_id

thread_id: Optional[str] = None

to

to: str = ''

uid

uid: Optional[str] = Field(default=None, description='Provider message id / IMAP UID')

to_record

def to_record() -> EmailMessageRecord

Project the compatibility row into the normalized data schema.

SendResult

Bases: BaseModel

Outcome of one send, retaining the established public fields.

status is the HTTP status a failed send was refused with, when the transport gave one (the Gmail API, Graph); SMTP replies carry none.

Fields and properties declared here; inherited members belong to the bases above.

error

error: Optional[str] = None

error_type

error_type: Optional[str] = None

message_id

message_id: Optional[str] = None

operator_message

operator_message: str = ''

provider

provider: Optional[str] = None

provider_message_id

provider_message_id: Optional[str] = None

recipients

recipients: list[str] = Field(default_factory=list)

status

status: Optional[int] = Field(default=None, ge=100, le=599)

success

success: bool

thread_id

thread_id: Optional[str] = None

failed

@classmethod
def failed(exc: BaseException, message_id: Optional[str] = None, recipients: Optional[list[str]] = None, provider: Optional[str] = None) -> SendResult

from_delivery

@classmethod
def from_delivery(delivery: EmailDeliveryRecord, recipients: list[str], provider: Optional[str] = None) -> SendResult

ok

@classmethod
def ok(message_id: Optional[str], recipients: list[str], provider: Optional[str] = None, provider_message_id: Optional[str] = None, thread_id: Optional[str] = None) -> SendResult

ThreadRefBatch

Bases: EmailOperationResult

One page of the threads a search matches, by identity: nothing is fetched.

Fields and properties declared here; inherited members belong to the bases above.

count

Read-only property.

count: int

next_page_token

next_page_token: Optional[str] = None

refs

refs: list[ThreadRef] = Field(default_factory=list)

result_size_estimate

result_size_estimate: Optional[int] = Field(default=None, ge=0)

ThreadResult

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

thread

thread: Optional[EmailThreadRecord] = None

WatchResult

Bases: EmailOperationResult

Fields and properties declared here; inherited members belong to the bases above.

expires_at

expires_at: Optional[datetime] = None

history_id

history_id: Optional[str] = None