Skip to main content

Processing State

Complete guide to monitoring and managing email processing activity.

The Processing State page provides visibility into how emails are processed by your mail rules. Every matched email creates a processing state record from arrival through completion.

Table of contents​

  1. Introduction
  2. Overview
  3. Processing states table
  4. Understanding status and results
  5. Manual polling
  6. Monitoring and progress
  7. Downloading logs
  8. Advanced actions
  9. Troubleshooting

Introduction​

Use this page to monitor processing activity, view detailed logs, manually trigger mailbox polling, and troubleshoot issues. It is the central dashboard for automated email processing.

What you can do​

  • Filter by mailbox, date range, and status
  • Search subject, sender, and other fields
  • Download logs for each processing run
  • Run now / Force run to poll mailboxes immediately
  • Process now / Stop / Delete record per message

Overview​

When an email arrives in a configured mailbox:

  1. The system polls for unread emails (automatically or manually)
  2. Each unread email is matched against Mail rules
  3. If a rule matches, a processing state is created with status pending
  4. Actions run (ingest images, parse spreadsheet, send EDI, etc.)
  5. The processing state updates with progress and final result
  6. Detailed logs are generated for each step

Processing states table​

The table shows processed emails, newest first by default (infinite scroll, 25 records initially).

Table columns​

ColumnDescription
StatusPending → Processing → Completed/Failed (sortable)
ResultMatched rule name or error message
MailboxSource mailbox (filterable)
SubjectEmail subject (sortable)
FromSender address (sortable)
ReceivedWhen the email was received (tenant timezone)
ProcessedWhen processing completed (default sort: newest first)
ErrorError message if failed
DownloadDownload plain-text .log file

Filtering and sorting​

  • Status filter — All, Pending, Processing, Completed, Failed
  • Mailbox filter — Specific mailbox
  • Search — Text across subject, from, and other fields
  • Column sorting — Click headers; click Processed to reset default sort

Understanding status and results​

Processing status​

StatusMeaning
PendingQueued, not started yet
ProcessingIn progress; may show steps like "Parsing spreadsheet"
CompletedFinished successfully
FailedError — check Error column and download logs
Waiting childrenWaiting for child tasks (e.g. spreadsheet row chunks)

Result column​

  • Rule name — When a mail rule matched and processed the email
  • Error message — When processing failed
  • Empty — When no rule matched

Manual polling​

Run now​

  1. Select one or more mailboxes (or All mailboxes)
  2. Click Run now
  3. Unread emails are fetched immediately
  4. New rows appear as emails are processed
Behaviour

Run now respects poll locks and skips mailboxes already being polled. Safe to click multiple times.

Force run​

Same as Run now, but clears existing poll locks first.

Use with caution

Force run may interrupt an ongoing poll and cause duplicate processing. Use when a mailbox appears stuck.

Monitoring and progress​

Unread email counts​

  • Total unread across all mailboxes (e.g. "7 unread remaining")
  • Per-mailbox counts update automatically

Processing indicator​

  • Processing badge — Count of emails currently processing
  • Status updates — Rows update in real time
  • Progress steps — Detailed status in the Status column

"Enqueued" message​

After Run now or Force run, shows how many mailbox polls were queued. Disappears when polling completes.

Downloading logs​

  1. Find the email in the table
  2. Click the download icon in the Download column
  3. Open the .log file in any text editor

Log file contents​

  • Message — From, subject, received time, attachment list
  • Processing summary — Status, matched rules, child task counts, errors
  • Chronological steps — Rule matching, extracts, EDI, spreadsheet rows, JSON details

What to look for when troubleshooting​

  • ERROR entries
  • Which rule matched and why
  • Action execution (ingest, parse, EDI)
  • Code mapping lookups
  • EDI send results
  • Email notification delivery

Advanced actions​

Pause / resume mail ingestion​

  • Pause — Stops automatic polling; manual Run now still works
  • Resume — Restarts automatic polling
Use case

Pause during maintenance or rule testing. Remember to resume when done.

Clear poll lock​

If a mailbox appears stuck:

  1. Open More actions
  2. Select mailbox under Clear poll lock
  3. Click Clear lock
Warning

Only clear locks when certain the mailbox is stuck. Clearing during an active poll may cause duplicates.

Process now (per message)​

Play icon for pending, processing, and failed rows — enqueues that message's worker immediately.

  • Not shown for completed, partial_success, poison, or waiting_children
  • Blocked when mail ingestion is paused
  • If no row exists yet, use Run now on the mailbox first

Stop (per message)​

Stop icon marks the run as stopped by the operator.

Delete record (rerun from scratch)​

Trash icon deletes the processing row, logs, and spreadsheet jobs. The email remains in the mailbox. If still unread, the next poll creates a fresh run.

Not available while processing or waiting_children — use Stop first.

Troubleshooting​

Emails not appearing in the table​

  • Verify mailbox is active in Mailboxes
  • Check mail rules are active
  • Click Run now; then Process now on existing rows
  • Check unread counts and mailbox connection

Emails stuck in Pending or Processing​

  • Wait — large emails or complex rules take time
  • Check if ingestion is paused
  • Review Error column and download logs
  • Clear poll lock if stuck

Processing fails with errors​

Retry spreadsheet processing after failure​

  • Keep the message unread
  • Use Run now or Force run on the mailbox
  • Fix duplicate parse_spreadsheet rules before retrying

"Run now" doesn't process emails​

  • Check ingestion not paused
  • Verify unread emails exist
  • Try Force run or clear poll lock
  • Test mailbox connection
  • Verify active mail rules

Can't download log file​

  • Check browser download settings
  • Logs may be incomplete for pending/processing states

See also: Mailboxes, Mail rules, Code mappings