# Processing of Attachments

This documentation describes how attachments are handled during mail imports. The documented behavior is independent of the mail protocol used — it makes no difference whether mails are imported via IMAP, EWS, etc.

<p class="callout info">This page describes **how attachments of an already-imported email** are classified and processed. Whether an email is imported at all is controlled independently by sender/subject filters, see [Filtering via Black- and Whitelisting](https://docs.squeeze.one/books/squeeze-2-admin-handbuch/page/filterung-mittels-black-und-whitelisting).</p>

### Attachments with Passwords

In daily business, a large number of encrypted attachments can arrive via your company's digital inbound channels. The following section covers the options available in Squeeze.

#### Compressed archives (.zip)

If you receive encrypted ZIP archives from your senders, Squeeze offers a way (from version &gt;=2.4.1) to store passwords per unique email address.

To configure this, open the Email tab as an admin:

[![2026-09-23_13-57.png](https://docs.squeeze.one/uploads/images/gallery/2026-09/scaled-1680-/2026-09-23-13-57.png)](https://docs.squeeze.one/uploads/images/gallery/2026-09/2026-09-23-13-57.png)

Afterwards switch to the Passwords sub-tab within the email configuration screen:

[![2026-09-23_13-57_1.png](https://docs.squeeze.one/uploads/images/gallery/2026-09/scaled-1680-/2026-09-23-13-57-1.png)](https://docs.squeeze.one/uploads/images/gallery/2026-09/2026-09-23-13-57-1.png)

Use the button at the bottom to add a new entry:

[![2026-09-23_13-58.png](https://docs.squeeze.one/uploads/images/gallery/2026-09/scaled-1680-/2026-09-23-13-58.png)](https://docs.squeeze.one/uploads/images/gallery/2026-09/2026-09-23-13-58.png)

Save the data by entering a unique email address and a password.

[![2026-09-23_13-58_1.png](https://docs.squeeze.one/uploads/images/gallery/2026-09/scaled-1680-/2026-09-23-13-58-1.png)](https://docs.squeeze.one/uploads/images/gallery/2026-09/2026-09-23-13-58-1.png)

---

Please note the following when using this functionality:

1. You must specify full email addresses — always the complete address, otherwise saving fails.
2. To assign multiple passwords to one email address, simply create multiple entries.
3. If emails contain attachments that cannot be decrypted, those emails are moved to the configured error email folder.

<p class="callout warning">Stored passwords are not used for password-protected PDF files.</p>

<p class="callout warning">A unique email address looks like: dexpro@test.com, not wildcard constructs like: \*pro@test.com</p>

### Attachment Filters (Email Attachment Filters)

#### How it works

For each mail, attachments are checked against import rules. The first rule whose sender and filename pattern match an attachment decides what happens to it. Non-global rules take highest priority.

##### Example:

<table id="bkmrk-priority-example-fir"><thead><tr><th>Priority</th><th>Example</th></tr></thead><tbody><tr><td>First priority</td><td>specific sender (<support@dexpro.de>) + specific filename pattern (Rechnung.pdf)</td></tr><tr><td>Second priority</td><td>specific domain (dexpro.de) + unspecific filename pattern (\*.pdf)</td></tr><tr><td>etc.</td><td>-</td></tr></tbody></table>

<p class="callout warning">If no rule matches, the attachment is ignored.</p>

<p class="callout info">Squeeze uses the "PDFBox" software library to perform PDF merging or splitting. This library's availability is essential for attachment filtering. From Squeeze version 2.3.4, this library is included in the [System Checks](https://docs.squeeze.one/books/squeeze-2-admin-handbuch/page/system-information-und-prufungen), allowing quick identification of possible error causes.</p>

**In more detail:** rules for the **D**ocument and **A**ttachment type are resolved independently of each other: for each type, an exact sender match is looked up first, then domain, then (automatically for document rules; for attachment rules only if the global rule is still reached afterwards) the global rule (`*`). Among the resulting candidate rules, the final tiebreak is that the **longest filename pattern wins** — the table above simplifies this for the common case.

The filename pattern (`filenamepattern`) is evaluated as a shell wildcard pattern (`*`, `?`, `[abc]`). If the filename match fails, the MIME type is additionally checked as a fallback, provided the pattern is `*.pdf` or `*.xml`.

The `emailattachmentfilters` master data table is used to tell SQUEEZE whether and how attachments are relevant for recognition.

The table has the following structure:

<table id="bkmrk-name-description-mea"><thead><tr><th>Name</th><th>Description</th><th>Meaning</th></tr></thead><tbody><tr><td>id</td><td>ID</td><td>Unique technical ID</td></tr><tr><td>batchclassid</td><td>Batch Class ID</td><td>ID of the batch class for which the rule is defined</td></tr><tr><td>sender</td><td>Sender</td><td>Sender of the email (wildcards allowed, see note below)</td></tr><tr><td>filenamepattern</td><td>Filename Pattern</td><td>Filename filter (wildcards allowed)</td></tr><tr><td>type</td><td>Type</td><td>Relevant **D**ocument for extraction or accompanying **A**ttachment</td></tr><tr><td>singledocument</td><td>Single Document</td><td>Flag indicating whether the file should become a standalone document (**X**)</td></tr><tr><td>newbatchclassid</td><td>New Batch Class ID</td><td>If the document should be moved to a different batch class, the batch class ID of the new batch class goes here</td></tr><tr><td>newdocumentclassid</td><td>New Document Class ID</td><td>If a new document class should also be set, the document class ID goes here</td></tr></tbody></table>

#### Example configurations

##### Example

<table id="bkmrk-id-batch-class-sende"><thead><tr><th>ID</th><th>Batch Class</th><th>Sender</th><th>Pattern</th><th>Type</th><th>Single Document</th><th>new Batch Class</th><th>new Document Class</th></tr></thead><tbody><tr><td>1</td><td>1</td><td>\*</td><td>\*.pdf</td><td>D</td><td> </td><td> </td><td> </td></tr><tr><td>2</td><td>1</td><td>\*</td><td>AGB.pdf</td><td>A</td><td> </td><td> </td><td> </td></tr><tr><td>3</td><td>1</td><td>dexpro.de</td><td>INV\*.pdf</td><td>D</td><td>X</td><td> </td><td> </td></tr><tr><td>4</td><td>1</td><td><payment@dexpro.de></td><td>Avis\*.pdf</td><td>D</td><td>X</td><td>2</td><td>2</td></tr><tr><td>5</td><td>1</td><td>dexpro.de</td><td>\*.xml</td><td>A</td><td> </td><td> </td><td> </td></tr><tr><td>6</td><td>1</td><td><invoice@squeeze.one></td><td>\*.xml</td><td>D</td><td> </td><td> </td><td> </td></tr><tr><td>7</td><td>1</td><td><invoice@squeeze.one></td><td>\*.pdf</td><td>A</td><td> </td><td> </td><td> </td></tr></tbody></table>

##### Explanation of the rules

**Rule ID 1:** For every sender, every PDF of an email is treated as a document for extraction, and all PDFs are merged into one document.

**Rule ID 2:** For every sender, the PDF named **AGB.pdf** is kept as an attachment.

**Rule ID 3:** Only applies to senders on the **dexpro.de** domain; PDFs matching the filename pattern **INV\*.pdf** are kept as a **D**ocument. Additionally, every file matching this pattern becomes its own standalone document.

**Rule ID 4:** Only applies to sender <payment@dexpro.de>; PDFs matching the filename pattern **Avis\*.pdf** are kept as a **D**ocument. Additionally, every matching file becomes a standalone document of a new batch and document class.

**Rule ID 5:** Only applies to senders on the **dexpro.de** domain; XML files (e.g. an XRechnung) are kept as **A**ttachments. This assumes a valid PDF exists in the email (e.g. from Rule ID 3) that forms the main document.

**Rule ID 6 &amp; 7:** Only apply to sender **<invoice@squeeze.one>**; XML files (e.g. an XRechnung) are kept as a **D**ocument. Any additionally attached PDF documents are kept as **A**ttachments.

##### Note on the Sender field

<p class="callout warning">The Sender field does not allow wildcards combined with text.  
Allowed values:  
- \*  
- domain.de  
- foobaa@domain.de  
Not allowed are wildcard/string combinations:  
- \*domain\*  
- \*domain.de</p>

<p class="callout info">Rules can be defined to control the processing of emails containing both XRechnung documents and ZUGFeRD invoices.</p>

#### Processing multiple PDF invoices (incl. ZUGFeRD) in one email individually

##### Symptom

A sender sends several invoices as separate PDF attachments in a single email — for example several ZUGFeRD/hybrid invoices (PDF with embedded XML) in one bulk mail. Without matching configuration, these PDFs get merged into **one** document (PDF merge), or extraction ends up using the embedded XML of the "wrong" PDF.

##### Cause

If the same **D**ocument rule matches several attachments of one email and that rule's `singledocument` column is **empty**, all matching attachments are merged into **one** shared document. This applies regardless of whether the attachments are plain PDFs or ZUGFeRD/hybrid PDFs with embedded XML.

##### Fix: `singledocument = X`

If the matching rule has `singledocument` set to **X**, a **separate** document is created for **each** matching attachment — invoices are extracted individually instead of being merged.

**Example:**

<table id="bkmrk-id-batch-class-sende-1"><thead><tr><th>ID</th><th>Batch Class</th><th>Sender</th><th>Pattern</th><th>Type</th><th>Single Document</th><th>new Batch Class</th><th>new Document Class</th></tr></thead><tbody><tr><td>8</td><td>1</td><td><invoices@customer.de></td><td>\*.pdf</td><td>D</td><td>X</td><td> </td><td> </td></tr></tbody></table>

With this rule, every PDF file from an email sent by `invoices@customer.de` is treated as its own standalone document — no matter how many PDFs (including ZUGFeRD hybrids) are contained in the same email.

<p class="callout info">`newbatchclassid` / `newdocumentclassid` can additionally reroute each individually created document to a different batch or document class — e.g. when invoices and credit notes arrive together but need different processing.</p>

##### Interaction with ZUGFeRD Strict Mode

If ZUGFeRD Strict Mode is active (default-on since version 2.33, see [disabling it here](https://docs.squeeze.one/books/squeeze-2-admin-handbuch/page/zugferd-strictmode-deaktivieren)), matching PDF document rules are overridden at runtime in favor of XML processing (see the update notes below). The `singledocument` value carries over, however — so a rule with `singledocument = X` still processes each invoice individually even while Strict Mode is active.

Further background on XRechnung/ZUGFeRD processing: [Digital Formats (XML, XRechnung, ZUGFeRD)](https://docs.squeeze.one/books/squeeze-2-admin-handbuch/chapter/digitale-formate-xml-xrechnung-zugferd).

##### Troubleshooting

If invoices from a sender still get merged despite `singledocument = X`, check:

1. Whether a **different, longer-matching** rule (e.g. a global `*.pdf` rule without `singledocument`) is matching first — see "How it works" above on filename-pattern length priority.
2. Whether the rule is actually registered for the correct sender or domain (sender before domain before global).
3. The comparable [troubleshooting example](https://docs.squeeze.one/books/squeeze/page/e-mail-im-error-ordner-mit-no-valid-attachment-email-attachment-filters) for a similar case.

### Update Notes

#### Separation of attachments and document from Squeeze 1.10

In Squeeze 1.9 (and older), documents and attachments were handled differently on import, but were treated as one file in subsequent processing steps. The result was that the primary document to be processed and the attachments were merged into a single PDF and then extracted as if a single file had been imported.

From Squeeze 1.10, attachments are handled separately and are therefore not part of the document being extracted. This can also affect export interfaces that can only export one file per document (e.g. NavisionSoap) — these now only export the main document in the newer version; attachments are not exported.

<p class="callout info">If the pre-1.10 behavior should be retained, mark all attachments as documents in the attachment filters.</p>

#### Prioritization of XML invoices over PDF files from Squeeze 2.17

With the introduction of version 2.17, Squeeze's default behavior was adjusted so that invoices in XML format are preferred over PDF files. The background for this change is that customers and partners increasingly pointed out that invoice issuers often send documents in both XML and PDF format. Depending on configuration, this could lead to duplicates or processing errors.

To ensure consistent handling of documents by default, version 2.17 establishes that documents in XML format are given priority. This behavior can, however, be adapted to individual requirements via the rules described above. General prioritization of PDF files is currently not planned.

#### ZUGFeRD Strict Mode — Prioritizing XML for hybrid e-invoice formats

With the introduction of version 2.30 (April 2026), ZUGFeRD Strict Mode was introduced as a [batch class property](https://docs.squeeze.one/books/squeeze-2-admin-handbuch/page/stapelklassen-eigenschaften#bkmrk-zugferdstrictmode). When active, attachment filters are overridden in favor of XML processing. So for a ZUGFeRD process, existing filters that prefer PDFs are overridden. This behavior is logged to ensure traceable processing.

There is additionally a [system check](https://docs.squeeze.one/books/squeeze-2-admin-handbuch/page/system-information-und-prufungen) that can detect a possible misconfiguration.

Further information on Strict Mode can be found [here](https://docs.squeeze.one/link/500#bkmrk-%C2%A0).