invoice-extractor-from-mail

name	invoice-extractor-from-mail
description	Designed for AP finance teams in cross-border trade enterprises. Automatically fetches invoice attachments from email (IMAP/OAuth) or local files, batch-extracts key fields (invoice number, amount, currency, etc.) via ADP, and exports results to Excel or business systems — no manual data entry required.

Invoice Extractor from Mail Skill

Invoice Extractor from Mail Skill is a dedicated invoice extraction skill officially built by Laiye Technology for finance teams in traditional manufacturing enterprises. Powered by Laiye ADP (Agentic Document Processing) core capabilities, it establishes an end-to-end automated document processing pipeline from email to business systems, compressing the previously tedious "find attachments -> manual data entry" workflow into a single automated execution: automatically retrieve attachments -> ADP intelligent extraction -> automatic field mapping -> one-click output to Excel / business systems, significantly improving cross-border procurement invoice processing efficiency and data accuracy.

New users get 100 free credits per month (refreshed monthly), equivalent to extracting approximately 66 invoice pages per month for free. ADP provides production-ready commercial APIs — integrate into your business system in as little as 1 hour.

---

Use Cases

• AP finance teams in traditional manufacturing enterprises can improve end-to-end processing efficiency for overseas invoice collection from email attachments, intelligent information extraction, and data entry during overseas procurement and cross-border settlement workflows.
• Audit teams in cross-border trade enterprises can batch-extract key information from overseas invoices and uniformly archive them during audit and compliance review workflows, improving document organization efficiency and completeness.
• Whether invoices are scattered across employee mailboxes or stored in local files, they can all be processed in batch with concurrency, dramatically improving email processing efficiency.

---

1. Core Design Principles

Guided decision tree, not an exhaustive matrix.

The Skill does not preset specific email types or business system platforms. Each step asks only one question, follows the corresponding branch based on the user's answer, and automatically skips unnecessary steps.

This means:

• New email types and new business system platforms do not require modifying the Skill; simply guide the user to provide the corresponding connection parameters during the conversation.
• The configuration file structure uses a universal type + params pattern, without defining a dedicated schema for each vendor.

---

2. User Workflow

First-time use:
  invoice-extract init
  |-- Q1: Where do the files come from?
  |   |-- "Email" -> Q2: Which email service? -> Collect connection parameters -> Q3: Filter criteria
  |   +-- "Local" -> Skip email configuration
  |-- Q4: ADP Key (required for first use)
  |-- Q5: Do you need field mapping? -> Yes -> Guide configuration / No -> Use ADP raw fields
  +-- Q6: Where should results be output?
      |-- "Local Excel file" (default)
      |-- "Upload to cloud platform" -> Which platform? -> Guide connection parameter configuration
      +-- "Push to business system API" -> Guide endpoint, authentication, and field mapping configuration

Daily use:
  invoice-extract run [--source mail|local] [--path ./invoices/] [--out ./result.xlsx]

---

3. Skill Internal Processing Flow

+----------------------------------------------------------+
|  Phase 1: Retrieve Files                                  |
|  +-----------+     +----------------+                     |
|  | Local     |     | Email          |                     |
|  | Files     |     | Attachments    |                     |
|  | Read      |     | Connect->Filter|                     |
|  | Directly  |     | ->Download     |                     |
|  +-----+-----+     +-------+--------+                     |
|        +--------+-----------+                             |
|                 v                                         |
|  Phase 2: Unified Adaptation                              |
|  Select optimal method by source: file_url / file_path    |
|  / base64                                                 |
|                 v                                         |
|  Phase 3: ADP Extraction                                  |
|  Auto-match invoice extraction app -> Call ADP API ->     |
|  Receive structured JSON                                  |
|                 v                                         |
|  Phase 4: Field Mapping (Optional)                        |
|  ADP raw fields -> Business field names                   |
|                 v                                         |
|  Phase 5: Output                                          |
|  Local Excel file / Upload to user-specified business     |
|  system                                                   |
+----------------------------------------------------------+

Detailed Description for Each Phase

Phase 1: Retrieve Files

Branch A -- Local Files:

• Supports user uploading a single file or specifying a local folder
• Supported formats: .jpeg, .jpg, .png, .bmp, .tiff, .pdf, .doc, .docx, .xls, .xlsx
• Supported size: 50 MB (if file > 20 MB, the ADP async interface is recommended)
• Folder mode automatically performs recursive scanning, filtering by file extension

Branch B -- Email Attachments:

• Ask the user: "What email service do you use?" (no preset options; the user specifies)
• Based on the user's answer, guide the collection of corresponding connection parameters:
  • Generic IMAP types (QQ / 163 / Gmail / Outlook / Feishu Mail / DingTalk Mail / Enterprise Mail / Exchange, etc.): User needs to provide: email address, authorization code, IMAP server address
  • API types (enterprise self-built mail open platforms / other systems providing Mail Open API): Corresponding app_id, app_secret, authentication method
  • Other unknown types: Ask the user what protocol the email service supports, and provide two guided paths: IMAP and API
• Collect filter criteria:
  • Whether to filter unread emails only
  • Attachment type whitelist
  • Sender whitelist
  • Time range
  • Maximum number of messages to process

Phase 2: Unified Adaptation

ADP supports three file input methods. The Skill automatically selects the optimal method based on the source:

Source	Adaptation Method	Priority Notes
Local files	Pass file_path (local path)	Most direct, no conversion needed
API-type attachments (providing a temporary download URL)	Pass file_url to ADP	No download needed, most efficient
Agent scenarios (file already uploaded to server)	Pass file_url to ADP	Same as above
IMAP-type attachments (binary stream download)	Download then pass file_path; if unable to write to disk, convert to base64	Prefer writing to disk and using path; fall back to base64

Phase 3: ADP Extraction (via CLI)

This Skill completes extraction through the ADP CLI tool (rather than calling the API directly). The CLI runs faster after installation and is simpler to integrate.

Prerequisites before first run:

1. Install ADP CLI

# Agent usage
npx skills add laiye-ai/adp-cli -y -g

# npm (recommended)
npm install -g @laiye-adp/agentic-doc-parse-and-extract-cli

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/laiye-ai/adp-cli/main/scripts/adp-init.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/laiye-ai/adp-cli/main/scripts/adp-init.ps1 | iex

2. Run adp config get to check credentials. If not configured, guide the user to execute adp config set --api-key <KEY> --api-base-url <URL>

a. The API key provided by the user can be saved as an environment variable to avoid repeated configuration each time ADP is called.
b. The base URL can be auto-populated based on the user's region without requiring user input. ADP provides independent public cloud access URLs for domestic and overseas users. Accessing the nearest endpoint ensures the highest speed and stability.

Region	Login Address	API Base URL
Chinese Mainland	https://adp.laiye.com/	https://adp.laiye.com/
Overseas Region	https://adp-global.laiye.com/	https://adp-global.laiye.com/

3. Run adp app-id list to get the invoice processing application ID. Subsequently, prefer using adp app-id cache

The app id should preferably be a preset invoice processing application. If the application list contains multiple invoice-processing-related applications, ask the user which one to use. After querying the app id list, the ID list can be saved to cache for faster future queries.

Core Flow: Execute Extraction

# Single file extraction -- local file
adp extract local <file_path> --app-id <app_id>

# Single file extraction -- URL
adp extract url <file_url> --app-id <app_id>

# Single file extraction -- Base64
adp extract base64 <base64> --app-id <app_id> --file-name <filename.ext>

# Large file async extraction and result querying
adp extract local <file_path> --app-id <app_id> --async
adp extract query <task_id>

# Batch extraction -- local folder (email attachments downloaded and placed in a folder)
adp extract local <folder_path> --app-id <app_id> --export <output_folder> 

# Batch extraction -- URL list file (one URL per line)
adp extract url <url_list_file> --app-id <app_id> --export <output_folder> 

Application Matching Logic:

• From adp app-id list / adp app-id cache, preferably select the preset invoice processing application. If the application list contains multiple invoice-processing-related applications, ask the user which one to use.
• If the preset template does not meet the user's needs, a custom extraction template can be created using adp custom-app create. Custom templates can be reused.

Phase 4: Field Mapping (Optional)

• To ensure that data exported from ADP can be smoothly imported into business systems, users can manually adjust field name mappings.
• If the user has configured mapping rules: Replace the ADP raw field name field_name with the mapped field name.
• If not configured: Use the raw field names returned by ADP directly.
• Mapping rules are grouped by document type and support post-run additions/modifications.

Phase 5: Output

Mode A (Default) — Local Excel File:

• Generates ./out/invoices_YYYYMMDD_HHMM.xlsx
• One row per document
• When outputting the Excel file, proactively ask the customer to verify the extraction results and whether they need to import the results into a business system

Mode B — Upload to Cloud Platform (file-based):

• Upload the generated Excel to cloud storage
• Ask the user which platform they use
• Based on the answer, guide the collection of corresponding authentication parameters and target location
• Common scenario references (for guidance only, not hardcoded):
  • Feishu Docs: Requires app_id + folder_token
  • DingTalk: Requires access_token + space_id
  • OneDrive/SharePoint: Requires OAuth + drive_id
  • Google Sheets: Requires service account + spreadsheet_id
  • Others: Ask the user for the platform's API documentation or upload method

Mode C — Push to Business System API (structured data):

• Push ADP's structured JSON extraction results directly to the user's business system (ERP, finance system, etc.) via HTTP API
• Guide the user to provide the following:
  1. API Endpoint: The receiving interface URL of the business system (e.g., https://erp.company.com/api/v1/invoices)
  2. Authentication: Bearer Token / API Key / OAuth 2.0 / Basic Auth
  3. Request Format: POST body structure (JSON) and the field names expected by the business system
  4. Field Mapping: Use field_map.json to map ADP's field_key to the target field names in the business system
• Push flow:

  ADP structured JSON → Field mapping (field_key → business system field name) → Assemble request body → POST to endpoint
  

• Common scenario references (for guidance only, not hardcoded):
  • SAP: Requires API endpoint + OAuth client credentials + field mapping
  • Kingdee/Yonyou: Requires API endpoint + App Key + App Secret + field mapping
  • Custom ERP: Requires user to provide API documentation; Skill guides configuration accordingly
• After push completes, display the push status for each record (success/failure); failed records are written to failed.log

---

4. Configuration File Structure

All configurations are stored in the ~/.invoice_extract/ directory, with chmod 600 permissions, and must not be committed to version control.

4.1 Source Configuration source.json

Universal structure: type + params, without defining a dedicated schema for each email platform.

{
  "type": "imap",
  "params": {
    "host": "imap.qq.com",
    "port": 993,
    "ssl": true,
    "username": "[e-mail]",
    "password": "your_authorization_code",
    "mailbox": "INBOX"
  }
}

{
  "type": "local",
  "params": {
    "path": "./invoices/"
  }
}

4.2 Filter Criteria filter.json (Email Mode Only)

{
  "unread_only": true,
  "with_attachment_only": true,
  "attachment_ext": ["pdf", "jpg", "jpeg", "png", "bmp", "tiff"],
  "sender_whitelist": [],
  "since": "2026-04-01",
  "until": "2026-04-30",
  "max_messages": 200
}

4.3 ADP Credentials (Managed via CLI)

# View current configuration
adp config get

# Set API Key
adp config set --api-key <KEY>

# Set API Base URL (Chinese Mainland: https://adp.laiye.com/ Overseas: https://adp-global.laiye.com/)
adp config set --api-base-url <url>

# Check balance
adp credit

4.4 Field Mapping field_map.json (Optional)

Full field schema reference: See refers/adp-invoice-fields.md for the complete ADP field definition, JSON structure, and mapping rules.

Mapping rules: The left-side key is the field_key from ADP output JSON (fixed identifier, cannot be modified). The right-side value is the user-defined display name (used as Excel column headers or business system target field names, freely modifiable by user).

Example:

{
  "invoice/receipt": {
    "invoice_number":             "Invoice Number",
    "invoice_date":               "Invoice Date",
    "supplier_name":              "Vendor",
    "total_amount":               "Grand Total",
    "line_items_description":     "Item Description",
    "line_items_total_amount":    "Line Amount"
  }
}

• If no mapping is configured, the Skill uses ADP's raw field_name as the display name
• For API push mode (Mode C), the values become the field names in the POST request body

4.5 Output Configuration output.json

{
  "type": "excel",
  "params": {
    "dir": "./out/"
  }
}

{
  "type": "cloud",
  "platform": "feishu",
  "params": {
    "app_id": "cli_xxxxxxx",
    "app_secret": "xxxxxxxxxxxxxxxx",
    "folder_token": "xxxxxxxx"
  }
}

{
  "type": "api",
  "params": {
    "endpoint": "https://erp.company.com/api/v1/invoices",
    "method": "POST",
    "auth_type": "bearer",
    "auth_token": "your_token_here",
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

API mode notes:

• auth_type supports: bearer (Bearer Token), api_key (in header or query), oauth2 (Client Credentials), basic (username + password)
• When pushing, the Skill assembles ADP extraction results into a JSON body according to field_map.json mapping, then POSTs each record to the endpoint
• If the business system supports batch APIs, the user can configure "batch": true and the Skill will combine multiple records into an array for a single push
• Before pushing, a preview is displayed (request body of the first record) for user confirmation before batch execution

---

5. Command Reference

# First-time configuration (guided wizard)
invoice-extract init

# Execute extraction (using saved configuration)
invoice-extract run

# Override source (extract from local files this time)
invoice-extract run --source local --path ./invoices/

# Override time range
invoice-extract run --since 2026-04-01 --until 2026-04-30

# Preview only (list files to be processed without actually extracting)
invoice-extract dry-run

# View/edit field mapping
invoice-extract map --edit

# Reconfigure a specific step
invoice-extract init --only source
invoice-extract init --only adp
invoice-extract init --only output

---

6. Excel Output Column Conventions

• Use the field_name from the ADP output JSON results as columns, with one field name corresponding to one column name.
• All results from one document are output as a single row.
• The Excel sheet is named "adp extract result".

---

7. Error Handling

Scenario	Behavior
Email connection failure	Terminate immediately, prompt to check connection parameters
Single file download/read failure	Skip, log to failed.log, continue processing the next file
ADP CLI not installed	Automatically execute the installation script
ADP credentials not configured / authentication failure	Terminate immediately, guide the user to execute adp config set --api-key <KEY>
ADP extraction failure (corrupted file / blank page, etc.)	Do not retry, log to failed.log
ADP async task timeout	Exponential backoff polling with adp extract query <task_id>, up to 3 retries
Cloud platform upload failure	Excel is still retained locally, prompt the user to check platform configuration
API push authentication failure (401/403)	Terminate immediately, prompt user to check if token/credentials have expired
API push single record failure (4xx/5xx)	Skip the record, log to failed.log, continue pushing the next one; summarize failure count after completion
API push endpoint unreachable	Terminate immediately, prompt user to check network and endpoint URL

---

8. Security and Privacy

• All credential files have chmod 600 permissions and must not be committed to version control.
• Email passwords/authorization codes are stored locally only and are not sent to ADP.
• ADP will transmit files to its server for processing. For sensitive files, please confirm data compliance first.
• Cache directory: ./.cache/invoice_extract/

---

9. Limitations

• Single file <= 50 MB (ADP limitation)
• Recommended <= 100 files per batch; please process in batches if exceeded.
• Encrypted emails (S/MIME) and password-protected PDFs are not supported.

10. Billing Rules

• New user benefit: 100 free credits per month, with no restrictions on which applications can be used.
• Credit consumption rules:

  Processing Stage	Cost
  Document parsing	0.5 credits/page
  Purchase order extraction	1.5 credits/page
  Invoice/receipt extraction	1.5 credits/page
  Custom extraction	1 credit/page

When credits are insufficient, you can log in to the ADP portal directly to top up. We provide independent public cloud access URLs for domestic and overseas users, which need to be configured separately by region. Accessing the nearest endpoint ensures the highest speed and stability.

• Chinese Mainland users: Login
  
• Non-Chinese Mainland users: Login
  

If you encounter any payment issues, please contact support: [e-mail]

---

11. Related Resources

• CLI Documentation: ADP CLI User Guide
• API Documentation: OpenAPI User Guide
• User Guide: Public Cloud Operation Manual
• Issue Tracker: GitHub Issues
• Problem Feedback: [e-mail]
• Official Website: Laiye ADP

---

Copyright (c) 2026 [Laiye Technology (Beijing) Co., Ltd.] All rights reserved.