Author: Product Team Status: Draft Last Updated: 2026-02-04
When documents fail ingestion, have validation errors, or fail to export to DATEV, users currently discover these issues only by checking the Orcha web UI. This requires users to actively monitor their document list and filter for problems — a manual, error-prone process.
For time-sensitive invoices (approaching payment deadlines, early-payment discounts), delayed discovery of processing failures can have real financial consequences. Users need to be notified proactively when something goes wrong, so they can take corrective action without constantly polling the UI.
Build an email notification system that:
| Metric | Target |
|---|---|
| Mean time from failure to user awareness | < 15 minutes (down from hours/days) |
| Percentage of actionable failures with notification sent | 100% |
| Email deliverability rate | > 98% |
| False positive rate (notifications for non-issues) | 0% (errors only, no warnings) |
Four categories of events trigger notifications. The guiding principle: notify when a document cannot reach DATEV, whether due to processing failure, validation errors that block export, export-time failures, or broken integrations. Soft warnings (tax ID format, IBAN format, fraud flags) do not trigger notifications — documents with only warnings export to DATEV normally, and users can review them there.
Trigger: Ingestion status becomes :failed (after max retry attempts exhausted).
What happened: The document could not be processed at all — OCR failed, extraction crashed, or a system error occurred. The document has no usable extracted data and cannot be exported.
Included in email:
Trigger: Ingestion completes successfully but needs_human_review = true due to validation errors (any validation check with status = :error), AND the tenant has an active DATEV connection.
Why this condition matters: Validation errors with status :error prevent auto-export to DATEV (the check-auto-export function skips documents with validation errors, and the UI disables the export button). Since these documents are stuck and can't reach DATEV, users need to be notified. If the tenant has no DATEV connection, validation errors don't block any workflow, so no notification is sent — users can review them in the Orcha UI at their convenience.
What happened: The document was processed and data was extracted, but critical validation checks failed. Examples: required fields missing (no invoice number, no VAT ID on EU invoice over EUR 250), financial math doesn't add up (line items don't sum to subtotal).
Included in email:
Trigger: DATEV export audit record status becomes FAILED or PARTIAL_SUCCESS.
What happened: The document was processed and validated, but could not be exported to the DATEV accounting system. This could be due to API errors, ledger configuration issues, or DATEV-side validation failures.
Included in email:
Trigger: One of the following system-level events occurs:
tenant_integration.is_active set to false with a disconnect_reason (e.g., ledger not found, token expired)doc_source_email.connection_status changes to token_refresh_failed (after 3 consecutive failures) or subscription_expiredWhat happened: A critical integration has stopped working. No documents can be exported (DATEV) or new documents can't be received from that email source.
Included in email:
noreply@mail.getorcha.comOrchaNotification emails are designed to help the user identify which original email or document is affected so they can investigate in their email client or re-submit the document. Emails do NOT contain deep links back into the Orcha UI.
Subject: [Orcha] Document processing error: {filename}
Hi,
A document in your Orcha workspace "{tenant_name}" encountered an error
during processing.
DOCUMENT DETAILS
Source: {email_subject} from {email_sender}
— OR —
Uploaded by {uploader_name}
File: {filename}
WHAT WENT WRONG
• {error_description_1}
• {error_description_2}
...
Please check the original email or document and re-submit if needed.
—
Orcha · Automated Document Processing
You received this email because your administrator configured you
to receive Orcha notifications for {tenant_name}.
When multiple documents fail within the consolidation window:
Subject: [Orcha] {count} documents need attention in {tenant_name}
Hi,
{count} documents in your Orcha workspace "{tenant_name}" encountered
errors during processing.
─────────────────────────────────────────────
DOCUMENT 1 — {error_type}
Source: {email_subject} from {email_sender}
File: {filename}
Error: {error_description}
─────────────────────────────────────────────
DOCUMENT 2 — {error_type}
Source: Uploaded by {uploader_name}
File: {filename}
Error: {error_description}
─────────────────────────────────────────────
... (up to 20 documents listed individually)
{if count > 20}
And {remaining_count} more. Please check Orcha for the full list.
{/if}
Please check the original emails or documents and re-submit if needed.
—
Orcha · Automated Document Processing
You received this email because your administrator configured you
to receive Orcha notifications for {tenant_name}.
Subject: [Orcha] Action required: {integration_name} disconnected
Hi,
A critical integration in your Orcha workspace "{tenant_name}" has
been disconnected.
WHAT HAPPENED
Integration: {integration_name}
(e.g., "DATEV accounting system" or "Gmail inbox user@company.com")
Reason: {disconnect_reason}
(e.g., "Authentication token expired" or
"Accounts payable ledger not found in DATEV")
IMPACT
{impact_description}
(e.g., "New invoices will not be exported to DATEV until reconnected."
or "Emails sent to user@company.com will not be processed until reconnected.")
WHAT TO DO
Please ask your Orcha administrator to reconnect this integration
in Orcha Settings.
—
Orcha · Automated Document Processing
You received this email because your administrator configured you
to receive Orcha notifications for {tenant_name}.
To prevent notification fatigue when many documents fail at once (e.g., a batch email with 20 attachments where all fail validation):
(tenant_id, event_category)Event categories for consolidation:
A new "Notifications" section is added to the existing Settings page, alongside the existing sections (Master Data, Email Connections, DATEV Integration).
┌─────────────────────────────────────────────────────┐
│ Notifications │
│ │
│ Send email notifications when documents fail │
│ processing or integrations disconnect. │
│ │
│ Notify the following team members: │
│ │
│ ┌───────────────────────────────────────────┐ │
│ │ ☑ alice@company.com (Alice Mueller) │ │
│ │ ☐ bob@company.com (Bob Schmidt) │ │
│ │ ☑ carol@company.com (Carol Weber) │ │
│ └───────────────────────────────────────────┘ │
│ │
│ All enabled members receive notifications for: │
│ • Document processing failures │
│ • Validation errors blocking DATEV export │
│ • DATEV export failures │
│ • Integration disconnections │
│ │
│ [ Save ] │
│ │
└─────────────────────────────────────────────────────┘
Any tenant member can access the Settings page and modify notification settings. (There is no admin role distinction today — all tenant members have equal access.)
1. Invoice arrives via email inbox (user@company.com)
2. Orcha processes the document (OCR, extraction, validation)
3. Validation finds: missing invoice number, missing issuer VAT ID
4. Document marked needs_human_review = true
5. Notification event created: "Validation error for document X"
6. Event enters consolidation buffer (5-minute window starts)
7. No more events arrive within 5 minutes
8. System sends email (Template A) to all enabled members:
- Alice and Carol receive the email
- Subject: "[Orcha] Document processing error: Invoice_Q4_2025.pdf"
- Body includes: email subject/sender, filename, specific missing fields
9. Alice checks her email inbox, finds the original invoice email,
and re-forwards a corrected version
1. Email arrives with 15 PDF attachments
2. Orcha creates 15 ingestion jobs
3. 12 succeed, 3 fail validation (missing required fields)
4. 3 notification events enter the buffer at ~same time
5. After 5-minute window: single consolidated email sent
- Subject: "[Orcha] 3 documents need attention in Acme GmbH"
- Lists all 3 documents with their specific errors
1. Invoice processes successfully, auto-export to DATEV triggers
2. DATEV API returns error: "Accounts payable ledger not found"
3. System attempts automatic ledger retry (existing behavior)
4. Retry also fails → DATEV integration deactivated
5. Two notification events:
a. DATEV export failure for the specific document (enters consolidation buffer)
b. Connection issue: DATEV disconnected (sent IMMEDIATELY)
6. Enabled members receive the connection issue email right away
7. 5 minutes later, they receive the export failure email for the document
1. Bob uploads "scan_001.pdf" via the Orcha UI
2. Processing fails after 3 retry attempts (corrupted PDF)
3. Notification event created
4. Email sent to enabled members:
- Source: "Uploaded by Bob Schmidt"
- File: "scan_001.pdf"
- Error: "Document processing failed after 3 attempts..."
5. Bob himself may also receive this email (if enabled),
which is acceptable — it serves as confirmation
1. Alice (tenant member) goes to Settings
2. Scrolls to "Notifications" section
3. Sees list of all tenant members with checkboxes
4. Enables herself and Carol, leaves Bob disabled
5. Clicks Save
6. From now on, Alice and Carol receive notification emails
1. No one has been enabled for notifications in Settings
2. Document fails validation
3. Notification event is created but has no recipients
4. No email is sent
5. The failure is still visible in the Orcha UI as before
| Edge Case | Behavior |
|---|---|
| Tenant has no members enabled for notifications | No emails sent. Events still logged internally for debugging. |
| Tenant has no active DATEV connection | Validation error notifications are suppressed (no export to block). Ingestion failures and connection issues still notify. |
| Same document fails ingestion, is retried, and fails again | Only notify on the FINAL failure (when attempt_count >= max_retry_attempts). Do not notify on intermediate retry failures. |
| Document fails validation AND DATEV export fails | Two separate notification events. May be consolidated into the same email if within the 5-minute window and same category, but validation errors and export failures are different categories so they'd be separate emails. |
| Member is removed from tenant while enabled for notifications | Membership deletion should cascade to remove their notification preference. |
| Email sending fails (SES error, bounced, etc.) | Log the failure. Do not retry notification emails — this is best-effort. Users still have the UI. |
| Consolidation buffer has events when system restarts | Events in the buffer are lost. Acceptable for v1 — these are best-effort notifications, not transactional guarantees. |
| DATEV auto-retry succeeds after initial failure | Do NOT send a notification. Only notify on terminal failure states. |
| Document is re-processed (new ingestion) after notification was sent | The new ingestion is treated independently. If it also fails, a new notification is sent. |
| Enabled member's email address is invalid/bouncing | SES will report bounces. For v1, log but don't auto-disable. Future: auto-disable after repeated bounces. |
| Two DATEV connection issues within 5 minutes | Each sent immediately (connection issues bypass consolidation). |
| 100 documents fail in one hour | First 10 emails sent (hourly cap). Remaining queued for next hour. Connection issues still sent immediately. |
New table or extension to track which members are enabled:
For debugging and monitoring, log each notification event:
:error status) trigger notifications, not warnings.mail.getorcha.com is already configured in SES for receiving. Sending from the same domain requires additional SES configuration (DKIM, SPF, DMARC). This needs to be verified/set up as part of implementation.