parseur¶

Submodules¶

Attributes¶

`FAILED_STATUSES`
`FINAL_STATUSES`
`PENDING_STATUSES`
`SUPPORTED_FILE_EXTENSIONS`

Classes¶

`Config`
`Document`	Document resource providing class-based API access.
`DocumentOrderKey`	Enumeration of supported document sorting keys.
`ParseurEvent`	Enumeration of supported Parseur webhook event types.
`ExportConfig`	Manage a mailbox's export configurations and download their exports.
`EmailProcessing`	How a mailbox processes incoming emails and their attachments.
`Mailbox`
`MailboxOrderKey`	Enumeration of supported mailbox sorting keys.
`Metadata`	Per-document metadata columns a mailbox can expose.
`SenderFilter`	How a mailbox filters incoming senders.
`ParserField`	Manage the fields (`parser_object_set`) extracted by a mailbox.
`DocumentStatus`	Enum for Parseur document processing statuses.
`ExportType`	Type of an export configuration.
`AIEngine`	Enumeration of AI engines that can be set on a mailbox when creating or
`DateFormat`	How to read ambiguous dates in documents (the `input_date_format`).
`DecimalSeparator`	Decimal separator for numbers in documents (the `decimal_separator`).
`FieldFormat`	Enumeration of the data formats a parser field can have.
`Webhook`

Functions¶

to_json(data[, indent, sort_keys, ensure_ascii])

Serialize a Python object to a JSON-formatted string with ISO datetime support.

Package Contents¶

class parseur.Config(config_path: str)[source]¶

config_path¶

api_key = None¶

api_base = None¶

load()[source]¶

save()[source]¶

class parseur.Document[source]¶

Document resource providing class-based API access.

classmethod from_response(data: Dict) → Dict[source]¶: Validate and deserialize a single document dict.

classmethod log_from_response(data: Dict) → Dict[source]¶: Validate and deserialize a single document log dict.

classmethod upload_from_response(data: Dict) → Dict[source]¶: Validate and deserialize a document upload response dict.

classmethod notifications_from_response(data: Dict) → Dict[source]¶

Deserialize the notification_set returned by async actions.

Asynchronous endpoints (reprocess, copy, split, reverse_split) reply with {"notification_set": {<level>: [messages]}} rather than a document; this extracts and validates that inner mapping.

classmethod iter(mailbox_id: int, *, search: str | None = None, order_by: DocumentOrderKey | None = None, ascending: bool = True, received_after: datetime.datetime | None = None, received_before: datetime.datetime | None = None, with_result: bool = False, api_key: str | None = None) → Iterable[Dict][source]¶

Yield all documents in a mailbox with pagination and filtering.

Parameters:

mailbox_id – The mailbox ID to retrieve documents from.
search (str) –
Search string to filter documents. The search query parameter searches the following properties:
- document id (exact match)
- document name
- template name
- from, to, cc, and bcc email addresses
- document metadata header
order_by (DocumentOrderKey) – Enum value specifying the sorting field.
ascending (bool) – Whether to sort in ascending order (True) or descending order (False).
received_after (datetime.datetime) – Filter for documents received after this date (converted to UTC YYYY-MM-DD).
received_before (datetime.datetime) – Filter for documents received before this date (converted to UTC YYYY-MM-DD).
with_result (bool) – Whether to include the parsed result in the returned documents.
api_key – Optional API key overriding the global one for this call.

Yield dict:

Each yielded dictionary represents a document.

classmethod list(mailbox_id: int, *, search: str | None = None, order_by: DocumentOrderKey | None = None, ascending: bool = True, received_after: datetime.datetime | None = None, received_before: datetime.datetime | None = None, with_result: bool = False, api_key: str | None = None) → List[Dict][source]¶

classmethod retrieve(document_id: str, *, api_key: str | None = None) → Dict[source]¶: Retrieve document details, deserialized.

classmethod reprocess(document_id: str, *, api_key: str | None = None) → Dict[source]¶

Re-run parsing on a document.

Asynchronous: the API queues the work and returns a notification_set ({<level>: [messages]}), not the document. Poll with wait() or retrieve() to observe the result.

classmethod skip(document_id: str, *, api_key: str | None = None) → Dict[source]¶: Mark a document as skipped and return the updated document.

classmethod copy(document_id: str, target_mailbox_id: int, *, api_key: str | None = None) → Dict[source]¶

Copy a document into another mailbox.

Asynchronous: the new document is created in the background, so the API returns a notification_set ({<level>: [messages]}), not a document.

classmethod split(document_id: str, *, api_key: str | None = None) → Dict[source]¶

Split a multi-page document following the mailbox’s split settings.

Asynchronous: returns a notification_set ({<level>: [messages]}). The mailbox must have at least one splitting method enabled and the document must be splittable, otherwise the API responds with an error.

classmethod reverse_split(document_id: str, *, api_key: str | None = None) → Dict[source]¶

Undo a previous split of a document.

Asynchronous: returns a notification_set ({<level>: [messages]}). Only valid on a document that was split.

classmethod logs(document_id: str, *, api_key: str | None = None) → List[Dict][source]¶

classmethod delete(document_id: str, *, api_key: str | None = None) → bool[source]¶

classmethod upload_file(mailbox_id: int, file_path: str, *, api_key: str | None = None) → Dict[source]¶

Upload a local file to a mailbox.

The file is read from the filesystem of the machine running this code (for an MCP server, that is the server’s machine — usually the same as the client when launched locally by Claude Desktop). ~ is expanded.

Raises:: FileNotFoundError – If no readable file exists at file_path.

classmethod batch_upload_files(file_paths: List[str], mailbox_id: int, *, api_key: str | None = None) → Iterable[Dict][source]¶

classmethod upload_folder(mailbox_id: int, folder_path: str, *, api_key: str | None = None) → Iterable[Dict][source]¶

classmethod upload_text(recipient: str, subject: str, sender: str | None = None, body_html: str | None = None, body_plain: str | None = None, *, api_key: str | None = None) → Dict[source]¶

static _uploaded_document_id(upload: Dict) → str[source]¶

Extract the document id from an upload response.

upload_text returns it as DocumentID; file uploads return it as the first entry of attachments.

classmethod wait(document_id: str, *, api_key: str | None = None, on_poll=None) → Dict[source]¶

Poll a document until it reaches a final (non-pending) status.

A document is still pending while its status is INCOMING, ANALYZING or PROGRESS; any other status (PARSEDOK, PARSEDKO, EXPORTKO, …) is considered final. The cadence (POLL_INTERVAL = 5s) and budget (MAX_WAIT = 10 min) are fixed.

Parameters:

document_id – ID of the document to poll.
api_key – Optional API key overriding the global one for this call.
on_poll – Optional callback on_poll(elapsed_seconds, status) invoked after every status check (e.g. to render progress).

Returns:

The document once it reaches a final status.

Raises:

TimeoutError – If still pending after MAX_WAIT seconds.

classmethod upload_file_and_wait(mailbox_id: int, file_path: str, *, api_key: str | None = None, on_poll=None) → Dict[source]¶

Upload a file and block until the document reaches a final status.

Returns:: The processed document.
Raises:: TimeoutError – If processing does not finish within MAX_WAIT.

classmethod upload_text_and_wait(recipient: str, subject: str, sender: str | None = None, body_html: str | None = None, body_plain: str | None = None, *, api_key: str | None = None, on_poll=None) → Dict[source]¶

Upload text/email content and block until the document is final.

Returns:: The processed document.
Raises:: TimeoutError – If processing does not finish within MAX_WAIT.

class parseur.DocumentOrderKey[source]¶

Bases: str, enum.Enum

Enumeration of supported document sorting keys.

Used with the order_by parameter to specify sorting in list_documents and yield_documents.

Members:

NAME: Sort by document name.
CREATED: Sort by created/received date.
PROCESSED: Sort by processed date.
STATUS: Sort by document status.

NAME = 'name'¶

CREATED = 'created'¶

PROCESSED = 'processed'¶

STATUS = 'status'¶

parseur.FAILED_STATUSES[source]¶

parseur.FINAL_STATUSES[source]¶

parseur.PENDING_STATUSES[source]¶

class parseur.ParseurEvent[source]¶

Bases: str, enum.Enum

Enumeration of supported Parseur webhook event types.

Use these values when registering webhooks to specify which event to listen for.

Members:

DOCUMENT_PROCESSED: Document processed successfully.
DOCUMENT_PROCESSED_FLATTENED: Document processed as flat data.
DOCUMENT_TEMPLATE_NEEDED: Document processing failed (template needed).
DOCUMENT_EXPORT_FAILED: Export of the document failed.
TABLE_PROCESSED: A table field row was processed.
TABLE_PROCESSED_FLATTENED: A table field row (flattened) was processed.

DOCUMENT_PROCESSED = 'document.processed'¶

DOCUMENT_PROCESSED_FLATTENED = 'document.processed.flattened'¶

DOCUMENT_TEMPLATE_NEEDED = 'document.template_needed'¶

DOCUMENT_EXPORT_FAILED = 'document.export_failed'¶

TABLE_PROCESSED = 'table.processed'¶

TABLE_PROCESSED_FLATTENED = 'table.processed.flattened'¶

is_table_event() → bool[source]¶

class parseur.ExportConfig[source]¶

Manage a mailbox’s export configurations and download their exports.

An export config selects which columns (items) to export for the mailbox (PARSER) or one of its table fields (PARSER_FIELD). Use available_fields() to discover the columns you can include, and download() to fetch the resulting CSV/XLSX.

classmethod from_response(data: Dict) → Dict[source]¶: Validate/deserialize an export config and resolve its download URLs.

classmethod iter(mailbox_id: int, *, api_key: str | None = None) → Iterable[Dict][source]¶: Yield all export configurations of a mailbox (handles pagination).

classmethod list(mailbox_id: int, *, api_key: str | None = None) → List[Dict[str, Any]][source]¶: Retrieve all export configurations of a mailbox as a list.

classmethod retrieve(mailbox_id: int, export_config_id: int, *, api_key: str | None = None) → Dict[str, Any][source]¶: Retrieve a single export configuration by its ID.

classmethod create(mailbox_id: int, name: str, items: List[str], *, export_type: str | parseur.schemas.export_config.ExportType = ExportType.PARSER.value, parser_field_id: str | None = None, api_key: str | None = None) → Dict[str, Any][source]¶

Create an export configuration.

Parameters:

mailbox_id – ID of the mailbox.
name – Name of the export configuration.
items – Columns to export (see available_fields()).
export_type – PARSER (document-level) or PARSER_FIELD (a table field). See ExportType.
parser_field_id – The table field id, required for PARSER_FIELD exports (e.g. “PF1”).
api_key – Optional API key overriding the global one for this call.

Returns:

The created export configuration.

Raises:

marshmallow.ValidationError – If a value is invalid.

classmethod update(mailbox_id: int, export_config_id: int, *, api_key: str | None = None, **fields: Any) → Dict[str, Any][source]¶

Update an export configuration. Only the fields you pass are changed.

Parameters:: fields – Writable fields (name, type, items, parser_field_id).
Raises:: marshmallow.ValidationError – If a value is invalid or an unknown field is provided.

classmethod delete(mailbox_id: int, export_config_id: int, *, api_key: str | None = None) → bool[source]¶: Delete an export configuration. Returns True on success.

classmethod available_fields(mailbox_id: int, *, api_key: str | None = None) → List[Dict[str, Any]][source]¶

List the groups of columns that can be exported for a mailbox.

Returns one entry for the document-level export (PARSER) and one per table field (PARSER_FIELD), each with the items you can pass to create().

classmethod download(mailbox_id: int, export_config_id: int, fmt: str = 'csv', *, api_key: str | None = None) → bytes[source]¶

Download the configured export and return its raw bytes.

Parameters:: fmt – "csv" (default) or "xlsx" ("xls" is accepted).
Returns:: The export file content as bytes.

class parseur.EmailProcessing[source]¶

Bases: str, enum.Enum

How a mailbox processes incoming emails and their attachments.

Maps to the process_attachments / attachments_only mailbox flags (see Mailbox.set_email_processing()).

EMAILS_AND_ATTACHMENTS = 'emails_and_attachments'¶

EMAILS_ONLY = 'emails_only'¶

ATTACHMENTS_ONLY = 'attachments_only'¶

class parseur.Mailbox[source]¶

classmethod from_response(data: Dict) → Dict[source]¶

Deserialize a single mailbox API response.

Parameters:: data – Raw API response dictionary.
Returns:: Validated and transformed mailbox dictionary.

classmethod iter(*, search: str | None = None, order_by: MailboxOrderKey | None = None, ascending: bool = True, api_key: str | None = None) → Iterable[Dict][source]¶

Yield all mailboxes with pagination and optional filtering or sorting.

Parameters:: api_key – Optional API key overriding the global one for this call.

classmethod list(*, search: str | None = None, order_by: MailboxOrderKey | None = None, ascending: bool = True, api_key: str | None = None) → List[Dict[str, Any]][source]¶: Retrieve all mailboxes as a list.

classmethod retrieve(mailbox_id: int, *, api_key: str | None = None) → Dict[str, Any][source]¶: Retrieve a single mailbox by ID.

classmethod schema(mailbox_id: int, *, api_key: str | None = None) → Dict[str, Any][source]¶: Get the schema for a mailbox.

classmethod create(name: str | None = None, *, ai_engine: str | None = None, api_key: str | None = None, **fields: Any) → Dict[str, Any][source]¶

Create a new mailbox (parser).

Parameters:

name – Optional display name. Parseur generates one if omitted.
ai_engine – AI engine (see AIEngine). Defaults to the AI Vision engine (GCP_AI_2), which understands layout and images.
api_key – Optional API key overriding the global one for this call.
fields – Any other writable mailbox fields (e.g. ai_instructions, parser_object_set) forwarded to the API.

Returns:

The created mailbox object as a dictionary.

Raises:

marshmallow.ValidationError – If a value is invalid or an unknown/read-only field is provided.

Defaults applied on creation (each overridable):

ai_engine is set to the AI Vision engine (GCP_AI_2).
When no fields are predefined, identification_status is set to REQUESTED so Parseur auto-detects fields from the first documents. If you predefine parser_object_set, identification is left to the API default so those fields are used as-is (REQUESTED would put the mailbox in identification mode and skip extraction).

classmethod update(mailbox_id: int, *, api_key: str | None = None, **fields: Any) → Dict[str, Any][source]¶

Update an existing mailbox.

Only the fields you pass are changed; others are left untouched.

Parameters:

mailbox_id – ID of the mailbox to update.
api_key – Optional API key overriding the global one for this call.
fields – Writable mailbox fields to update (e.g. name, ai_engine, ai_instructions, retention_policy).

Returns:

The updated mailbox object as a dictionary.

Raises:

marshmallow.ValidationError – If a value is invalid or an unknown/read-only field is provided.

classmethod rename(mailbox_id: int, name: str, *, api_key: str | None = None) → Dict[str, Any][source]¶

Rename a mailbox.

Parameters:

mailbox_id – ID of the mailbox.
name – New display name.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod set_ai_engine(mailbox_id: int, ai_engine: parseur.schemas.mailbox.AIEngine | str, *, api_key: str | None = None) → Dict[str, Any][source]¶

Set the AI engine a mailbox uses to extract data.

Parameters:

mailbox_id – ID of the mailbox.
ai_engine – One of AIEngine.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod set_ai_instructions(mailbox_id: int, instructions: str | None, *, api_key: str | None = None) → Dict[str, Any][source]¶

Set the natural-language extraction instructions for a mailbox.

Parameters:

mailbox_id – ID of the mailbox.
instructions – Instructions text, or None to clear them.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod split_by_ai(mailbox_id: int, instructions: str | None = None, *, enabled: bool = True, api_key: str | None = None) → Dict[str, Any][source]¶

Enable (or disable) splitting incoming documents with AI.

Sets is_ai_split_enabled and, optionally, the natural-language ai_split_instructions. AI splitting takes precedence over the other split methods. The split itself runs per document via Document.split().

Parameters:

mailbox_id – ID of the mailbox.
instructions – Optional AI splitting instructions.
enabled – Set to False to turn AI splitting off.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod split_by_page(mailbox_id: int, every: int | None = None, *, enabled: bool = True, api_key: str | None = None) → Dict[str, Any][source]¶

Enable (or disable) splitting documents every every pages.

Parameters:

mailbox_id – ID of the mailbox.
every – Number of pages per resulting document (required unless enabled is False).
enabled – Set to False to turn this split method off.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod split_by_page_range(mailbox_id: int, ranges: List[Dict[str, Any]] | None = None, *, enabled: bool = True, api_key: str | None = None) → Dict[str, Any][source]¶

Enable (or disable) splitting documents by explicit page ranges.

Parameters:

mailbox_id – ID of the mailbox.
ranges – List of {"start_index", "end_index"} dicts (validated by PageRangeSchema); required unless enabled is False.
enabled – Set to False to clear the page-range split method.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod split_by_keywords(mailbox_id: int, keywords: List[Dict[str, Any]] | None = None, *, enabled: bool = True, api_key: str | None = None) → Dict[str, Any][source]¶

Enable (or disable) splitting documents on keywords.

Parameters:

mailbox_id – ID of the mailbox.
keywords – List of {"keyword", "is_before"} dicts (validated by SplitKeyWordsSchema); required unless enabled is False.
enabled – Set to False to clear the keyword split method.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod set_email_processing(mailbox_id: int, mode: EmailProcessing | str, *, api_key: str | None = None) → Dict[str, Any][source]¶

Configure how incoming emails and attachments are processed.

Parameters:

mailbox_id – ID of the mailbox.
mode – One of EmailProcessing — EMAILS_AND_ATTACHMENTS (process both), EMAILS_ONLY (skip attachments) or ATTACHMENTS_ONLY (skip the email body).
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod set_metadata(mailbox_id: int, enable: parseur.schemas.mailbox.Metadata = Metadata(0), disable: parseur.schemas.mailbox.Metadata = Metadata(0), *, api_key: str | None = None) → Dict[str, Any][source]¶

Enable and/or disable metadata columns on a mailbox, in one call.

Compose columns with |. Only the columns referenced in enable or disable are changed; the others are left as they are.

Parameters:

mailbox_id – ID of the mailbox.
enable – Columns to turn on, e.g. Metadata.SUBJECT | Metadata.SENDER.
disable – Columns to turn off, e.g. Metadata.TO.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

Raises:

ValueError – If a column appears in both enable and disable.

classmethod set_allowed_extensions(mailbox_id: int, extensions: List[str] | None, *, api_key: str | None = None) → Dict[str, Any][source]¶

Restrict which file types (“Files to process”) the mailbox accepts.

Parameters:

mailbox_id – ID of the mailbox.
extensions – List of extensions to accept (e.g. ["pdf", "docx", "png"]). Each is validated against SUPPORTED_FILE_EXTENSIONS. Pass None (or an empty list) to accept every supported type again.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod set_timezone(mailbox_id: int, timezone: str | None, *, api_key: str | None = None) → Dict[str, Any][source]¶

Set the timezone used to interpret dates/times in documents.

Parameters:

mailbox_id – ID of the mailbox.
timezone – An IANA timezone name (e.g. "Europe/Paris"), or None to clear it and fall back to the account default.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod set_date_format(mailbox_id: int, date_format: parseur.schemas.mailbox.DateFormat | str | None, *, api_key: str | None = None) → Dict[str, Any][source]¶

Set how ambiguous dates in documents are read.

Parameters:

mailbox_id – ID of the mailbox.
date_format – DateFormat (MONTH_FIRST or DAY_FIRST), or None to clear it.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod set_decimal_separator(mailbox_id: int, separator: parseur.schemas.mailbox.DecimalSeparator | str | None, *, api_key: str | None = None) → Dict[str, Any][source]¶

Set the decimal separator for numbers in documents.

Parameters:

mailbox_id – ID of the mailbox.
separator – DecimalSeparator (DOT or COMMA), or None to clear it.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod set_sender_filter(mailbox_id: int, mode: SenderFilter | str, emails_or_domains: List[str], *, api_key: str | None = None) → Dict[str, Any][source]¶

Filter incoming senders by an allow- or block-list.

Sets the mode and its list together. Pass an empty list to clear the filter (accept every sender).

Parameters:

mailbox_id – ID of the mailbox.
mode – SenderFilter — ALLOWLIST (only the listed senders are accepted) or BLOCKLIST (the listed senders are rejected).
emails_or_domains – Emails or domains to allow/block, e.g. ["acme.com", "billing@foo.com"].
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod process_page_range(mailbox_id: int, ranges: List[Dict[str, Any]] | None = None, *, enabled: bool = True, api_key: str | None = None) → Dict[str, Any][source]¶

Restrict processing to the given page ranges of each document.

Parameters:

mailbox_id – ID of the mailbox.
ranges – List of {"start_index", "end_index"} dicts (validated by PageRangeSchema); required unless enabled is False.
enabled – Set to False to clear the page-range restriction (process every page again).
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox.

classmethod process_odd_pages(mailbox_id: int, enabled: bool = True, *, api_key: str | None = None) → Dict[str, Any][source]¶: Restrict processing to odd pages (1, 3, 5, …) of each document.

classmethod process_even_pages(mailbox_id: int, enabled: bool = True, *, api_key: str | None = None) → Dict[str, Any][source]¶: Restrict processing to even pages (2, 4, 6, …) of each document.

classmethod download(mailbox_id: int, fmt: str = 'csv', *, api_key: str | None = None) → bytes[source]¶

Download every parsed result of the mailbox as a single file.

This is the document-level export: one row per processed document, with the mailbox’s fields as columns. To export the rows of a table field instead, use ParserField.download(); for a custom column selection, use ExportConfig.

Parameters:

mailbox_id – ID of the mailbox.
fmt – "csv" (default), "json" or "xlsx".
api_key – Optional API key overriding the global one for this call.

Returns:

The export file content as bytes.

Raises:

ValueError – If the format is unsupported or unavailable.

classmethod delete(mailbox_id: int, *, api_key: str | None = None) → bool[source]¶

Delete a mailbox.

Parameters:

mailbox_id – ID of the mailbox to delete.
api_key – Optional API key overriding the global one for this call.

Returns:

True if the deletion request was accepted.

class parseur.MailboxOrderKey[source]¶

Bases: str, enum.Enum

Enumeration of supported mailbox sorting keys.

Used with the order_by parameter to specify sorting in Mailbox.list() and Mailbox.iter().

NAME = 'name'¶

DOCUMENT_COUNT = 'document_count'¶

TEMPLATE_COUNT = 'template_count'¶

PARSEDOK_COUNT = 'PARSEDOK_count'¶

PARSEDKO_COUNT = 'PARSEDKO_count'¶

QUOTAEXC_COUNT = 'QUOTAEXC_count'¶

EXPORTKO_COUNT = 'EXPORTKO_count'¶

class parseur.Metadata[source]¶

Bases: enum.IntFlag

Per-document metadata columns a mailbox can expose.

A IntFlag, so columns compose with | and can be enabled or disabled together (see parseur.Mailbox.set_metadata()). Single source of truth for the *_field toggles: a member maps to its API field by lowercasing its name and appending _field (see field) — e.g. Metadata.SUBJECT -> "subject_field". Both the read and write mailbox schemas are derived from this enum so the column list lives in one place.

ATTACHMENTS¶

BCC¶

CC¶

CONTENT¶

CREATED_DATE¶

CREATED¶

CREATED_TIME¶

CREDIT_COUNT¶

DOCUMENT_ID¶

DOCUMENT_URL¶

HEADERS¶

HTML_DOCUMENT¶

LAST_REPLY¶

MAILBOX_ID¶

ORIGINAL_DOCUMENT¶

ORIGINAL_RECIPIENT¶

PAGE_COUNT¶

PARSING_ENGINE¶

PROCESSED_DATE¶

PROCESSED¶

PROCESSED_TIME¶

PUBLIC_DOCUMENT_URL¶

RECEIVED_DATE¶

RECEIVED¶

RECEIVED_TIME¶

RECIPIENT¶

RECIPIENT_SUFFIX¶

REPLY_TO¶

SEARCHABLE_PDF¶

SENDER¶

SENDER_NAME¶

SPLIT_PAGE_RANGE¶

SPLIT_PARENT_ID¶

SUBJECT¶

TEMPLATE¶

TEXT_DOCUMENT¶

TO¶

property field: str¶: The mailbox schema field this column maps to (e.g. subject_field).

class parseur.SenderFilter[source]¶

Bases: str, enum.Enum

How a mailbox filters incoming senders.

Maps to use_whitelist_instead_of_blacklist (see parseur.Mailbox.set_sender_filter()), paired with emails_or_domains.

ALLOWLIST = 'allowlist'¶

BLOCKLIST = 'blocklist'¶

class parseur.ParserField[source]¶

Manage the fields (parser_object_set) extracted by a mailbox.

Parseur has no per-field endpoint: fields are read from the mailbox and written back via PUT /parser/{id}. These helpers read the current fields, apply a change, and persist it. All writes are validated and serialized through ParserFieldWriteSchema. A PUT upserts the submitted fields and leaves the others untouched; deletion is requested with a _destroy marker (see delete()).

classmethod list(mailbox_id: int, *, api_key: str | None = None) → List[Dict[str, Any]][source]¶: Return the parser fields currently configured on a mailbox.

classmethod _save(mailbox_id: int, fields: List[Dict[str, Any]], *, api_key: str | None = None) → List[Dict[str, Any]][source]¶: Persist a field list via the mailbox and return the result.

classmethod add(mailbox_id: int, name: str, field_format: str | parseur.schemas.paserfield.FieldFormat, *, query: str | None = None, is_required: bool | None = None, used_by_ai: bool | None = None, choice_set: List[str] | None = None, parser_object_set: List[Dict[str, Any]] | None = None, api_key: str | None = None) → List[Dict[str, Any]][source]¶

Add a new field to a mailbox, keeping the existing ones.

Parameters:

mailbox_id – ID of the mailbox.
name – Name of the new field.
field_format – Field format (see FieldFormat).
query – Optional AI extraction instructions.
is_required – Optional required flag.
used_by_ai – Optional flag controlling AI extraction.
choice_set – Optional list of allowed values.
parser_object_set – Optional nested columns (for TABLE fields).
api_key – Optional API key overriding the global one for this call.

Returns:

The updated list of parser fields.

classmethod update(mailbox_id: int, field_id: str, *, api_key: str | None = None, **changes: Any) → List[Dict[str, Any]][source]¶

Update a single existing field by its id.

Only the provided keys are changed; the other fields are preserved.

Parameters:

mailbox_id – ID of the mailbox.
field_id – ID of the field to update (e.g. “PF12345”).
api_key – Optional API key overriding the global one for this call.
changes – Writable field properties to change (name, format, query, is_required, used_by_ai, choice_set, parser_object_set). field_format is accepted as an alias for format.

Returns:

The updated list of parser fields.

Raises:

ValueError – If no field with field_id exists on the mailbox.

classmethod delete(mailbox_id: int, field_id: str, *, api_key: str | None = None) → List[Dict[str, Any]][source]¶

Delete a single field from a mailbox by its id.

Sends a _destroy marker for the field; the other fields are left untouched.

Parameters:

mailbox_id – ID of the mailbox.
field_id – ID of the field to delete (e.g. “PF12345”).
api_key – Optional API key overriding the global one for this call.

Returns:

The updated list of parser fields.

Raises:

ValueError – If no field with field_id exists on the mailbox.

classmethod download(mailbox_id: int, field_id: str, fmt: str = 'csv', *, api_key: str | None = None) → bytes[source]¶

Download the rows of a field as a single file.

This is the table-level export, meant for TABLE fields: one row per line item, with the table columns as columns. For the whole mailbox use Mailbox.download(); for a custom column selection use ExportConfig.

Parameters:

mailbox_id – ID of the mailbox.
field_id – ID of the field to export (e.g. “PF12345”).
fmt – "csv" (default), "json" or "xlsx".
api_key – Optional API key overriding the global one for this call.

Returns:

The export file content as bytes.

Raises:

ValueError – If the field is unknown or the format is unavailable.

class parseur.DocumentStatus[source]¶

Bases: str, enum.Enum

Enum for Parseur document processing statuses.

INCOMING = 'INCOMING'¶

ANALYZING = 'ANALYZING'¶

DELETED = 'DELETED'¶

PROGRESS = 'PROGRESS'¶

PARSEDOK = 'PARSEDOK'¶

PARSEDKO = 'PARSEDKO'¶

QUOTAEXC = 'QUOTAEXC'¶

SKIPPED = 'SKIPPED'¶

SPLIT = 'SPLIT'¶

EXPORTKO = 'EXPORTKO'¶

TRANSKO = 'TRANSKO'¶

INVALID = 'INVALID'¶

class parseur.ExportType[source]¶

Bases: str, enum.Enum

Type of an export configuration.

PARSER: export the document-level result (one row per document).
PARSER_FIELD: export the rows of a table field.

PARSER = 'PARSER'¶

PARSER_FIELD = 'PARSER_FIELD'¶

class parseur.AIEngine[source]¶

Bases: str, enum.Enum

Enumeration of AI engines that can be set on a mailbox when creating or updating it.

The values mirror the parser.ai_engine choices returned by the /bootstrap endpoint.

Members:

DISABLED: No AI engine (template-based parsing only).
GCP_AI_2_5: AI Text engine v2.5 (analyzes extracted text).
GCP_AI_3_TXT: AI Text engine v3 (analyzes extracted text).
GCP_AI_2: AI Vision engine v3 (understands layout and images).

DISABLED = 'DISABLED'¶

GCP_AI_2_5 = 'GCP_AI_2_5'¶

GCP_AI_3_TXT = 'GCP_AI_3_TXT'¶

GCP_AI_2 = 'GCP_AI_2'¶

class parseur.DateFormat[source]¶

Bases: str, enum.Enum

How to read ambiguous dates in documents (the input_date_format).

MONTH_FIRST = 'MONTH_FIRST'¶

DAY_FIRST = 'DAY_FIRST'¶

class parseur.DecimalSeparator[source]¶

Bases: str, enum.Enum

Decimal separator for numbers in documents (the decimal_separator).

DOT = '.'¶

COMMA = ','¶

parseur.SUPPORTED_FILE_EXTENSIONS[source]¶

class parseur.FieldFormat[source]¶

Bases: str, enum.Enum

Enumeration of the data formats a parser field can have.

Used as the format of a field when creating or updating a mailbox’s fields (parser_object_set).

TEXT = 'TEXT'¶

ONELINE = 'ONELINE'¶

DATE = 'DATE'¶

TIME = 'TIME'¶

DATETIME = 'DATETIME'¶

NUMBER = 'NUMBER'¶

NAME = 'NAME'¶

ADDRESS = 'ADDRESS'¶

TABLE = 'TABLE'¶

LINK = 'LINK'¶

parseur.to_json(data, indent=2, sort_keys=True, ensure_ascii=False)[source]¶

Serialize a Python object to a JSON-formatted string with ISO datetime support.

This function uses the custom ISODateJSONEncoder to automatically convert datetime.datetime objects to ISO 8601 strings.

Parameters:

data – The data to serialize (dict, list, etc.).
indent – Number of spaces to indent in the output JSON. Default is 2.
sort_keys – Whether to sort the dictionary keys in the output. Default is True.
ensure_ascii – Whether to escape non-ASCII characters. Default is False.

Returns:

A JSON-formatted string.

class parseur.Webhook[source]¶

classmethod from_response(data: Dict) → Dict[source]¶

Deserialize a webhook API response.

Parameters:: data – Raw API response dictionary.
Returns:: Deserialized webhook dictionary.

classmethod create(event: parseur.event.ParseurEvent, target_url: str, mailbox_id: int | None = None, table_field_id: str | None = None, headers: Dict[str, str] | None = None, name: str | None = None, *, api_key: str | None = None) → Dict[str, Any][source]¶

Create a new custom webhook for Parseur.

Parameters:

event – Webhook event type (document or table event).
target_url – The URL to send webhook POSTs to.
mailbox_id – Mailbox ID (required for document events).
table_field_id – Table field ID (required for table events, e.g. “PF12345”).
headers – Optional custom HTTP headers.
name – Optional custom name for the webhook.
api_key – Optional API key overriding the global one for this call.

Returns:

The created webhook object as a dictionary.

classmethod retrieve(webhook_id: int, *, api_key: str | None = None) → Dict[str, Any][source]¶

Retrieve a webhook from the account.

Parameters:

webhook_id – ID of the webhook to delete.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox object as a dictionary.

classmethod delete(webhook_id: int, *, api_key: str | None = None) → bool[source]¶

Delete a webhook from the account.

Parameters:

webhook_id – ID of the webhook to delete.
api_key – Optional API key overriding the global one for this call.

Returns:

True if deletion was successful.

classmethod enable(mailbox_id: int, webhook_id: int, *, api_key: str | None = None) → Dict[str, Any][source]¶

Enable an existing webhook for a given mailbox.

Parameters:

mailbox_id – ID of the mailbox.
webhook_id – ID of the webhook to enable.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox object as a dictionary.

classmethod pause(mailbox_id: int, webhook_id: int, *, api_key: str | None = None) → Dict[str, Any][source]¶

Pause (disable) an existing webhook for a given mailbox.

Parameters:

mailbox_id – ID of the mailbox.
webhook_id – ID of the webhook to pause.
api_key – Optional API key overriding the global one for this call.

Returns:

The updated mailbox object as a dictionary.

classmethod list(*, api_key: str | None = None) → List[Dict[str, Any]][source]¶: Retrieve all webhooks as a list.

classmethod iter(*, api_key: str | None = None) → Iterable[Dict[str, Any]][source]¶: Yield all webhooks registered on the account.