Skip to content

API reference

UnMsg's public Python API is intentionally small and stable from 1.0 onward. The contract:

  • The names listed here keep their identities and shapes across 1.x.
  • Data models (Attachment, MsgRecord, ConvertResult, ConvertOptions) gain new optional fields only — existing fields don't move or change meaning.
  • convert_file and convert_batch keep their existing keyword arguments; new optional arguments may be added at the tail.

Anything not listed here — submodules of unmsg.core, writers, the UI, the CLI module layout — is private and may change.

Quick example

from pathlib import Path
from unmsg import convert_file, ConvertOptions

result = convert_file(
    Path("mail.msg"),
    Path("./out"),
    ConvertOptions(formats=["md", "html", "pdf"]),
)

if result.status == "success":
    for path in result.output_paths:
        print("wrote", path)
elif result.status == "warning":
    print("converted with notes:", result.warnings)
else:
    print("couldn't convert:", result.error)

Functions

Convert a single .msg file into out_root.

Convert every file in sources into out_root.

progress (if given) is called as progress(done, total, source) after each file. Returns one :class:ConvertResult per input, in sorted order.

Data models

The outcome of converting one message.

error is already humanised — safe to show a user. Raw exception text belongs only in the DEBUG log, never here.

A parsed message, normalised and ready to render.

sent_on / received_on are timezone-aware and normalised to UTC so output is identical regardless of the converting machine's locale.

A file or inline image carried by a message.

data holds the full bytes short-term. cid is set for inline images referenced from the HTML body. is_nested_msg marks an embedded .msg (an email attached to an email); such attachments are parsed recursively into :attr:MsgRecord.nested.

Version