Package: emlmailreader
EMLMailReaderA Python library designed to analyze EML files and to extract details and attachments contained within. It captures various information from the email, such as attachments, sender address, recipient address, subject, body, and a comprehensive list of all headers in the EML file. The parsed information is exportable as a JSON object, and attachments can be conveniently downloaded to a specified local directory.Table of ContentsExample UsageModules UsedDocumentationExample UsageHere's a sample code to leverageEMLMailReaderin parsing an EML file and extracting information contained within.from EMLMailReader import MailReader, RxMailMessage
  
reader: MailReader = MailReader()
message = reader.get_email("COMPLETE_EML_FILE_PATH")
if isinstance(message, RxMailMessage):
    json_string = message.export_as_json()
    print(json_string)In this context, the term "COMPLETE_EML_FILE_PATH" indicates the complete path of the .EML file intended for processing. Running this code will output a JSON string resembling the one provided below.{
    "From": "A Sample Email <sample-email-address@sample-domain.com>",
    "Subject": "This is a test process to generate sample JSON for emlmailreader",
    "Headers-Encoding": "",
    "Body-Encoding": "",
    "Message-ID": "<65c8f7741866_1c7cdb1e649248c@ao3-app09.mail>",
    "IsMultiPart": true,
    "Mime-Version": "1.0",
    "Date": "Sun, 11 Feb 2024 16",
    "Content-Description": "",
    "Entity-Type": "MIME_PART",
    "Content-ID": "",
    "Headers": 
    {
      "Received-SPF": "Pass (protection.outlook.com",
      "X-IncomingTopHeaderMarker": "OriginalChecksum",
      "DKIM-Signature": "v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed;d=archiveofourown.org; s=dkim20210802; h=Content-Transfer-Encoding",
      "X-IncomingHeaderCount": "11",
      "Return-Path": "do-not-reply@archiveofourown.org",
      "X-Message-Delivery": "Vj0xLjE7dXM9MDtsPTA7YT0xO0Q9MTtHRD0xO1NDTD0tMQ=="
    },
    "Content-Type": "{\"Media-Type\": \"multipart/alternative\", \"Character-Set\": \"utf-8\", \"Name\": \"\", \"Boundary\": \"--==_mimepart_65c8f773f2a1b_1c7cdb1e64923ad\"}",
    "Content-Disposition": "None",
    "To": "something@something.com",
    "Cc": "",
    "Bcc": "",
    "Reply-To": "",
    "Attachment-Count": 0
}Modules UsedGiven below are the list of all the modules used in theEMLMailReaderlibrary.os- To perform operating system file path manipulations.logging- To generate logs for EML file processing.quopri- To decode quoted-printable encoded string.base64- To decode base64 encoded string.json- To convert a python object to JSON and vice versa.All modules mentioned above are present in the Standard Python library and thus, do not require explicit installation or configuration.DocumentationThis section showcases the key classes employed in the library for handling an EML file and storing the information extracted from it.Class NamePurpose in libraryMailReaderProcesses an EML file, and returns the extracted information as an object of typeRxMailMessage.RxMailMessageA container to store and process information parsed from the EML file.TextEncodingExposes methods to decode header strings and MIME part body in the EML file.MailAttachmentExposes properties and methods to represent a single mail attachment from the EML file.MailAddressA class to represent an email address.ContentTypeA class to represent the Content-Type header of a MIME entity.ContentDispositionA class to represent the Content-Disposition header of a MIME entity.LoggerA class to manage the configuration and generation of logs during EML file processing.This section also elaborates other custom entities exposed by the library.NamePurpose in libraryCustom EnumerationsEnumerations to record different options available for processing.Custom ExceptionsExceptions to report error scenarios that might occur during processing.Custom CollectionsCollections to hold a list of items of a composite type.MailReaderExposes a single instance method, to process an EML file and return all the information extracted (headers, email body and attachments) as an RxMailMessage object.Instance Method(s)MethodParameter(s)Return(s)get_emailemlPath [string] - The complete file path where the EML file is located.a RxMailMessage object in case of successful parsing, 'NoneType' in case of any errors.RxMailMessageA class to represent all the information extracted from an EML file.PropertiesPropertyTypePurposeFromMailAddressEmail address in the 'From' header of EML file.ToMailAddressCollectionA list of all the emails present in 'To' header of EML file.CcMailAddressCollectionA list of all the emails present in 'Cc' header of EML file.BccMailAddressCollectionA list of all the emails present in 'Bcc' header of EML file.ReplyToMailAddressCollectionA list of all the emails present in 'Reply-To' header of EML file.SubjectstringSubject of the emailBodystringBody of the emailContentTypeContentTypeValue in the 'Content-Type' header of EML file.ContentDispositionContentDispositionValue in the 'Content-Disposition' header of EML file.ContentTransferEncodingTransferEncodingValue in the 'Content-Transfer-Encoding' header of EML file.HeadersdictionaryA dictionary value containing all other headers.MessageIDstring'Message-ID' header value.MimeVersionstring'MIME-Version' header value.ContentIDstring'Content-ID' header value.AttachmentsMailAttachmentCollectionList of all the attachments present in the EML file.Instance Method(s)MethodParameter(s)Return(s)export_as_jsonNo parameters neededa JSON string containing all the fields of the RxMailMessage object.save_attachmentsTargetFolderPath [string] - Folder where the attachments will be downloaded.does not return a valueTextEncodingA class to perform character encoding - BASE64 and QUOTED-PRINTABLE on MIME part content. It uses the 'quopri' and 'base64' modules in the Standard Python library to decode the encoded strings.Static Method(s)MethodParameter(s)Return(s)decode_headerencoded_string [string] - The encoded MIME header value to be decoded.the decoded string.decode_base64_filefile_contents [string] - The file contents encoded as a base64 string.The decoded file contents as 'bytes'.MailAttachmentA class to represent an attachment present in the EML file.PropertiesPropertyTypePurposeNamestringGets/Sets the name of the attachment.ContentTypeContentTypeGets/Sets the "Content-Type" of the attachment.ContentDispositionContentDispositionGets/Sets the "Content-Disposition" of the attachment.ContentsbytesGets/Sets the contents of the attachment.ContentIDstringGets/Sets the "Content-ID" of the attachment.Instance Method(s)MethodParameter(s)Return(s)parse_valuescontents [bytes] - Contents of the MailAttachment.content_type [ContentType] - Content-Type of the attachment.content_disposition [ContentDisposition] - Content-Disposition of the attachment.content_id [string] - Content-ID of the attachment.does not return a value.MailAddressA class to represent an email address.PropertiesPropertyTypePurposeDisplayNamestringGets/Sets the display name of the mail address.EmailstringGets/Sets the email part of the mail address.Instance Method(s)MethodParameter(s)Return(s)parseMailAddressString [string] - The string to be parsed into a MailAddress object.does not return a value.ContentTypeA class to represent the Content-Type header of a MIME entity.PropertiesPropertyTypePurposeMediaTypestringMedia type and sub-type of the MIME entity.CharsetstringCharacter set of the MIME entity.BoundarystringBoundary value for 'multipart' MIME entities.NamestringName of the MIME entity.Instance Method(s)MethodParameter(s)Return(s)parseContentTypeString [string] - The string to be parsed into a ContentType object.does not return a value.ContentDispositionA class to represent the Content-Disposition header of a MIME entity.PropertiesPropertyTypePurposeDispositionTypeDispositionTypeDisposition type of the MIME entity.FileNamestringFile name of the MIME entity.CreationDatestringDate when the MIME entity was created.ModificationDatestringDate when the MIME entity was last modified.SizeintegerSize of the MIME entity.Instance Method(s)MethodParameter(s)Return(s)parseContentDispositionString [string] - The string to be parsed into a ContentDisposition object.does not return a value.LoggerA class to manage the configuration and generation of logs during EML file processing.Static Method(s)MethodParameter(s)Return(s)set_configurationlogging_mode [LoggingMode] - Denotes where the generated logs have to be stored or printed.target_folder [string] - The target folder where the log file must be created. If the 'logging_mode' is 'LoggingMode.CONSOLE', an empty string is returned.the complete path to the log file generated.log_entrymessage [string] - message to be loggedlogging_level [LoggingLevel] - Type of message being logged.does not return a valueCustom EnumerationsGiven below are the custom enumerations exposed by the library.TransferEncodingEnumeration to represent the different content encoding methods supported.NameValueBASE641SEVEN_BIT2EIGHT_BIT3QUOTED_PRINTABLE4EntityTypeEnumeration to represent the different MIME entity types supported.NameValueATTACHMENT1TEXT2MIME_PART3DispositionTypeEnumeration to represent the different content disposition types supported in MIME.NameValueATTACHMENT1INLINE2LoggingLevelEnumeration containing the different levels of logging available for a module.NameValueDEBUG1INFO2ERROR3CRITICAL4LoggingModeEnumeration containing the different modes of logging available for a module.NameValueCONSOLE1FILE2Custom ExceptionsGiven below are the list of custom exceptions exposed by the library.ExceptionPurposeInvalidEncodingErrorTo report Invalid Encoding errors.FileMissingErrorTo report when file is missing at the specified location.IncompleteHeaderErrorTo report when an incomplete header line is found in the EML file.FolderNotAvailableErrorTo report when a given folder is not available at the specified location.Custom CollectionsThe library exposes the following custom collection classes.CollectionPurposeMailAddressCollectionA Collection to hold a list of MailAddress instance(s).MailAttachmentCollectionA Collection to hold a list of MailAttachment instance(s).Instance Method(s)MethodParameter(s)Return(s)appenditem[MailAddress or MailAttachment] - the item to be appended to the end of the collection.does not return a value.lengthno parameter(s).number of items in the collection.export_as_listno parameter(s).the items in the collection as a new list.