📗 How to Fix Unparsed (Failed to Process) Documents

Before troubleshooting failed documents, it’s important to understand how template-based parsing works and why documents may fail to process.

The template-based parser requires a fixed and consistent document structure. If your emails or files change frequently, consider using an AI-powered or GPT-powered parser instead.

How template-based parsing works

When you create a template and highlight fields to extract, Parsio does not only remember the selected values.

It also remembers the context around each field — the text or HTML structure before and after the field.

For future documents to be parsed successfully:

• The surrounding context must remain the same

• The document structure must be consistent

If Parsio cannot find the same pattern in a new document, it will be marked as Failed to process.

Configure email auto-forwarding correctly

Some email clients (including Gmail) modify the email body when you manually forward an email.

Even if the email looks the same visually, the underlying HTML may change.

For this reason, we strongly recommend using automatic email forwarding instead of manual forwarding.

Common issue

Many users manually forward their first email, create a template, and see it parse successfully.
After enabling auto-forwarding, newly received emails may fail to process.

Solution: Create a new template using an auto-forwarded email, not a manually forwarded one.

Handle emails with slightly different layouts

Some services send multiple email formats for the same event or update their layout over time.

Parsio allows you to create multiple templates per mailbox. When parsing a document, Parsio:

1. Tries the template with the most fields

2. Falls back to the next matching template if parsing fails

In most cases, the solution is simply to create an additional template for the new layout.

Handle emails with missing fields

By design, Parsio must find all fields defined in a template for a document to be considered successfully parsed.

If some fields are missing in certain emails:

• Create one or more additional templates to cover those cases

This approach is usually more reliable than trying to force a single template to match all variations.

There is also an advanced trick that might be helpful.

Avoid dynamic data around fields

A common cause of failed parsing is dynamic data immediately before or after a field.

Example: ZIP and state

Email content: Zip & State: 77701 Texas

If you extract only the ZIP code:

• Text before ZIP → constant

• Text after ZIP → dynamic (state name changes)

Parsio may fail to match this pattern in future emails.

Solutions:

• Extract both ZIP and state as a single field, or

• Create a second field to extract the state separately

The same applies to timestamps.

Example: August 3rd, 2022 03:20 PM

You cannot reliably extract only the date unless you:

• Extract the full date and time, or

• Create separate Date and Time fields

Use the template debugger

Parsio includes a template debugger to help identify where parsing fails.

The debugger shows:

• The template document (left)

• The failed document (right)

Sections highlighted in red indicate where the pattern no longer matches.

Compare both sides to understand what changed and adjust your template accordingly.

Use text mode when HTML is unstable

Emails can be parsed as HTML or plain text.

If:

• HTML layouts change frequently, or

• Emails contain inconsistent formatting

Switching to text mode can reduce variability and improve template matching.

You can change this setting on the Mailbox settings page.

When templates are not the right solution

If:

• You need many templates to handle variations

• Emails change often

• Documents are PDFs with inconsistent layouts

The template-based parser may not be the best fit.

In these cases, consider using:

• AI-powered parser (pre-trained models)

• GPT-powered parser (flexible, layout-agnostic)

Still need help?