{% extends "documentation/base.html" %} {% block doc_content %}

Mail Parsing

Understand how BackupChecks automatically extracts backup information from email reports using parsers.

Overview

When emails are imported from your mailbox, BackupChecks automatically parses (analyzes) the email content to extract structured backup information. This eliminates the need to manually read each email and enter data.

Parsing extracts:

How Parsing Works

The mail parsing process follows these steps:

  1. Retrieval: Email is imported from Microsoft Graph and stored as a MailMessage record
  2. Preprocessing: Email body is normalized (line endings, character encoding) for consistent parsing
  3. Parser selection: All active parsers are evaluated in order to find a match
  4. Matching: Each parser checks if the email matches its criteria (sender, subject, body patterns)
  5. Parsing: When a match is found, the parser extracts backup information from the email
  6. Storage: Parsed data is stored in the database and linked to the email

Parsers

A parser is a piece of code that knows how to extract backup information from a specific backup software's email format.

Viewing Available Parsers

To see all available parsers:

  1. Navigate to the Parsers page in the main navigation menu (Admin only)
  2. The parsers page shows a table with all parsers and their configuration

Parser Information

Each parser entry shows:

Column Description
Name Unique identifier for the parser (e.g., veeam_backup_job)
Backup software The product this parser handles (e.g., Veeam, NAKIVO)
Backup type(s) Types of jobs this parser supports (e.g., Backup Job, Replication Job)
Match criteria Rules used to identify matching emails (sender, subject, body patterns)
Order Evaluation order (lower numbers are checked first)
💡 Read-Only Parser List:
The Parsers page is for viewing parser information only. Parsers cannot be enabled, disabled, or modified through the UI. Parser management is handled by the BackupChecks developer.

Match Criteria

Parsers use match criteria to determine if an email matches their expected format. Common criteria include:

Sender Match

Match based on the sender's email address:

Subject Match

Match based on the email subject line:

Body Match

Match based on email body content (not shown in table but used internally):

Supported Backup Software

BackupChecks includes built-in parsers for popular backup solutions:

Veeam Backup & Replication

Synology Active Backup

NAKIVO Backup & Replication

Other Supported Software

Additional parsers exist for:

💡 Requesting New Parsers:
If your backup software is not listed, contact BackupChecks support to request a new parser. Provide sample emails (.eml files) to help the developer create the parser. Parsers can only be created by the BackupChecks developer.

Parser Execution Order

When an email is parsed, BackupChecks evaluates parsers in a specific order based on their Order value. This is important because:

For example:

Order Parser Rationale
1 veeam_replication_job Specific Veeam job type - check before generic Veeam parser
2 veeam_backup_job Generic Veeam parser - fallback for other Veeam emails
10 synology_active_backup Unrelated to Veeam - order doesn't matter relative to Veeam

Re-parsing Emails

If parsing fails or produces incorrect results, you can re-parse emails after fixing the issue.

When to Re-parse

How to Re-parse

Re-parsing is only available for all inbox emails at once:

  1. Navigate to the Inbox page
  2. Click the Re-parse all button at the top of the page
  3. All emails in the inbox will be re-processed by all available parsers
💡 Re-parsing is Safe:
Re-parsing only updates parsed fields (backup software, job name, objects, etc.). It does not re-fetch the email from the mailbox or modify the original email content stored in the database.

Parsing Workflow Example

Here's how a typical Veeam backup email is parsed:

Example Email

Parsing Steps

  1. Import: Email is fetched from Graph API and stored
  2. Match: Veeam backup job parser matches (sender contains 'veeam.com', subject contains '[Veeam]')
  3. Extract: Parser extracts:
  4. Store: Data is saved to the database
  5. Display: Email appears in inbox with parsed fields populated

Troubleshooting Parsing Issues

Email Not Parsed (Blank Fields)

If an email shows blank Backup software or Job name:

  1. Check if a parser exists for this backup software on the Parsers page (Admin only)
  2. If no parser exists, contact support to request a new parser (provide sample .eml files)
  3. If a parser exists but the email wasn't parsed:

Incorrect Parsing Results

If parsing produces wrong job names or objects:

  1. Verify the email format hasn't changed (backup software update may have changed email templates)
  2. Contact support with sample .eml files to investigate the parsing issue
  3. The parser may need to be updated to handle the new email format

Partial Parsing

If some fields parse correctly but others don't:

Parser Limitations

Parsers have some inherent limitations:

Best Practices

Next Steps

{% endblock %}