Email conversion

ARender converts email files (EML, MSG) to PDF for rendering. The conversion is handled by the rendition engine (document-service-broker) and uses wkhtmltopdf for HTML-to-PDF conversion. This page covers the configuration properties that control how email metadata and content are rendered.

All properties in this page are set on the rendition engine (application.properties) unless stated otherwise.

Date formatting

Control how dates appear in the converted email header.

emltopdf.config.format.date=EEE d MMM yyyy HH:mm:ss ZZ

The format follows Java SimpleDateFormat patterns. The example above renders 2022-01-24T04:54:42-05 as Mon 24 Jan 2022 04:54:42 -0500.

Timezone

By default, dates are formatted in the UTC timezone. To use a specific timezone:

emltopdf.config.time.zone=Europe/Paris

To use the timezone extracted from each email's date header, set the following property on the Web UI side:

default.url.parser.use.timeZone.for.ids=true

Non-Latin character encoding

Subjects and attachment names containing non-Latin characters (Chinese, Arabic, Cyrillic, etc.) may display incorrectly. To fix this, configure the rendition engine to use the email body's encoding for header fields:

emltopdf.encode.header.with.body.encoding=true
emltopdf.config.filter.special.characters.regex=
emltopdf.config.filter.replacement.character=

Setting the regex and replacement to empty strings disables the default special-character filter, which would otherwise replace non-Latin characters with underscores.

tip

If encoding issues persist after applying the above, enable locale-based encoding on the Web UI side. This passes the user's locale to the rendition engine so it can select the correct character encoding:

default.url.parser.use.locale.for.ids=true

Header language

The rendered email header labels (From, To, Subject, Date, etc.) default to French. To switch to English:

emltopdf.config.header.language=EN

Supported values: FR, EN.

HTML embedded image resizing

Emails with HTML bodies may contain large embedded images that exceed the page width in the converted PDF. Enabling image resizing scales these images to fit within the page boundaries:

emltopdf.resize.embedded.image.enabled=true

Default: false.

Performance tradeoff

Enabling this option adds processing overhead during conversion. The rendition engine must decode each embedded image to determine its dimensions and rewrite the HTML before passing it to wkhtmltopdf. For emails with many or large embedded images, this increases conversion time. Enable it only if oversized images are a recurring problem in your document set.

Troubleshooting

wkhtmltopdf not converting

Email HTML-to-PDF conversion relies on wkhtmltopdf. If conversion fails:

• Linux: if the error mentions an X server problem, install the xvfb package. The ARender Docker images include this by default. For manual installations, wrap the binary:

  mv /usr/bin/wkhtmltopdf /usr/bin/wkhtmltopdf_nohead

  Create /usr/bin/wkhtmltopdf:

  #!/bin/bash
  xvfb-run -a -s "-screen 0 640x480x16" /usr/bin/wkhtmltopdf_nohead "$@"

  chmod a+x /usr/bin/wkhtmltopdf

External images not loading

If the email body references external images (hosted URLs), wkhtmltopdf must be able to reach those URLs from the rendition server. If network access is restricted, you can configure a proxy or accept degraded rendering without external images.

Property reference

See Rendition properties — Email conversion for the full list of email conversion properties.