<!-- mcp-name: io.github.parseur/parseur-py -->

🤖🧙parseur-py

parseur-py is a modern Python client for the Parseur API.

It lets you manage mailboxes, documents, uploads, and webhooks programmatically or from the command line.

Built to help you automate document parsing at scale, parseur-py makes integrating with Parseur fast, easy, and Pythonic.

---

✨ Features

✅ List, search, and sort mailboxes
✅ Get mailbox details and schema
✅ List, search, filter, and sort documents
✅ Upload documents by file or email content
✅ Reprocess, skip, copy, or delete documents
✅ Manage custom webhooks for real-time events
✅ Listen to events in real time with a temporary webhook & tunnel
✅ Fully-featured Command Line Interface (CLI)
✅ Built-in MCP server to drive Parseur from AI assistants (Claude, Cursor, …)

---

⚠️ Disclaimer about Localtunnel

When using the parseur listen command (with event listener support), your data is forwarded through localtunnel servers.

These servers are not affiliated with Parseur and are not covered by Parseur’s Privacy Policy or Data Processing Agreement.

Data transmitted through localtunnel is not encrypted end-to-end.

➡️ Use this feature at your own risk.

For production-grade setups, we strongly recommend configuring your own secure webhook endpoint instead of relying on localtunnel.

---

🚀 Quick Start

Install the package

pip install parseur-py

With event listener support (Flask + localtunnel)

pip install "parseur-py[listener]"

With MCP server support (use Parseur from AI assistants)

pip install "parseur-py[mcp]"

Install the package from source

pip install -e .

Build documentation

pip install -r requirements-doc.txt
cd docs
make html

Run the tests

Unit tests run fully offline:

pytest

Integration tests hit the real Parseur API. They create and delete real resources, so they're skipped unless credentials are provided via the environment (never committed or stored in ~/.parseur.conf):

PARSEUR_API_BASE=https://api.parseur.com \
PARSEUR_API_KEY=sk_your_key \
pytest tests/integration -v

---

Initialize your configuration

Store your Parseur API credentials securely:

parseur init --api-key YOUR_PARSEUR_API_KEY

Your config is saved (by default) in:

~/.parseur.conf

---

Example usage

List all your mailboxes:

parseur list-mailboxes

List documents in a mailbox:

parseur list-documents 12345

Upload a file to a mailbox (add --wait to block until it is parsed, with a live progress bar):

parseur upload-file 12345 ./path/to/document.pdf
parseur upload-file 12345 ./path/to/document.pdf --wait

Download a mailbox's results as a file (stdout by default, or --output):

parseur download-mailbox 12345 --format csv -o results.csv     # whole mailbox
parseur list-parser-fields 12345                               # find a table field id
parseur download-field 12345 PF951 --format xlsx -o lines.xlsx  # a table field

Register a custom webhook:

parseur create-webhook --event document.processed --target-url https://yourserver.com/webhook --mailbox-id 12345

Listen to events in real time (requires [listener]):

parseur listen --event document.processed --mailbox-id 12345

With forwarding:

parseur listen --event document.processed --mailbox-id 12345 --redirect-url http://localhost --redirect-port 8000

---

📜 CLI Commands

Run:

parseur --help

for a full list of available commands.

Highlights

• init: Set your API token and (optional) base URL
• list-mailboxes: Search and sort mailboxes
• get-mailbox: Fetch a mailbox by ID
• get-mailbox-schema: Get the mailbox parsing schema
• list-parser-fields: List the fields extracted by a mailbox
• download-mailbox / download-field / download-export: Download results as a file (csv/json/xlsx)
• list-export-configs: List a mailbox's custom export configurations
• list-documents: Advanced document search, filtering, sorting
• get-document / get-document-logs: Fetch document details and processing logs
• reprocess-document / skip-document / copy-document / split-document / reverse-split-document / delete-document: Document lifecycle operations
• upload-file / upload-text: Upload new documents (add --wait for synchronous parsing)
• upload-folder: Upload every file matching a glob path
• create-webhook / get-webhook / list-webhooks / delete-webhook: Create, get, list, and delete custom webhook integrations.
• enable-webhook / pause-webhook: Activate or pause a webhook for a specific mailbox.
• listen: Create a temporary webhook and listen to events in real time (with optional redirect & silent mode)
• mcp: Run the Parseur MCP server so AI assistants can manage your account (requires [mcp])

---

🔎 Advanced Search & Filtering

Mailbox listing supports:

• Search by name or email prefix
• Sort by:
  • name
  • document_count
  • template_count
  • PARSEDOK_count (processed)
  • PARSEDKO_count (failed)
  • QUOTAEXC_count (quota exceeded)
  • EXPORTKO_count (export failed)

Document listing supports:

• Search in:
  • document ID
  • document name
  • template name
  • email addresses (from, to, cc, bcc)
  • document metadata header
• Sort by:
  • name
  • created (received date)
  • processed date
  • status
• Filter by:
  • received_after / received_before dates
• Include parsed result in response

---

⚡ Webhooks Support

Easily register custom webhooks for events like:

• document.processed
• document.processed.flattened
• document.template_needed
• document.export_failed
• table.processed
• table.processed.flattened

Your webhook endpoint will receive POST notifications with Parseur payloads, enabling real-time integrations with your systems.

---

🤖 MCP Server (AI assistants)

parseur-py ships an MCP server that exposes Parseur as tools any MCP-compatible AI assistant (Claude Desktop, Codex, Cursor, Claude Code, and others) can call directly.

Start with MCP.md if you want to connect Parseur to Claude, Codex, or Cursor. It separates the recommended user setup from the developer setup and includes copy-paste configs for each client.

The full tool reference is in MCP-TOOLS.md, and maintainer publishing instructions are in MCP-PUBLISHING.md.

Quick zero-install command:

uvx --from "parseur-py[mcp]" parseur-py

---

🛠️ Configuration

Your API token and settings are stored in a simple INI file:

[parseur]
api_token = YOUR_API_KEY
base_url = https://api.parseur.com

You can customize the path by setting `--config-path` in your calls if needed.

---

🐍 Python Client Usage

Beyond the CLI, parseur-py is a standard Python library. Example:

import parseur

parseur.api_key = "YOUR_API_KEY"

for mailbox in parseur.Mailbox.list():
    print(mailbox.name)

Per-call API key override

Every method accepts an optional api_key argument that takes priority over the global parseur.api_key for that single call — useful for multi-account or multi-tenant code:

parseur.Mailbox.list(api_key="sk_account_a")
parseur.Document.upload_file(123, "invoice.pdf", api_key="sk_account_b")

---

📖 Documentation

• Parseur Official API Docs
• This package mirrors Parseur’s REST API, adding pagination handling, schema support, and convenient CLI commands.

---

💼 License

MIT License

---

🤝 Contributing

We welcome contributions! Please:

1. Fork the repo
2. Create your feature branch (git checkout -b feature/foo)
3. Commit your changes (git commit -am 'Add foo')
4. Push to the branch (git push origin feature/foo)
5. Open a pull request

---

✨ Credits

Developed with ❤️ by the Parseur team.

---

Parseur is the easiest way to automatically extract data from emails and documents. Stop copy-pasting data and automate your workflows!