copilot-swe-agent[bot]
fe8e1c41cc
- Add aria-label to all Help nav links for better screen reader support - Fix Samba config examples: use authenticated user instead of guest ok=yes - Fix chmod 777 to chmod 770 with group-based access control - Add security notes about dedicated groups and passwords in how-to guides - Fix Python script to use os.environ.get() with explicit error messages - Add app-specific password comment to EmailIngestion.md config example Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# How to Set Up Automatic Document Ingestion via Email
|
||
|
||
Many devices (scanners, printers, fax services, and apps) can send documents as email attachments. This guide explains how to automatically route those attachments into DocuElevate.
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
The Email Ingestion workflow works like this:
|
||
|
||
```
|
||
Scanner/Device → Email (SMTP) → Monitored Mailbox → DocuElevate API → Processing & Storage
|
||
```
|
||
|
||
DocuElevate periodically checks a designated email inbox, downloads PDF/image attachments, and processes them through the standard document pipeline.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
- An email account dedicated to document ingestion (e.g., `scan@yourdomain.com`)
|
||
- IMAP access enabled for that account
|
||
- DocuElevate running with the Celery worker active
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
Add the following to your DocuElevate `.env` file:
|
||
|
||
```env
|
||
# Email ingestion settings
|
||
EMAIL_INGESTION_ENABLED=true
|
||
EMAIL_INGESTION_IMAP_HOST=mail.yourdomain.com
|
||
EMAIL_INGESTION_IMAP_PORT=993
|
||
EMAIL_INGESTION_IMAP_SSL=true
|
||
EMAIL_INGESTION_USERNAME=scan@yourdomain.com
|
||
# Use an app-specific password (Gmail, Outlook) – NOT your main account password.
|
||
# See the Security Considerations section below for details.
|
||
EMAIL_INGESTION_PASSWORD=your-app-specific-password
|
||
EMAIL_INGESTION_FOLDER=INBOX
|
||
EMAIL_INGESTION_INTERVAL=60 # Check every 60 seconds
|
||
EMAIL_INGESTION_MARK_SEEN=true # Mark emails as read after processing
|
||
EMAIL_INGESTION_ALLOWED_SENDERS= # Comma-separated allowlist (empty = allow all)
|
||
```
|
||
|
||
Restart DocuElevate after saving the configuration:
|
||
|
||
```bash
|
||
docker compose restart api worker
|
||
```
|
||
|
||
---
|
||
|
||
## Supported File Types
|
||
|
||
DocuElevate will process the following attachment types from emails:
|
||
|
||
| Type | Extension | Notes |
|
||
|------|-----------|-------|
|
||
| PDF | `.pdf` | Native support; OCR applied if not searchable |
|
||
| JPEG/PNG | `.jpg`, `.jpeg`, `.png` | Converted to PDF before processing |
|
||
| TIFF | `.tif`, `.tiff` | Common format from older scanners/fax |
|
||
| Multi-page TIFF | `.tif` | Full multi-page support |
|
||
|
||
---
|
||
|
||
## Setting Up Your Scanner/Device
|
||
|
||
### HP Printers – Scan to Email
|
||
|
||
See the detailed guide: [HP Enterprise Printer Setup](./HPPrinterSetup.md#option-a-scan-to-email--docuelevate-api-upload)
|
||
|
||
### Fujitsu ScanSnap – Send by Email
|
||
|
||
See the detailed guide: [ScanSnap Setup](./SnapScanSetup.md#method-3-scan-to-email--docuelevate)
|
||
|
||
### iOS/Android Scanning Apps
|
||
|
||
Most mobile scanning apps (Adobe Scan, Microsoft Lens, SwiftScan) can email scans:
|
||
|
||
1. Scan your document.
|
||
2. Use the app's **Share** or **Send** function.
|
||
3. Select **Email** and enter `scan@yourdomain.com`.
|
||
4. DocuElevate will pick up the attachment within the configured interval.
|
||
|
||
### Fax-to-Email Services
|
||
|
||
Services like eFax, RingCentral Fax, or Twilio Fax can forward incoming faxes as email attachments. Configure them to send to `scan@yourdomain.com`.
|
||
|
||
---
|
||
|
||
## Security Considerations
|
||
|
||
> **Important:** Only process emails from trusted sources to avoid ingesting malicious documents.
|
||
|
||
Use the `EMAIL_INGESTION_ALLOWED_SENDERS` setting to restrict which email addresses can submit documents:
|
||
|
||
```env
|
||
EMAIL_INGESTION_ALLOWED_SENDERS=scanner@office.com,printer@office.com,fax@office.com
|
||
```
|
||
|
||
DocuElevate will silently skip emails from addresses not in the allowlist.
|
||
|
||
Additionally:
|
||
|
||
- Use a **dedicated email account** solely for document ingestion
|
||
- Enable **app-specific passwords** (Gmail, Outlook) instead of your main account password
|
||
- Store credentials in environment variables, never in config files committed to version control
|
||
|
||
---
|
||
|
||
## Monitoring
|
||
|
||
Check the DocuElevate worker logs to verify email ingestion is running:
|
||
|
||
```bash
|
||
docker logs document_worker --follow
|
||
```
|
||
|
||
You should see log entries like:
|
||
|
||
```
|
||
INFO Email ingestion: checking inbox scan@yourdomain.com
|
||
INFO Email ingestion: found 3 new messages
|
||
INFO Email ingestion: processing attachment invoice-2024.pdf from printer@office.com
|
||
INFO Email ingestion: queued document ID 142 for processing
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
**No emails are being processed?**
|
||
→ Verify IMAP credentials and that IMAP is enabled on your mail server.
|
||
→ Check firewall rules: port 993 (SSL) or 143 (plain) must be open from DocuElevate to the mail server.
|
||
|
||
**Gmail not working?**
|
||
→ Enable "App Passwords" in your Google Account security settings.
|
||
→ Use the App Password (not your main Google password) for `EMAIL_INGESTION_PASSWORD`.
|
||
|
||
**Attachments processed but files are empty?**
|
||
→ Some email clients send inline images instead of attachments. Check the raw email source.
|
||
|
||
**Emails keep getting re-processed?**
|
||
→ Set `EMAIL_INGESTION_MARK_SEEN=true` to mark emails as read after processing.
|
||
→ Alternatively, configure a separate ingestion folder and move/delete emails after processing.
|
||
|
||
---
|
||
|
||
## Related Documentation
|
||
|
||
- [HP Enterprise Printer Setup](./HPPrinterSetup.md)
|
||
- [ScanSnap Setup](./SnapScanSetup.md)
|
||
- [Configuration Guide](../ConfigurationGuide.md)
|
||
- [Notifications Setup](../NotificationsSetup.md)
|