{"slug": "show-hn-auto-triage-customer-emails-to-linear-with-claude-and-pydantic-ai", "title": "Show HN: Auto-triage customer emails to Linear with Claude and pydantic-AI", "summary": "A developer released an open-source FastAPI webhook service that uses Claude AI and pydantic-AI to automatically triage customer emails into prioritized Linear issues, extracting priority, customer info, and issue type from raw email content and sending Slack alerts for urgent items.", "body_md": "Automatically convert incoming emails into prioritized Linear issues using AI-powered triage. Extract customer information, priority levels, and issue types from raw email content, then instantly create structured tickets in your Linear workspace with Slack notifications for urgent items.\n\nThis template provides a production-ready FastAPI webhook service that:\n\n- Accepts emails via SMTP forwarding or Gmail API integration\n- Extracts priority, customer, and issue classification using Claude AI\n- Creates Linear issues with rich metadata and proper linking\n- Sends Slack alerts for high-priority tickets\n- Stores triage decisions for audit and refinement\n\n**Why use this?**\n\n**Cost savings:** Eliminates $20-40/mo Zapier fees + manual triage overhead**Speed:** 30-second email-to-ticket pipeline vs. 5-minute manual routing**Consistency:** AI-driven classification reduces human error in priority assignment**Extensibility:** Built on Pydantic AI for easy customization of triage logic\n\n- Accepts raw email POST payloads (SMTP webhook format or parsed JSON)\n- Extracts sender, subject, body, and attachment metadata\n- Supports both plain text and HTML email bodies\n\nUses Claude to extract from email content:\n\n**Priority level**(urgent/high/normal/low)** Customer identifier**(email domain, name, account ID)** Issue type**(bug/feature-request/support/billing)** Summary**(auto-generated from subject + body context)** Suggested assignee**(based on issue type patterns, optional)\n\n- Creates issues in your Linear workspace\n- Attaches original email as issue comment\n- Sets priority and status based on triage output\n- Links to customer/team projects (configurable)\n- Supports custom fields for email metadata\n\n- Posts urgent/high-priority tickets to designated channel\n- Includes customer info, issue link, and priority badge\n- Optional thread replies for follow-up updates\n\n- Stores all triage decisions in SQLite (or configured DB)\n- Enables performance monitoring and model refinement\n- Supports manual override and feedback loops\n\n**Python 3.11+****Linear API token**(create in[Settings > API > Personal API Keys](https://linear.app/settings/api))** Claude API key**(from[Anthropic Console](https://console.anthropic.com/))** Slack webhook URL**(optional, from[Slack Apps](https://api.slack.com/apps))** Gmail API credentials**or SMTP relay service (optional, for email ingestion)\n\n- Docker + Docker Compose (for containerized deployment)\n- PostgreSQL (for production database, defaults to SQLite)\n\n```\ngit clone https://github.com/yourusername/email-linear-triage.git\ncd email-linear-triage\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\nCreate `.env`\n\nin the project root:\n\n```\n# API Keys\nANTHROPIC_API_KEY=sk-ant-...\nLINEAR_API_KEY=lin_api_...\nSLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL  # Optional\n\n# Linear Configuration\nLINEAR_TEAM_ID=acme  # Your Linear team slug (e.g., 'acme' from linear.app/acme)\nLINEAR_PROJECT_ID=INB  # Project key for incoming emails (default: 'INB')\nLINEAR_DEFAULT_STATUS=backlog  # Initial status for new issues\n\n# Email Configuration\nSMTP_SECRET_TOKEN=your-secret-token-here  # For webhook authentication\nEMAIL_DOMAIN=yourdomain.com\n\n# Database (optional)\nDATABASE_URL=sqlite:///./triage.db  # Or: postgresql://user:pass@localhost/triage\n\n# Feature Flags\nENABLE_SLACK_NOTIFICATIONS=true\nENABLE_AUTO_ASSIGN=false\nTRIAGE_MODEL=claude-3-5-sonnet-20241022  # Claude model to use\npython -m alembic upgrade head\n```\n\nOr for SQLite (auto-created):\n\n``` python\npython -c \"from app.db import init_db; init_db()\"\nuvicorn app.main:app --host 0.0.0.0 --port 8000 --reload\n```\n\nServer runs on `http://localhost:8000`\n\n**Option A: SMTP Forwarding** (Recommended)\n\n- In your email provider, set up a forward rule:\n**From:**`tickets@yourdomain.com`\n\n**To:**`{your-server}/webhook/email`\n\nwith authentication\n\n**Option B: Gmail API**\n\n- Enable\n[Gmail API](https://developers.google.com/gmail/api/quickstart/python)in Google Cloud Console - Download credentials JSON to\n`./credentials.json`\n\n- App auto-fetches labeled emails periodically\n\n**Option C: Manual Testing**\n\n```\ncurl -X POST http://localhost:8000/webhook/email \\\n  -H \"X-Webhook-Token: your-secret-token-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"from\": \"customer@example.com\",\n    \"subject\": \"Payment processing is broken\",\n    \"body\": \"Hi, our recurring invoices havent charged for 2 days. This is urgent!\",\n    \"timestamp\": \"2024-01-15T14:30:00Z\"\n  }'\n```\n\nIn Linear Settings > Integrations > Webhooks, add:\n\n**URL:**`{your-server}/webhook/linear-event`\n\n**Events:** Issue created, issue updated- Useful for closing issues via email replies\n\n**Email arrives** at`tickets@yourdomain.com`\n\n(forwarded via SMTP)**Webhook handler** receives POST, validates token**Claude triage** classifies email (2-5 seconds)**Linear issue created** with extracted metadata**Slack notification** posted (if urgent/high)**Response** returned with issue URL\n\n```\ncurl -X POST http://localhost:8000/webhook/email \\\n  -H \"X-Webhook-Token: your-secret-token-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"from\": \"sarah@acmecorp.com\",\n    \"subject\": \"[BUG] Dashboard crashes on mobile\",\n    \"body\": \"When I open the dashboard on iPhone, it instantly crashes. Happens every time. Our team cant work.\",\n    \"timestamp\": \"2024-01-15T09:30:00Z\"\n  }'\n```\n\n**Response (201 Created):**\n\n```\n{\n  \"status\": \"success\",\n  \"linear_issue_id\": \"INB-234\",\n  \"linear_issue_url\": \"https://linear.app/acme/issue/INB-234\",\n  \"triage_result\": {\n    \"priority\": \"urgent\",\n    \"issue_type\": \"bug\",\n    \"customer_domain\": \"acmecorp.com\",\n    \"summary\": \"Dashboard mobile app crashes on iOS\",\n    \"suggested_assignee\": \"eng-mobile\"\n  },\n  \"slack_notification_sent\": true,\n  \"processing_time_ms\": 3200\n}\n```\n\n**Ingest raw email and create Linear issue**\n\n**Headers:**\n\n```\nX-Webhook-Token: {SMTP_SECRET_TOKEN}\nContent-Type: application/json\n```\n\n**Request Body:**\n\n```\n{\n  \"from\": \"customer@example.com\",\n  \"subject\": \"Issue title\",\n  \"body\": \"Email body text\",\n  \"html_body\": \"<p>HTML version (optional)</p>\",\n  \"timestamp\": \"2024-01-15T10:00:00Z\",\n  \"attachments\": [\n    {\n      \"filename\": \"screenshot.png\",\n      \"content_base64\": \"iVBORw0KGgoAAAANS...\",\n      \"mime_type\": \"image/png\"\n    }\n  ]\n}\n```\n\n**Response (201 Created):**\n\n```\n{\n  \"status\": \"success|error\",\n  \"linear_issue_id\": \"INB-123\",\n  \"linear_issue_url\": \"string\",\n  \"triage_result\": {\n    \"priority\": \"urgent|high|normal|low\",\n    \"issue_type\": \"bug|feature|support|billing\",\n    \"customer_domain\": \"string\",\n    \"customer_name\": \"string (optional)\",\n    \"summary\": \"string\",\n    \"suggested_assignee\": \"string (optional)\"\n  },\n  \"slack_notification_sent\": boolean,\n  \"error\": \"string (if status='error')\"\n}\n```\n\n**Manually override AI triage decision**\n\n**Headers:**\n\n```\nX-API-Key: {LINEAR_API_KEY}\nContent-Type: application/json\n```\n\n**Request Body:**\n\n```\n{\n  \"priority\": \"high\",\n  \"issue_type\": \"bug\",\n  \"notes\": \"Manually corrected from 'low' due to context\"\n}\n```\n\n**Response (200 OK):**\n\n```\n{\n  \"status\": \"updated\",\n  \"triage_record_id\": \"uuid\",\n  \"changes\": {\n    \"priority\": {\"old\": \"normal\", \"new\": \"high\"}\n  }\n}\n```\n\n**Retrieve triage history and metrics**\n\n**Query Parameters:**\n\n`limit=50`\n\n(default)`offset=0`\n\n`priority_filter=urgent|high|normal|low`\n\n(optional)`date_from=2024-01-01`\n\n(optional)`date_to=2024-01-31`\n\n(optional)\n\n**Response (200 OK):**\n\n```\n{\n  \"total_processed\": 342,\n  \"results\": [\n    {\n      \"id\": \"uuid\",\n      \"email_from\": \"customer@example.com\",\n      \"linear_issue_id\": \"INB-234\",\n      \"priority\": \"high\",\n      \"issue_type\": \"bug\",\n      \"created_at\": \"2024-01-15T09:30:00Z\",\n      \"processing_time_ms\": 3200,\n      \"model_confidence\": 0.94\n    }\n  ],\n  \"statistics\": {\n    \"avg_processing_time_ms\": 2800,\n    \"priority_distribution\": {\n      \"urgent\": 15,\n      \"high\": 87,\n      \"normal\": 198,\n      \"low\": 42\n    },\n    \"issue_type_distribution\": {\n      \"bug\": 124,\n      \"feature\": 56,\n      \"support\": 142,\n      \"billing\": 20\n    }\n  }\n}\n```\n\n**Service health check**\n\n**Response (200 OK):**\n\n```\n{\n  \"status\": \"healthy\",\n  \"timestamp\": \"2024-01-15T10:00:00Z\",\n  \"dependencies\": {\n    \"anthropic\": \"ok\",\n    \"linear\": \"ok\",\n    \"slack\": \"ok\",\n    \"database\": \"ok\"\n  }\n}\n```\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n`ANTHROPIC_API_KEY` |\n✓ | — | Claude API key from Anthropic Console |\n`LINEAR_API_KEY` |\n✓ | — | Linear API token from Settings > API |\n`LINEAR_TEAM_ID` |\n✓ | — | Linear team slug (e.g., 'acme') |\n`LINEAR_PROJECT_ID` |\n`INB` |\nLinear project key for new issues | |\n`LINEAR_DEFAULT_STATUS` |\n`backlog` |\nInitial issue status (backlog/todo/in_progress) | |\n`SMTP_SECRET_TOKEN` |\n✓ | — | Secret token for webhook authentication |\n`SLACK_WEBHOOK_URL` |\n— | Slack webhook URL (leave empty to disable) | |\n`ENABLE_SLACK_NOTIFICATIONS` |\n`true` |\nPost notifications for urgent/high | |\n`ENABLE_AUTO_ASSIGN` |\n`false` |\nAutomatically assign based on issue type | |\n`TRIAGE_MODEL` |\n`claude-3-5-sonnet-20241022` |\nClaude model (3-opus-20250219 for best accuracy) | |\n`DATABASE_URL` |\n`sqlite:///./triage.db` |\nPostgreSQL or SQLite connection string | |\n`GMAIL_CREDENTIALS_PATH` |\n`./credentials.json` |\nPath to Gmail API credentials (if using Gmail) | |\n`EMAIL_DOMAIN` |\n— | Your email domain (for reply-to headers) | |\n`LOG_LEVEL` |\n`INFO` |\nLogging level (DEBUG/INFO/WARNING/ERROR) |\n\nEdit `app/config.py`\n\nto customize:\n\n```\n# Claude model settings\nTRIAGE_MODEL = \"claude-3-5-sonnet-20241022\"  # Change to claude-3-opus-20250219 for higher accuracy\n\n# Triage classification thresholds\nPRIORITY_KEYWORDS = {\n    \"urgent\": [\"critical\", \"down\", \"broken\", \"asap\", \"emergency\"],\n    \"high\": [\"bug\", \"broken\", \"failing\", \"urgent\"],\n    \"normal\": [\"feature\", \"improve\"],\n    \"low\": [\"typo\", \"minor\", \"nice-to-have\"]\n}\n\n# Linear field mappings\nLINEAR_PRIORITY_MAP = {\n    \"urgent\": 4,    # Urgent in Linear\n    \"high\": 3,\n    \"normal\": 2,\n    \"low\": 1\n}\n```\n\nEdit `app/agents/triage_agent.py`\n\n:\n\n```\nTRIAGE_SYSTEM_PROMPT = \"\"\"You are an expert customer support triage system...\nAnalyze the email and extract:\n1. Priority (urgent/high/normal/low) - consider customer tone, service impact, frequency\n2. Issue type (bug/feature/support/billing) - classify by nature\n3. Customer identifier - extract domain or company name\n4. Concise summary - max 10 words\n5. Suggested team - based on issue type\n\"\"\"\n```\n\nIn `app/models/triage.py`\n\n, extend `TriageResult`\n\n:\n\n```\nclass TriageResult(BaseModel):\n    priority: str\n    issue_type: str\n    customer_domain: str\n    summary: str\n    custom_field_1: str | None = None  # Add your field\n```\n\nThen update the Claude prompt to extract it, and Linear creation logic in `app/integrations/linear.py`\n\n:\n\n```\ncustom_field_id = \"LIN_CUSTOM_1\"\nissue_data[\"fieldValues\"].append({\n    \"fieldId\": custom_field_id,\n    \"value\": triage_result.custom_field_1\n})\n```\n\nIn `app/integrations/linear.py`\n\n, modify project selection:\n\n``` php\ndef get_target_project(triage_result: TriageResult) -> str:\n    if triage_result.issue_type == \"billing\":\n        return \"BIL\"  # Billing project\n    elif triage_result.customer_domain == \"enterprise.com\":\n        return \"ENT\"  # Enterprise project\n    return settings.LINEAR_PROJECT_ID\n```\n\nIn `app/integrations/slack.py`\n\n, edit the Slack payload:\n\n```\nblocks = [\n    {\n        \"type\": \"section\",\n        \"text\": {\n            \"type\": \"mrkdwn\",\n            \"text\": f\"🔴 *URGENT: {triage_result.summary}*\\nCustomer: {triage_result.customer_domain}\\n<{issue_url}|View in Linear>\"\n        }\n    }\n]\n```\n\nFor **higher accuracy** (slower + more expensive):\n\n```\nTRIAGE_MODEL=claude-3-opus-20250219 python -m uvicorn app.main:app\n```\n\nFor **lower cost** (faster):\n\n```\nTRIAGE_MODEL=claude-3-5-haiku-20241022 python -m uvicorn app.main:app\n```\n\nSwitch from SQLite to PostgreSQL:\n\n```\npip install psycopg2-binary\nexport DATABASE_URL=postgresql://user:password@localhost:5432/triage\npython -m alembic upgrade head\npytest tests/ -v\npython -m app.agents.triage_agent --email-from \"customer@example.com\" --subject \"Payment failed\" --body \"We can't process payments today\"\npython scripts/test_email_webhook.py\ndocker-compose up -d\n```\n\nSee `docker-compose.yml`\n\nfor production config (PostgreSQL, environment variables).\n\n```\ngit push heroku main\nheroku config:set ANTHROPIC_API_KEY=sk-ant-...\nheroku config:set LINEAR_API_KEY=lin_api_...\npip install aws-wsgi\n# See Dockerfile.lambda for container image setup\n```\n\n**\"Invalid Linear API Key\"**\n\n- Verify token in\n[Settings > API > Personal API Keys](https://linear.app/settings/api) - Ensure token has\n`read`\n\nand`write`\n\nscopes\n\n**\"Claude rate limit exceeded\"**\n\n- Upgrade Anthropic plan or implement request queueing\n- Batch emails in peak hours\n\n**\"Slack notification not sent\"**\n\n- Verify\n`SLACK_WEBHOOK_URL`\n\nis set and valid - Check Slack workspace webhook permissions\n- Set\n`ENABLE_SLACK_NOTIFICATIONS=false`\n\nto skip errors\n\n**\"Database connection error\"**\n\n- For SQLite: ensure\n`triage.db`\n\ndirectory is writable - For PostgreSQL: verify host/port/credentials\n- Run\n`python -c \"from app.db import init_db; init_db()\"`\n\nto reinitialize\n\nTypical performance on Sonnet 3.5:\n\n**Email parsing:** 50ms**Claude triage:** 2-4s (network + inference)**Linear issue creation:** 300-800ms**Slack notification:** 200-500ms**Total end-to-end:** 2.5-6s\n\nMIT License — see LICENSE file for details.\n\nBuilt with [Pydantic AI](https://github.com/pydantic/pydantic-ai), [FastAPI](https://fastapi.tiangolo.com/), and [Linear API](https://linear.app/docs).", "url": "https://wpnews.pro/news/show-hn-auto-triage-customer-emails-to-linear-with-claude-and-pydantic-ai", "canonical_source": "https://github.com/Reactance0083/pydantic-ai-email-linear-auto-triage", "published_at": "2026-06-16 13:02:00+00:00", "updated_at": "2026-06-16 13:20:00.466115+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-tools", "ai-agents", "developer-tools", "generative-ai"], "entities": ["Claude", "Linear", "Slack", "FastAPI", "pydantic-AI", "Anthropic", "Gmail", "PostgreSQL"], "alternates": {"html": "https://wpnews.pro/news/show-hn-auto-triage-customer-emails-to-linear-with-claude-and-pydantic-ai", "markdown": "https://wpnews.pro/news/show-hn-auto-triage-customer-emails-to-linear-with-claude-and-pydantic-ai.md", "text": "https://wpnews.pro/news/show-hn-auto-triage-customer-emails-to-linear-with-claude-and-pydantic-ai.txt", "jsonld": "https://wpnews.pro/news/show-hn-auto-triage-customer-emails-to-linear-with-claude-and-pydantic-ai.jsonld"}}