Introdução

Aspose.Email FOSS for Python vai além da criação básica de mensagens. A biblioteca expõe toda a profundidade do modelo de propriedades MAPI, permitindo que você leia, escreva e consulte propriedades individuais por ID e tipo. Ela lida com destinatários, anexos e mensagens incorporadas como objetos de primeira classe, e fornece conversão bidirecional entre o formato binário MSG e o padrão email.message.EmailMessage do Python.

No nível do contêiner, o leitor e gravador CFB oferecem controle determinístico sobre documentos Compound File Binary. Você pode percorrer hierarquias de armazenamento, extrair dados brutos de fluxo, criar novos contêineres do zero e serializá‑los de volta para bytes. Tanto CFBError quanto MsgError fornecem tratamento estruturado de exceções para entrada malformada.

Esta postagem percorre cada recurso com exemplos de código verificados, extraídos diretamente da própria suíte de testes da biblioteca e dos scripts de exemplo.

O que está incluído

Acesso a Propriedades MAPI

Cada arquivo MSG é construído sobre propriedades MAPI. MapiMessage expõe set_property() e get_property() para trabalhar com propriedades pelo seu valor enum PropertyId. Use iter_properties() para enumerar todas as propriedades de uma mensagem, ou get_property_value() para recuperação direta de valores com decodificação opcional de tipo.

from aspose.email_foss import msg

message = msg.MapiMessage.create("Status report", "Weekly update attached.")

message.set_property(msg.PropertyId.SENDER_NAME, "Build Agent")
message.set_property(msg.PropertyId.SENDER_EMAIL_ADDRESS, "build.agent@example.com")
message.set_property(msg.PropertyId.DISPLAY_TO, "Alice Example; Bob Example")
message.set_property(msg.PropertyId.DISPLAY_CC, "Carol Example")
message.set_property(msg.PropertyId.DISPLAY_BCC, "Ops Archive")
message.set_property(
    msg.PropertyId.TRANSPORT_MESSAGE_HEADERS,
    "X-Environment: production\nX-Workflow: weekly-report\n",
)
message.save("report.msg")

Para ler as propriedades de volta de um arquivo existente:

from aspose.email_foss import msg

with msg.MapiMessage.from_file("report.msg") as loaded:
    print(f"Subject: {loaded.subject}")
    print(f"Body: {loaded.body}")

    for prop in loaded.iter_properties():
        print(f"tag=0x{prop.property_tag:08X}")

Destinatários e Anexos

Adicione destinatários com add_recipient(), especificando o nome de exibição e o tipo de destinatário (Para, CC ou CCO). Anexe arquivos com add_attachment() usando bytes brutos e um tipo MIME. Para mensagens aninhadas, add_embedded_message_attachment() incorpora um MapiMessage completo como um objeto filho dentro do pai.

from aspose.email_foss import msg

message = msg.MapiMessage.create("Team update", "See attached notes.")

message.add_recipient("alice@example.com", display_name="Alice Example")
message.add_recipient(
    "carol@example.com",
    display_name="Carol Example",
    recipient_type=msg.RECIPIENT_TYPE_CC,
)
message.add_recipient(
    "archive@example.com",
    display_name="Ops Archive",
    recipient_type=msg.RECIPIENT_TYPE_BCC,
)

message.add_attachment("notes.txt", b"Meeting notes content\n", mime_type="text/plain")
message.add_attachment("data.bin", b"\x00\x01\x02\x03", mime_type="application/octet-stream")
message.save("team-update.msg")

Para inspecionar anexos em uma mensagem existente:

from aspose.email_foss import msg

with msg.MapiMessage.from_file("team-update.msg") as loaded:
    for att in loaded.iter_attachments_info():
        print(f"name={att.filename} mime={att.mime_type} size={len(att.data)}")
        print(f"  embedded={att.is_embedded_message} storage={att.storage_name}")

Conversão de MSG para EmailMessage

A biblioteca converte em ambas as direções entre MSG e email.message.EmailMessage do Python. Use to_email_message() para produzir um objeto MIME compatível com padrões, ou from_email_message() para importar um EmailMessage existente para o formato MSG. Métodos de conveniência to_email_bytes() e to_email_string() serializam diretamente para bytes ou texto.

from aspose.email_foss import msg

with msg.MapiMessage.from_file("example.msg") as loaded:
    email_msg = loaded.to_email_message()

    print(f"content_type: {email_msg.get_content_type()}")
    print(f"is_multipart: {email_msg.is_multipart()}")
    print(f"headers: {len(email_msg)}")

    for key, value in email_msg.items():
        print(f"  {key}: {value}")

    body_part = email_msg.get_body(preferencelist=("plain", "html"))
    if body_part is not None:
        print(f"body: {body_part.get_content()[:200]}")

Viagem de Ida e Volta do Contêiner CFB

Construa e serialize contêineres Compound File Binary independentemente da camada MSG. CFBDocument.from_file() carrega um contêiner existente em um modelo de documento mutável com nós CFBStorage e CFBStream. CFBWriter.write_file() serializa o documento de volta ao disco de forma determinística.

from aspose.email_foss.cfb import CFBDocument, CFBReader, CFBWriter

reader = CFBReader.from_file("container.cfb")
document = CFBDocument.from_reader(reader)
reader.close()

output = CFBWriter.to_bytes(document)
print(f"Serialized {len(output)} bytes")

Manipulação de Erros

A biblioteca gera CFBError para conteúdo CFB malformado e MsgError para estrutura MSG inválida. MapiMessage também expõe uma propriedade validation_issues que retorna uma tupla de strings de aviso sem gerar uma exceção, permitindo que você decida quão estritamente lidar com arquivos não conformes.

from aspose.email_foss.cfb import CFBReader, CFBError
from aspose.email_foss.msg import MsgReader, MsgError

try:
    reader = CFBReader.from_file("corrupted.cfb")
except CFBError as e:
    print(f"CFB parse error: {e}")

try:
    reader = MsgReader.from_file("malformed.msg")
except MsgError as e:
    print(f"MSG parse error: {e}")

Início rápido

pip install aspose-email-foss>=26.3

Carregue um MSG existente, leia seus metadados e liste os anexos:

from aspose.email_foss import msg

with msg.MapiMessage.from_file("inbox-message.msg") as message:
    print(f"Subject: {message.subject}")
    print(f"Body preview: {message.body[:200] if message.body else '(empty)'}")

    for att in message.iter_attachments_info():
        print(f"Attachment: {att.filename} ({att.mime_type}, {len(att.data)} bytes)")

    issues = message.validation_issues
    if issues:
        print(f"Warnings: {issues}")

Formatos suportados

FormatoImportarExportar
MSGSimSim
CFBSimSim

Código Aberto e Licenciamento

Aspose.Email FOSS for Python é lançado sob a MIT License. Você pode usá-lo em projetos pessoais, internos e comerciais sem restrição. O código‑fonte está disponível no GitHub.

Começando