Mailbox picture ingest — FAQ
Answers for tenant admins, support, and operations about how inbound email pictures are processed in ConPDS Checker.
See also: Mail rules · Mailboxes · Processing state · Container codes
Search this help site
The search box understands plain words, not JSON syntax.
| Search for | Finds |
|---|---|
| Container OCR | OCR scenarios, rule setup, mailbox OCR section |
| ocr enabled | Same (use a space — not "ocr_enabled": true) |
| mailbox ingest | This FAQ and mailboxes |
Do not paste rule JSON into search (e.g. "ocr_enabled": true) — quotes and colons break the search parser. Use Container OCR or ocr enabled instead.
In your rule editor, the JSON key is still "ocr_enabled": true on the ingest_images action.
1. Where must the container number appear?
Today (rule-driven extract): The container code comes from whatever field your mail rule extract block configures — typically subject, but also supported: body_text, body_html, and sender.
Not scanned today: attachment filename (Tier 3 — subject → body → filename cascade is planned in a follow-up change request).
With OCR enabled (ocr_enabled: true):
| Scenario | Stated container | ISO check digit | OCR on attachments? | Container used |
|---|---|---|---|---|
| A1 | Yes (from extract) | Valid | No | Stated code |
| A2 | Yes | Invalid | Yes — up to 25 attachments, stop at first hit | OCR result |
| B | No / empty | — | Yes | First OCR result |
Precedence when cascade is implemented (Tier 3): subject → body → filename.
2. Is ISO 6346 check-digit validation performed?
Without OCR: No — extracted codes are normalized (4 letters + 7 digits) but the check digit is not verified before insert.
With OCR enabled: Yes — Scenario A1 requires a valid ISO 6346 check digit on the stated code to skip OCR. Invalid stated codes trigger Scenario A2 (OCR fallback).
Helper: is_valid_iso6346() in conpds_utils.container_normalize.
3. What happens with an invalid number?
| Situation | Outcome |
|---|---|
Missing container_code or terminal in rule target (and OCR disabled) | Action failed — no pictures inserted |
No matching attachments + fail_if_no_attachments: true | Action failed |
| No matching attachments (default) | Action skipped |
| OCR enabled, no usable OCR result (A2/B) | Action failed (ocr_no_usable_result) — no insert |
| OCR enabled, OCR service unavailable but stated container present | Ingest continues with stated container |
| Partial attachment failures | partial_success — successful attachments kept |
There is no separate manual-review queue; configure report_recipients on the Mailbox to receive an ops email after each message is finalized.
4. Which files are accepted?
| Format | Accepted | Stored as |
|---|---|---|
| JPEG | Yes | JPEG (scaled, max 1280×1280 default) |
| PNG | Yes | Converted to JPEG |
| GIF | Yes | Converted to JPEG |
| HEIC | No (today) | Rejected |
| No | Rejected | |
| ZIP | No | Not extracted |
Tier 3 (deferred): HEIC/PDF/ZIP extraction and conversion.
5. Are files renamed?
No. The original attachment filename is stored in PICTURE_NAME.
6. Where do processed photos appear?
Pictures are inserted into ESTIMATE_PICTURES for the resolved container, terminal, and case date. They appear in:
- Gallery (container case)
- Upload history
- Ops report View case link (when terminal + container + case date are known)
7. How are duplicates treated?
Idempotency uses a stable mail_ingest_key derived from message id + attachment id (stored in PICTURE_SOURCE). Re-processing the same email skips duplicate inserts for the same attachment.
There is no content-hash deduplication across different emails.
8. Typical processing time
Default mailbox poll interval is ~5–10 minutes (see Mailboxes — poll_interval_minutes). OCR adds up to 25 sequential API calls × 15 s timeout each (typically ~1 s per call when the service is healthy).
Container OCR (Scenarios A/B)
Requires ocr_enabled: true on the ingest_images action. The OCR service is configured on the backend host only (not in rule JSON or tenant-admin UI).
Rule JSON — operator-configurable:
| Key | Default | Meaning |
|---|---|---|
ocr_enabled | false | Enable container OCR Scenarios A1/A2/B |
fail_if_no_attachments | false | No eligible attachments → failed (not skipped) |
Backend-fixed (not in rule JSON):
| Setting | Value | Meaning |
|---|---|---|
| Minimum OCR confidence | 85% | API must return checksum==1 and confidence ≥ 85 |
| Max attachments scanned | 25 | Stops at first usable OCR hit |
Picture metadata after OCR:
| Picture | OCR_SUCCESS | CASE_OCR_SUCCESS | Tags |
|---|---|---|---|
| Frame used for OCR | Y | Y | Mailbox OCR verified (A2) or Mailbox OCR autoprocessed (B) |
| Other attachments | A | Y | Same tag on all pictures in B; A2 tag on OCR frame only |
Scenario A1 (no OCR): all pictures keep A / Y (legacy default).
OCR service unavailable: when the backend OCR service cannot be reached, ingest continues using the stated container (if extract provided one). Pictures are still stored; the normal ops report is sent when report_recipients is configured.
Ops report email
Set report_recipients on the mailbox — see Mailboxes → Ops report recipients. After each message is finalized, Checker sends a branded HTML ops report with:
- Status: Success / Warning / Failure
- Matched rule, container number, received time, from (with email address), subject
- Received photos: count
- View case button → tenant gallery with signed
case_id(when case fields are known)
Status notes: Success includes completed EDI-only messages (search_pictures_and_send_edi succeeded and photo ingest was not attempted), even when Received photos is 0. Warning still applies when ingest ran (or was matched) but stored zero photos, and for partial success.
Plain-text part is included for mail clients that prefer it. Row-level spreadsheet details remain as a TSV attachment when present.
Developer log summaries and OCR confidence/checksum details are not included in the operator email.
Post-processing (mark read, move folder) is configured separately on the mailbox — see Mailboxes → Post-processing policy.
Sender notification email
When a rule includes send_notification after ingest_images, Checker emails the sender (or a fixed address) using a simple branded template by default:
- Status: Success / Warning / Failure
- Container number and received photo count
- One plain-language sentence
Set "simple_body": false in the action config only if you need a custom subject/body.
Use send_when_picture_count": "nonzero" (or legacy skip_if_no_pictures: true) so senders are not emailed when nothing was stored.
Zero-photo behaviour
When fail_if_no_attachments: true and the message has no eligible attachments, the ingest action returns failed (not skipped), so the processing state reflects a hard failure and ops reports show Failure.
Use send_when_picture_count": "nonzero" on send_notification so senders are not emailed when nothing was stored.