{"record":{"id":"e6d441a7e0d2a035","repo":"docling-project/docling","slug":"the-mail-parser-package-is-required-to-process-e","errorCode":null,"errorMessage":"The 'mail-parser' package is required to process email files. Install it with `pip install 'docling-slim[format-email]'`.","messagePattern":"The 'mail-parser' package is required to process email files\\. Install it with `pip install 'docling-slim\\[format-email\\]'`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/backend/email_backend.py","lineNumber":81,"sourceCode":"\n_MSG_INSTALL_HINT = (\n    \"The 'python-oxmsg' package is required to process Outlook .msg files. \"\n    \"Install it with `pip install 'docling-slim[format-email]'`.\"\n)\n\n\nclass EmailDocumentBackend(DeclarativeDocumentBackend):\n    def __init__(\n        self,\n        in_doc: InputDocument,\n        path_or_stream: BytesIO | Path,\n        options: EmailBackendOptions | None = None,\n    ):\n        # Raised before super().__init__() so a missing optional dependency\n        # gives an actionable message rather than a NameError when mailparser\n        # is dereferenced below.\n        if not _MAILPARSER_AVAILABLE:\n            raise ImportError(_INSTALL_HINT) from _MAILPARSER_IMPORT_ERROR\n        if options is None:\n            options = EmailBackendOptions()\n        super().__init__(in_doc, path_or_stream, options)\n\n        self.options: EmailBackendOptions = options\n        self.valid = False\n        self.is_msg = False\n        self.mail: mailparser.MailParser | None = None\n\n        try:\n            raw = self._read_bytes()\n            self.is_msg = raw.startswith(_MSG_MAGIC)\n            if self.is_msg:\n                raw = self._msg_to_rfc822_bytes(raw)\n            self.mail = mailparser.parse_from_bytes(raw)\n\n            self.valid = self.mail is not None\n        except ImportError:","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/email_backend.py#L63-L99","documentation":"EmailDocumentBackend.__init__ raises ImportError before super().__init__() when the optional mail-parser dependency is not installed, with the chained original import error preserved. Docling ships email support as an optional extra, so importing the backend without the package installed is a supported but actionable failure.","triggerScenarios":"Constructing EmailDocumentBackend (or converting an .eml file) in an environment where `import mailparser` failed — e.g. docling-slim installed without the format-email extra.","commonSituations":"Installing docling-slim instead of full docling; slimming a Docker image and dropping extras; upgrading Docling in a venv where the extra was never re-added.","solutions":["Install the extra: pip install 'docling-slim[format-email]'","Or install the full package: pip install docling","Pin the extra in requirements.txt/pyproject so CI and Docker rebuilds keep it"],"exampleFix":"# before\npip install docling-slim\n\n# after\npip install 'docling-slim[format-email]'","handlingStrategy":"validation","validationCode":"try:\n    import mailparser  # noqa: F401\nexcept ImportError:\n    raise RuntimeError(\"Install: pip install 'docling-slim[format-email]'\")","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(src)\nexcept ImportError as exc:\n    if 'mail-parser' in str(exc):\n        install_or_skip('docling-slim[format-email]')\n    raise","preventionTips":["Declare format extras explicitly in pyproject/requirements","Add a startup dependency probe for every format your service accepts"],"tags":["email","optional-dependency","installation","importerror"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}