Edit Email Leave feedback

This example demonstrates the standard open-edit-save pipeline with Email documents, using different options on every step.

There is a group of Email file formats, which are usually intended for storing individual mail letters, contact data, personal information, calendars, and so on. There are plenty of them, because almost every email program uses its own set of such formats. This article explains how to edit different Email files, because due to their nature their editing differs from editing common text documents.

Loading Email documents is usual and the same as for other formats. Like with text, XPS, and e-Book formats, and unlike PDF and Office formats, there are no loading options for Email documents — just specify a path to the file or a byte stream with the document content in the constructor of the Editor class, and that’s all.

from groupdocs.editor import Editor

# Load from a file path
editor_from_path = Editor("message.eml")

# Load from a binary stream
with open("message.eml", "rb") as stream:
    editor_from_stream = Editor(stream)

Like for all other formats, there is a special EmailEditOptions class for adjusting the editing of Email documents. An instance of this class can be specified in the editor.edit() method. It is also possible to use the parameterless overload of editor.edit() — in this case GroupDocs.Editor automatically applies the default EmailEditOptions.

The EmailEditOptions class has only one member — a mail_message_output property of the MailMessageOutput type. MailMessageOutput is a flagged enum that controls which parts of the mail message should be delivered to the output EditableDocument and then to the emitted HTML. The MailMessageOutput enum has both atomic values that are responsible for a single part of the mail message (SUBJECT, FROM, TO, CC, BCC, DATE, BODY, ATTACHMENTS), as well as combined values, like COMMON and ALL.

It is important to mention that currently GroupDocs.Editor cannot process the content of attachments — it can only display a list of attachment names. So the MailMessageOutput.ATTACHMENTS flag, when specified, emits a list of attachment names, if they are present in the mail message.

The runnable example below loads an EML file, edits it with the MailMessageOutput.ALL value, and obtains the resulting HTML content.

import os
from groupdocs.editor import Editor, License
from groupdocs.editor.options import EmailEditOptions, MailMessageOutput

def edit_email():
    # Optionally set a license
    license_path = os.path.abspath("./GroupDocs.Editor.lic")
    if os.path.exists(license_path):
        License().set_license(license_path)

    # Load an input Email document into the Editor
    with Editor("./sample-email.eml") as editor:
        # Create edit options that process all parts of the mail message
        edit_options = EmailEditOptions(MailMessageOutput.ALL)

        # Edit the Email document and obtain an EditableDocument
        editable = editor.edit(edit_options)

        # Obtain the HTML content (in practice it is sent to the WYSIWYG-editor)
        content = editable.get_content()
        print("Generated HTML content length:", len(content))

        editable.dispose()

if __name__ == "__main__":
    edit_email()

Generated HTML content length: 1255

It is also possible to use any user-defined combination of atomic values. For example, you can create a combination that processes only metadata, but not the body and attachments list:

from groupdocs.editor.options import EmailEditOptions, MailMessageOutput

metadata_only = (MailMessageOutput.SUBJECT | MailMessageOutput.FROM | MailMessageOutput.TO |
                 MailMessageOutput.CC | MailMessageOutput.BCC | MailMessageOutput.DATE)
edit_options = EmailEditOptions(metadata_only)

Saving edited Email documents in general follows the same principles as for other document formats, but with several distinctions. As usual, after obtaining edited HTML content from the client-side WYSIWYG-editor, an instance of the EditableDocument should be created, and then it should be passed to the editor.save() method.

For Email documents the save options class is EmailSaveOptions. Like EmailEditOptions, this class has only one member — a mail_message_output property of the MailMessageOutput type. The only distinction is that in EmailEditOptions the mail_message_output property controls which parts of the mail message are processed while generating the EditableDocument from the input file, while in EmailSaveOptions it controls which parts are processed while generating the output Email file from the edited EditableDocument.

The EmailSaveOptions class does not allow specifying the format for the output document — it is automatically the same as the format of the original Email document loaded into the Editor class. For example, if you loaded an MSG file, then editor.save() will also generate an MSG file, no matter which file extension you specify.

from groupdocs.editor import Editor, EditableDocument
from groupdocs.editor.options import EmailEditOptions, EmailSaveOptions, MailMessageOutput

with Editor("./sample-email.eml") as editor:
    # Edit with all content
    original = editor.edit(EmailEditOptions(MailMessageOutput.ALL))

    # Send the content to the WYSIWYG-editor and obtain the edited content (omitted here)
    edited = EditableDocument.from_markup(original.get_embedded_html())

    # Save only the common parts of the mail message
    save_options = EmailSaveOptions(MailMessageOutput.COMMON)
    editor.save(edited, "./edited-email.eml", save_options)

    original.dispose()
    edited.dispose()

The article Extracting document metainfo describes the get_document_info() method, which allows you to detect the document format and extract its metadata without editing it. This mechanism also works with Email documents.

When get_document_info() is called for an Editor instance that is loaded with an Email document, the method returns a metadata view corresponding to the EmailDocumentInfo type — a common type for all Email formats like EML, EMLX, MSG, and so on. It exposes the format, page_count, size, and is_encrypted properties. For Email documents page_count always returns 1 (email documents have no paged view), and is_encrypted always returns False (email documents cannot be encrypted with a password).

from groupdocs.editor import Editor

with Editor("./sample-email.eml") as editor:
    info = editor.get_document_info()
    print("Format:", info.format.name)
    print("Size:", info.size)
    print("Is encrypted:", info.is_encrypted)