parseur.mailbox

Classes

EmailProcessing	How a mailbox processes incoming emails and their attachments.
SenderFilter	How a mailbox filters incoming senders.
MailboxOrderKey	Enumeration of supported mailbox sorting keys.
Mailbox

Module Contents

class parseur.mailbox.EmailProcessing

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.SenderFilter

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.mailbox.MailboxOrderKey

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.mailbox.Mailbox

classmethod from_response(data: Dict) → Dict

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]

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]]

Retrieve all mailboxes as a list.

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

Retrieve a single mailbox by ID.

classmethod schema(mailbox_id: int, *, api_key: str | None = None) → Dict[str, Any]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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

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

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.