autotouch-cli 0.2.21__tar.gz → 0.2.22__tar.gz

{autotouch_cli-0.2.21 → autotouch_cli-0.2.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.21
+Version: 0.2.22
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -102,6 +102,11 @@ Notes:
 - `--wait` polls import status to terminal state.
 - `--checkpoint-file` stores state and blocks accidental duplicate re-imports.
 - `--validate-only` validates CSV parse/shape on server without writing rows.
+- Blacklist controls on optimized import:
+  - company-domain filtering is ON by default
+  - email filtering is OFF by default
+  - disable company filtering with `--no-check-company-blacklist`
+  - enable email filtering with `--check-email-blacklist`
 - Safety assertions:
   - `--expected-rows <N>`
   - `--require-columns col_a,col_b`
@@ -109,6 +114,43 @@ Notes:
   - `--require-non-empty key:ratio`
 - For async imports with `--wait`, assertions are rechecked postflight via task manifest verification.
 - Use `--allow-reimport` if you intentionally want to run the same file again.
+- Import responses include `blacklist_summary` with company/email `skipped_count` and `enforced` flags.
+
+Example enabling both company and email enforcement:
+
+```bash
+autotouch rows import-csv \
+  --table-id <TABLE_ID> \
+  --confirm-table-id <TABLE_ID> \
+  --file contacts.csv \
+  --checkpoint-file .autotouch-import.json \
+  --check-email-blacklist \
+  --wait \
+  --output json
+```
+
+Manage blacklist entries (native CLI, admin identity required):
+
+```bash
+# List current entries
+autotouch blacklist list --type-filter all --limit 100
+
+# Add entries
+autotouch blacklist add --type domain --value competitor.com --reason "Do not contact"
+autotouch blacklist add --type email --value blocked@example.com --reason "Unsubscribed"
+
+# Bulk-import entries from CSV/TXT
+autotouch blacklist import --file blacklist.csv
+
+# Check/filter email sets (auto-chunked for large lists)
+autotouch blacklist check --emails-file recipients.csv --emails-column email --summary-only
+autotouch blacklist filter --emails-file recipients.csv --emails-column email --summary-only
+```
+
+Recommended timing:
+- Add suppressions early (unsubscribed addresses, existing customers, competitors, and clear non-ICP domains).
+- Before billable enrichments (`llm_enrichment`, `email_finder`, `phone_finder`), run blacklist filtering and enrich only clean candidates.
+- Run one final blacklist check/filter before outreach execution.
 
 ## Import modes
 
@@ -140,6 +182,7 @@ Auto-run is configured per column (`autoRun`), not per table.
 Important:
 - Insert events do not run `onSourceUpdate` columns.
 - Imports may queue auto-run dispatch evaluation, but only columns whose `autoRun` policy matches the event are queued.
+- Formatter columns are normalized server-side to `onSourceUpdate` (attempted `never`/`onInsert` values are overridden).
 
 ## Create a column
 
@@ -164,6 +207,7 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
   - router mode: `routes[]` (first matching route wins)
@@ -171,6 +215,7 @@ Notes:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
   - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+  - star/favorite high-signal fields so call-sidecar context stays quick to scan and AI draft context stays focused
 
 If you create custom `llm_enrichment` schemas:
 - Use strict field-map schema shape (no root `type/properties` wrapper).
@@ -227,6 +272,8 @@ Design guidance:
 - default behavior for agents: write full context/content, not summaries or truncation
 - only truncate/summarize when there is a hard limit (storage/model/provider/payload), and explicitly mark truncation
 - keep intent separate from raw context so downstream logic can change without losing source data
+- for calling workflows, favorite/star key fields so users can access the most relevant context quickly in sidecar views
+- for AI-generated emails/copy, include both intent and full context in imports so drafts are grounded, not generic
 - keep one entity per row and dedupe on a stable identity key
 - keep snippets/summaries optional and derived from raw context, never a replacement for it
 - normalize intent labels if you need deterministic automation
@@ -516,6 +563,15 @@ autotouch columns run-next \
   --wait
 ```
 
+Blacklist gate (recommended before billable runs):
+
+```bash
+autotouch blacklist filter \
+  --emails-file candidates.csv \
+  --emails-column work_email \
+  --output json
+```
+
 ## Job truth contract (agent-safe)
 
 - Treat a run as started only when you receive `job_id`.

{autotouch_cli-0.2.21 → autotouch_cli-0.2.22}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.21
+Version: 0.2.22
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -102,6 +102,11 @@ Notes:
 - `--wait` polls import status to terminal state.
 - `--checkpoint-file` stores state and blocks accidental duplicate re-imports.
 - `--validate-only` validates CSV parse/shape on server without writing rows.
+- Blacklist controls on optimized import:
+  - company-domain filtering is ON by default
+  - email filtering is OFF by default
+  - disable company filtering with `--no-check-company-blacklist`
+  - enable email filtering with `--check-email-blacklist`
 - Safety assertions:
   - `--expected-rows <N>`
   - `--require-columns col_a,col_b`
@@ -109,6 +114,43 @@ Notes:
   - `--require-non-empty key:ratio`
 - For async imports with `--wait`, assertions are rechecked postflight via task manifest verification.
 - Use `--allow-reimport` if you intentionally want to run the same file again.
+- Import responses include `blacklist_summary` with company/email `skipped_count` and `enforced` flags.
+
+Example enabling both company and email enforcement:
+
+```bash
+autotouch rows import-csv \
+  --table-id <TABLE_ID> \
+  --confirm-table-id <TABLE_ID> \
+  --file contacts.csv \
+  --checkpoint-file .autotouch-import.json \
+  --check-email-blacklist \
+  --wait \
+  --output json
+```
+
+Manage blacklist entries (native CLI, admin identity required):
+
+```bash
+# List current entries
+autotouch blacklist list --type-filter all --limit 100
+
+# Add entries
+autotouch blacklist add --type domain --value competitor.com --reason "Do not contact"
+autotouch blacklist add --type email --value blocked@example.com --reason "Unsubscribed"
+
+# Bulk-import entries from CSV/TXT
+autotouch blacklist import --file blacklist.csv
+
+# Check/filter email sets (auto-chunked for large lists)
+autotouch blacklist check --emails-file recipients.csv --emails-column email --summary-only
+autotouch blacklist filter --emails-file recipients.csv --emails-column email --summary-only
+```
+
+Recommended timing:
+- Add suppressions early (unsubscribed addresses, existing customers, competitors, and clear non-ICP domains).
+- Before billable enrichments (`llm_enrichment`, `email_finder`, `phone_finder`), run blacklist filtering and enrich only clean candidates.
+- Run one final blacklist check/filter before outreach execution.
 
 ## Import modes
 
@@ -140,6 +182,7 @@ Auto-run is configured per column (`autoRun`), not per table.
 Important:
 - Insert events do not run `onSourceUpdate` columns.
 - Imports may queue auto-run dispatch evaluation, but only columns whose `autoRun` policy matches the event are queued.
+- Formatter columns are normalized server-side to `onSourceUpdate` (attempted `never`/`onInsert` values are overridden).
 
 ## Create a column
 
@@ -164,6 +207,7 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
   - router mode: `routes[]` (first matching route wins)
@@ -171,6 +215,7 @@ Notes:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
   - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+  - star/favorite high-signal fields so call-sidecar context stays quick to scan and AI draft context stays focused
 
 If you create custom `llm_enrichment` schemas:
 - Use strict field-map schema shape (no root `type/properties` wrapper).
@@ -227,6 +272,8 @@ Design guidance:
 - default behavior for agents: write full context/content, not summaries or truncation
 - only truncate/summarize when there is a hard limit (storage/model/provider/payload), and explicitly mark truncation
 - keep intent separate from raw context so downstream logic can change without losing source data
+- for calling workflows, favorite/star key fields so users can access the most relevant context quickly in sidecar views
+- for AI-generated emails/copy, include both intent and full context in imports so drafts are grounded, not generic
 - keep one entity per row and dedupe on a stable identity key
 - keep snippets/summaries optional and derived from raw context, never a replacement for it
 - normalize intent labels if you need deterministic automation
@@ -516,6 +563,15 @@ autotouch columns run-next \
   --wait
 ```
 
+Blacklist gate (recommended before billable runs):
+
+```bash
+autotouch blacklist filter \
+  --emails-file candidates.csv \
+  --emails-column work_email \
+  --output json
+```
+
 ## Job truth contract (agent-safe)
 
 - Treat a run as started only when you receive `job_id`.

{autotouch_cli-0.2.21 → autotouch_cli-0.2.22}/autotouch_cli.egg-info/SOURCES.txt

@@ -48,6 +48,7 @@ scripts/migrations/20260113_normalize_table_filter_operators.py
 scripts/migrations/20260113_set_user_permissions_user_admin.py
 scripts/migrations/20260204_sync_lead_owner_from_tasks.py
 scripts/migrations/20260303_add_webhook_subscription_collections.py
+scripts/migrations/20260305_force_formatter_autorun_on_source_update.py
 scripts/migrations/migrate_org_user_credits.py
 scripts/migrations/set_default_lead_status.py
 scripts/migrations/update_lead_owner_from_tasks.py

{autotouch_cli-0.2.21 → autotouch_cli-0.2.22}/docs/research-table/reference/autotouch-cli-pypi.md

@@ -93,6 +93,11 @@ Notes:
 - `--wait` polls import status to terminal state.
 - `--checkpoint-file` stores state and blocks accidental duplicate re-imports.
 - `--validate-only` validates CSV parse/shape on server without writing rows.
+- Blacklist controls on optimized import:
+  - company-domain filtering is ON by default
+  - email filtering is OFF by default
+  - disable company filtering with `--no-check-company-blacklist`
+  - enable email filtering with `--check-email-blacklist`
 - Safety assertions:
   - `--expected-rows <N>`
   - `--require-columns col_a,col_b`
@@ -100,6 +105,43 @@ Notes:
   - `--require-non-empty key:ratio`
 - For async imports with `--wait`, assertions are rechecked postflight via task manifest verification.
 - Use `--allow-reimport` if you intentionally want to run the same file again.
+- Import responses include `blacklist_summary` with company/email `skipped_count` and `enforced` flags.
+
+Example enabling both company and email enforcement:
+
+```bash
+autotouch rows import-csv \
+  --table-id <TABLE_ID> \
+  --confirm-table-id <TABLE_ID> \
+  --file contacts.csv \
+  --checkpoint-file .autotouch-import.json \
+  --check-email-blacklist \
+  --wait \
+  --output json
+```
+
+Manage blacklist entries (native CLI, admin identity required):
+
+```bash
+# List current entries
+autotouch blacklist list --type-filter all --limit 100
+
+# Add entries
+autotouch blacklist add --type domain --value competitor.com --reason "Do not contact"
+autotouch blacklist add --type email --value blocked@example.com --reason "Unsubscribed"
+
+# Bulk-import entries from CSV/TXT
+autotouch blacklist import --file blacklist.csv
+
+# Check/filter email sets (auto-chunked for large lists)
+autotouch blacklist check --emails-file recipients.csv --emails-column email --summary-only
+autotouch blacklist filter --emails-file recipients.csv --emails-column email --summary-only
+```
+
+Recommended timing:
+- Add suppressions early (unsubscribed addresses, existing customers, competitors, and clear non-ICP domains).
+- Before billable enrichments (`llm_enrichment`, `email_finder`, `phone_finder`), run blacklist filtering and enrich only clean candidates.
+- Run one final blacklist check/filter before outreach execution.
 
 ## Import modes
 
@@ -131,6 +173,7 @@ Auto-run is configured per column (`autoRun`), not per table.
 Important:
 - Insert events do not run `onSourceUpdate` columns.
 - Imports may queue auto-run dispatch evaluation, but only columns whose `autoRun` policy matches the event are queued.
+- Formatter columns are normalized server-side to `onSourceUpdate` (attempted `never`/`onInsert` values are overridden).
 
 ## Create a column
 
@@ -155,6 +198,7 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
   - router mode: `routes[]` (first matching route wins)
@@ -162,6 +206,7 @@ Notes:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
   - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+  - star/favorite high-signal fields so call-sidecar context stays quick to scan and AI draft context stays focused
 
 If you create custom `llm_enrichment` schemas:
 - Use strict field-map schema shape (no root `type/properties` wrapper).
@@ -218,6 +263,8 @@ Design guidance:
 - default behavior for agents: write full context/content, not summaries or truncation
 - only truncate/summarize when there is a hard limit (storage/model/provider/payload), and explicitly mark truncation
 - keep intent separate from raw context so downstream logic can change without losing source data
+- for calling workflows, favorite/star key fields so users can access the most relevant context quickly in sidecar views
+- for AI-generated emails/copy, include both intent and full context in imports so drafts are grounded, not generic
 - keep one entity per row and dedupe on a stable identity key
 - keep snippets/summaries optional and derived from raw context, never a replacement for it
 - normalize intent labels if you need deterministic automation
@@ -507,6 +554,15 @@ autotouch columns run-next \
   --wait
 ```
 
+Blacklist gate (recommended before billable runs):
+
+```bash
+autotouch blacklist filter \
+  --emails-file candidates.csv \
+  --emails-column work_email \
+  --output json
+```
+
 ## Job truth contract (agent-safe)
 
 - Treat a run as started only when you receive `job_id`.

{autotouch_cli-0.2.21 → autotouch_cli-0.2.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "autotouch-cli"
-version = "0.2.21"
+version = "0.2.22"
 description = "Autotouch Smart Table CLI"
 readme = "docs/research-table/reference/autotouch-cli-pypi.md"
 requires-python = ">=3.9"

autotouch_cli-0.2.22/scripts/migrations/20260305_force_formatter_autorun_on_source_update.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+Normalize formatter columns to auto-run on source updates.
+
+Why:
+- Formatter columns should be reactive transforms.
+- Legacy records may still have auto_run=never/onInsert or a conflicting legacy autoRun field.
+
+What this migration does:
+1) Finds formatter columns with missing/legacy auto-run values.
+2) Sets `auto_run` to `onSourceUpdate`.
+3) Removes legacy `autoRun` to avoid precedence conflicts in payload serialization.
+
+Usage:
+  python scripts/migrations/20260305_force_formatter_autorun_on_source_update.py
+
+Environment variables:
+  MONGODB_URI      (default: mongodb://localhost:27017)
+  MONGODB_DB_NAME  (default: autotouch)
+  DRY_RUN          (default: false)
+"""
+
+import asyncio
+import os
+from datetime import datetime
+from typing import Any, Dict
+
+from motor.motor_asyncio import AsyncIOMotorClient
+
+
+MONGODB_URI = os.getenv("MONGODB_URI", "mongodb://localhost:27017")
+MONGODB_DB_NAME = os.getenv("MONGODB_DB_NAME", "autotouch")
+DRY_RUN = os.getenv("DRY_RUN", "false").strip().lower() == "true"
+
+
+def _formatter_query() -> Dict[str, Any]:
+    return {
+        "kind": "formatter",
+        "$or": [
+            {"auto_run": {"$exists": False}},
+            {"auto_run": {"$in": [None, "", "never", "onInsert"]}},
+            {"autoRun": {"$exists": True}},
+        ],
+    }
+
+
+async def run() -> None:
+    client = AsyncIOMotorClient(MONGODB_URI)
+    db = client[MONGODB_DB_NAME]
+
+    try:
+        print(f"Starting formatter auto-run migration on db={MONGODB_DB_NAME}")
+        print(f"Timestamp: {datetime.utcnow().isoformat()}Z")
+        print(f"DRY_RUN={DRY_RUN}")
+
+        query = _formatter_query()
+        candidates = await db.columns.count_documents(query)
+        print(f"Formatter columns to normalize: {candidates}")
+
+        if candidates == 0:
+            print("No formatter columns require migration.")
+            return
+
+        sample = await db.columns.find(
+            query,
+            {"_id": 1, "key": 1, "auto_run": 1, "autoRun": 1},
+        ).limit(5).to_list(length=5)
+        print("Sample candidates:")
+        for col in sample:
+            print(
+                f"- id={col.get('_id')} key={col.get('key')} "
+                f"auto_run={col.get('auto_run')} autoRun={col.get('autoRun')}"
+            )
+
+        if DRY_RUN:
+            print("DRY_RUN enabled; no updates applied.")
+            return
+
+        now = datetime.utcnow()
+        result = await db.columns.update_many(
+            query,
+            {
+                "$set": {
+                    "auto_run": "onSourceUpdate",
+                    "updated_at": now,
+                },
+                "$unset": {"autoRun": ""},
+            },
+        )
+        print(f"Matched: {result.matched_count}")
+        print(f"Modified: {result.modified_count}")
+        print("Migration complete.")
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(run())

{autotouch_cli-0.2.21 → autotouch_cli-0.2.22}/scripts/smart_table_cli.py

@@ -659,6 +659,150 @@ def _load_json_input(
     return default
 
 
+def _normalize_email_value(value: Any) -> Optional[str]:
+    text = str(value or "").strip().lower()
+    return text or None
+
+
+def _split_cli_email_values(raw_values: Optional[List[str]]) -> List[str]:
+    emails: List[str] = []
+    for raw in raw_values or []:
+        for piece in str(raw).replace("\n", ",").split(","):
+            normalized = _normalize_email_value(piece)
+            if normalized:
+                emails.append(normalized)
+    return emails
+
+
+def _parse_email_payload(payload: Any, *, context: str) -> List[str]:
+    raw_values: List[Any]
+    if isinstance(payload, list):
+        raw_values = payload
+    elif isinstance(payload, dict) and isinstance(payload.get("emails"), list):
+        raw_values = payload.get("emails") or []
+    else:
+        print(
+            f"ERROR: {context} must be a JSON array or an object with an 'emails' array",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    emails: List[str] = []
+    for item in raw_values:
+        normalized = _normalize_email_value(item)
+        if normalized:
+            emails.append(normalized)
+    return emails
+
+
+def _load_emails_from_file(file_path: str, *, csv_column: Optional[str]) -> List[str]:
+    resolved_path = os.path.abspath(os.path.expanduser(str(file_path)))
+    suffix = Path(resolved_path).suffix.lower()
+
+    try:
+        if suffix == ".json":
+            with open(resolved_path, "r", encoding="utf-8") as f:
+                payload = json.load(f)
+            return _parse_email_payload(payload, context=f"emails file '{resolved_path}'")
+
+        if suffix == ".csv":
+            with open(resolved_path, "r", encoding="utf-8", newline="") as f:
+                reader = csv.DictReader(f)
+                rows = list(reader)
+                fieldnames = [name for name in (reader.fieldnames or []) if name]
+
+            if not fieldnames:
+                return []
+
+            preferred = str(csv_column or "").strip().lower()
+            selected_column: Optional[str] = None
+            if preferred:
+                for field_name in fieldnames:
+                    if str(field_name).strip().lower() == preferred:
+                        selected_column = field_name
+                        break
+
+            if selected_column is None:
+                normalized_fields = {
+                    str(field_name).strip().lower(): field_name for field_name in fieldnames
+                }
+                for candidate in ("email", "work_email", "personal_email", "primary_email"):
+                    if candidate in normalized_fields:
+                        selected_column = normalized_fields[candidate]
+                        break
+
+            if selected_column is None:
+                selected_column = fieldnames[0]
+
+            emails: List[str] = []
+            for row in rows:
+                normalized = _normalize_email_value((row or {}).get(selected_column))
+                if normalized:
+                    emails.append(normalized)
+            return emails
+
+        emails: List[str] = []
+        with open(resolved_path, "r", encoding="utf-8") as f:
+            for line in f:
+                for piece in str(line).replace("\n", "").split(","):
+                    normalized = _normalize_email_value(piece)
+                    if normalized:
+                        emails.append(normalized)
+        return emails
+
+    except FileNotFoundError:
+        print(f"ERROR: emails file not found: {resolved_path}", file=sys.stderr)
+        sys.exit(2)
+    except Exception as exc:
+        print(f"ERROR: failed to read emails file '{resolved_path}': {exc}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _dedupe_keep_order(values: List[str]) -> List[str]:
+    seen: set[str] = set()
+    deduped: List[str] = []
+    for value in values:
+        if value in seen:
+            continue
+        seen.add(value)
+        deduped.append(value)
+    return deduped
+
+
+def _collect_blacklist_emails(args: argparse.Namespace) -> List[str]:
+    emails: List[str] = []
+    emails.extend(_split_cli_email_values(getattr(args, "email", None)))
+
+    raw_emails_json = getattr(args, "emails_json", None)
+    if raw_emails_json:
+        payload = _parse_json_string(str(raw_emails_json), "emails")
+        emails.extend(_parse_email_payload(payload, context="--emails-json"))
+
+    emails_file = getattr(args, "emails_file", None)
+    if emails_file:
+        emails.extend(
+            _load_emails_from_file(
+                str(emails_file),
+                csv_column=getattr(args, "emails_column", None),
+            )
+        )
+
+    deduped = _dedupe_keep_order([email for email in emails if email])
+    if not deduped:
+        print(
+            "ERROR: provide emails via --email, --emails-json, or --emails-file",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    return deduped
+
+
+def _chunk_list(values: List[str], size: int) -> List[List[str]]:
+    if size <= 0:
+        return [values]
+    return [values[idx: idx + size] for idx in range(0, len(values), size)]
+
+
 def _request_api(
     method: str,
     path: str,
@@ -2239,6 +2383,211 @@ def cmd_tables_create(args: argparse.Namespace) -> None:
     _print_json(data, compact=args.compact)
 
 
+def cmd_blacklist_list(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    params: Dict[str, Any] = {
+        "type_filter": str(getattr(args, "type_filter", "all") or "all"),
+        "page": max(1, int(getattr(args, "page", 1) or 1)),
+        "limit": max(1, int(getattr(args, "limit", 100) or 100)),
+    }
+    search = str(getattr(args, "search", "") or "").strip()
+    if search:
+        params["search"] = search
+
+    data = _request_api(
+        "GET",
+        "/api/blacklist",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        params=params,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
+def cmd_blacklist_add(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    entry_type = str(args.type).strip().lower()
+    value = str(args.value or "").strip().lower()
+
+    if entry_type == "domain":
+        value = value.replace("https://", "").replace("http://", "")
+        value = value.lstrip("@")
+        value = value.split("/", 1)[0]
+
+    payload = {
+        "type": entry_type,
+        "value": value,
+        "reason": str(getattr(args, "reason", "") or ""),
+        "notes": str(getattr(args, "notes", "") or ""),
+    }
+    data = _request_api(
+        "POST",
+        "/api/blacklist",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        payload=payload,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
+def cmd_blacklist_remove(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    data = _request_api(
+        "DELETE",
+        f"/api/blacklist/{args.entry_id}",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
+def cmd_blacklist_import(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    source_path = os.path.abspath(os.path.expanduser(str(args.file)))
+    data = _request_multipart_api(
+        "POST",
+        "/api/blacklist/import",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        file_path=source_path,
+        file_field="file",
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    if isinstance(data, dict):
+        data.setdefault("source", source_path)
+    _print_json(data, compact=args.compact)
+
+
+def cmd_blacklist_check(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    emails = _collect_blacklist_emails(args)
+    chunk_size = max(1, min(int(getattr(args, "chunk_size", 1000) or 1000), 1000))
+
+    all_results: List[Dict[str, Any]] = []
+    chunk_summaries: List[Dict[str, Any]] = []
+    for chunk_index, chunk in enumerate(_chunk_list(emails, chunk_size), start=1):
+        response = _request_api(
+            "POST",
+            "/api/blacklist/check",
+            base_url=args.base_url,
+            token=token,
+            use_x_api_key=args.use_x_api_key,
+            payload={"emails": chunk},
+            timeout=args.timeout,
+            verbose=args.verbose,
+        )
+        if not isinstance(response, dict):
+            print("ERROR: unexpected response from /api/blacklist/check", file=sys.stderr)
+            sys.exit(1)
+
+        chunk_results = response.get("results") if isinstance(response.get("results"), list) else []
+        chunk_summary = response.get("summary") if isinstance(response.get("summary"), dict) else {}
+        all_results.extend([result for result in chunk_results if isinstance(result, dict)])
+        chunk_summaries.append(
+            {
+                "chunk": chunk_index,
+                "size": len(chunk),
+                "summary": chunk_summary,
+            }
+        )
+
+    total_blacklisted = sum(
+        1
+        for result in all_results
+        if bool(result.get("is_blacklisted"))
+    )
+    output: Dict[str, Any] = {
+        "input_count": len(emails),
+        "chunks": len(chunk_summaries),
+        "chunk_size": chunk_size,
+        "summary": {
+            "total_checked": len(all_results),
+            "total_blacklisted": total_blacklisted,
+            "total_clean": max(0, len(all_results) - total_blacklisted),
+        },
+    }
+    if not bool(getattr(args, "summary_only", False)):
+        output["results"] = all_results
+        if len(chunk_summaries) > 1:
+            output["chunk_summaries"] = chunk_summaries
+    _print_json(output, compact=args.compact)
+
+
+def cmd_blacklist_filter(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    emails = _collect_blacklist_emails(args)
+    chunk_size = max(1, min(int(getattr(args, "chunk_size", 10000) or 10000), 10000))
+
+    clean_emails: List[str] = []
+    blacklisted_emails: List[Dict[str, Any]] = []
+    chunk_summaries: List[Dict[str, Any]] = []
+    for chunk_index, chunk in enumerate(_chunk_list(emails, chunk_size), start=1):
+        response = _request_api(
+            "POST",
+            "/api/blacklist/filter",
+            base_url=args.base_url,
+            token=token,
+            use_x_api_key=args.use_x_api_key,
+            payload={"emails": chunk},
+            timeout=args.timeout,
+            verbose=args.verbose,
+        )
+        if not isinstance(response, dict):
+            print("ERROR: unexpected response from /api/blacklist/filter", file=sys.stderr)
+            sys.exit(1)
+
+        chunk_clean = response.get("clean_emails") if isinstance(response.get("clean_emails"), list) else []
+        chunk_blocked = (
+            response.get("blacklisted_emails")
+            if isinstance(response.get("blacklisted_emails"), list)
+            else []
+        )
+        chunk_summary = response.get("summary") if isinstance(response.get("summary"), dict) else {}
+        clean_emails.extend(
+            [
+                normalized
+                for normalized in (_normalize_email_value(item) for item in chunk_clean)
+                if normalized
+            ]
+        )
+        blacklisted_emails.extend([item for item in chunk_blocked if isinstance(item, dict)])
+        chunk_summaries.append(
+            {
+                "chunk": chunk_index,
+                "size": len(chunk),
+                "summary": chunk_summary,
+            }
+        )
+
+    output: Dict[str, Any] = {
+        "input_count": len(emails),
+        "chunks": len(chunk_summaries),
+        "chunk_size": chunk_size,
+        "summary": {
+            "total_provided": len(emails),
+            "total_clean": len(clean_emails),
+            "total_blacklisted": len(blacklisted_emails),
+        },
+    }
+    if not bool(getattr(args, "summary_only", False)):
+        output["clean_emails"] = clean_emails
+        output["blacklisted_emails"] = blacklisted_emails
+        if len(chunk_summaries) > 1:
+            output["chunk_summaries"] = chunk_summaries
+    _print_json(output, compact=args.compact)
+
+
 def cmd_rows_add(args: argparse.Namespace) -> None:
     token = _resolve_token(args.token, required=True)
     records_payload = _load_json_input(
@@ -3616,6 +3965,74 @@ def build_parser() -> argparse.ArgumentParser:
     _add_api_common_arguments(ptc)
     ptc.set_defaults(func=cmd_tables_create)
 
+    # blacklist
+    pbl = sub.add_parser("blacklist", help="Organization blacklist operations (admin)")
+    blacklist_sub = pbl.add_subparsers(dest="blacklist_cmd", required=True)
+
+    pbll = blacklist_sub.add_parser("list", help="List blacklist entries")
+    pbll.add_argument("--type-filter", choices=["all", "email", "domain"], default="all")
+    pbll.add_argument("--search", help="Filter by value/reason/notes")
+    pbll.add_argument("--page", type=int, default=1, help="Page number (default: 1)")
+    pbll.add_argument("--limit", type=int, default=100, help="Entries per page (default: 100)")
+    _add_api_common_arguments(pbll)
+    pbll.set_defaults(func=cmd_blacklist_list)
+
+    pbla = blacklist_sub.add_parser("add", help="Add a blacklist entry")
+    pbla.add_argument("--type", choices=["email", "domain"], required=True, help="Entry type")
+    pbla.add_argument("--value", required=True, help="Email or domain value")
+    pbla.add_argument("--reason", default="", help="Optional reason")
+    pbla.add_argument("--notes", default="", help="Optional notes")
+    _add_api_common_arguments(pbla)
+    pbla.set_defaults(func=cmd_blacklist_add)
+
+    pblr = blacklist_sub.add_parser("remove", help="Remove a blacklist entry by id")
+    pblr.add_argument("--entry-id", required=True)
+    _add_api_common_arguments(pblr)
+    pblr.set_defaults(func=cmd_blacklist_remove)
+
+    pbli = blacklist_sub.add_parser("import", help="Import blacklist entries from CSV/TXT")
+    pbli.add_argument("--file", required=True, help="Path to CSV/TXT file")
+    _add_api_common_arguments(pbli)
+    pbli.set_defaults(func=cmd_blacklist_import)
+
+    pblc = blacklist_sub.add_parser("check", help="Check whether emails are blacklisted")
+    pblc.add_argument(
+        "--email",
+        action="append",
+        help="Email value (repeatable; comma-separated also supported)",
+    )
+    pblc.add_argument("--emails-json", help="JSON array or object with emails[]")
+    pblc.add_argument("--emails-file", help="Path to .txt/.csv/.json email list")
+    pblc.add_argument("--emails-column", default="email", help="CSV column for emails (default: email)")
+    pblc.add_argument(
+        "--chunk-size",
+        type=int,
+        default=1000,
+        help="Request chunk size (max 1000, default: 1000)",
+    )
+    pblc.add_argument("--summary-only", action="store_true", help="Omit per-email results")
+    _add_api_common_arguments(pblc)
+    pblc.set_defaults(func=cmd_blacklist_check)
+
+    pblf = blacklist_sub.add_parser("filter", help="Filter blacklisted emails from a list")
+    pblf.add_argument(
+        "--email",
+        action="append",
+        help="Email value (repeatable; comma-separated also supported)",
+    )
+    pblf.add_argument("--emails-json", help="JSON array or object with emails[]")
+    pblf.add_argument("--emails-file", help="Path to .txt/.csv/.json email list")
+    pblf.add_argument("--emails-column", default="email", help="CSV column for emails (default: email)")
+    pblf.add_argument(
+        "--chunk-size",
+        type=int,
+        default=10000,
+        help="Request chunk size (max 10000, default: 10000)",
+    )
+    pblf.add_argument("--summary-only", action="store_true", help="Omit full clean/blocked lists")
+    _add_api_common_arguments(pblf)
+    pblf.set_defaults(func=cmd_blacklist_filter)
+
     # rows
     pr = sub.add_parser("rows", help="Row operations")
     rows_sub = pr.add_subparsers(dest="rows_cmd", required=True)