Show HN: Auto-triage customer emails to Linear with Claude and pydantic-AI

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.

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. This template provides a production-ready FastAPI webhook service that: - Accepts emails via SMTP forwarding or Gmail API integration - Extracts priority, customer, and issue classification using Claude AI - Creates Linear issues with rich metadata and proper linking - Sends Slack alerts for high-priority tickets - Stores triage decisions for audit and refinement Why use this? 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 - Accepts raw email POST payloads SMTP webhook format or parsed JSON - Extracts sender, subject, body, and attachment metadata - Supports both plain text and HTML email bodies Uses Claude to extract from email content: 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 - Creates issues in your Linear workspace - Attaches original email as issue comment - Sets priority and status based on triage output - Links to customer/team projects configurable - Supports custom fields for email metadata - Posts urgent/high-priority tickets to designated channel - Includes customer info, issue link, and priority badge - Optional thread replies for follow-up updates - Stores all triage decisions in SQLite or configured DB - Enables performance monitoring and model refinement - Supports manual override and feedback loops 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 - Docker + Docker Compose for containerized deployment - PostgreSQL for production database, defaults to SQLite git clone https://github.com/yourusername/email-linear-triage.git cd email-linear-triage python -m venv venv source venv/bin/activate On Windows: venv\Scripts\activate pip install -r requirements.txt Create .env in the project root: API Keys ANTHROPIC API KEY=sk-ant-... LINEAR API KEY=lin api ... SLACK WEBHOOK URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL Optional Linear Configuration LINEAR TEAM ID=acme Your Linear team slug e.g., 'acme' from linear.app/acme LINEAR PROJECT ID=INB Project key for incoming emails default: 'INB' LINEAR DEFAULT STATUS=backlog Initial status for new issues Email Configuration SMTP SECRET TOKEN=your-secret-token-here For webhook authentication EMAIL DOMAIN=yourdomain.com Database optional DATABASE URL=sqlite:///./triage.db Or: postgresql://user:pass@localhost/triage Feature Flags ENABLE SLACK NOTIFICATIONS=true ENABLE AUTO ASSIGN=false TRIAGE MODEL=claude-3-5-sonnet-20241022 Claude model to use python -m alembic upgrade head Or for SQLite auto-created : python python -c "from app.db import init db; init db " uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload Server runs on http://localhost:8000 Option A: SMTP Forwarding Recommended - In your email provider, set up a forward rule: From: tickets@yourdomain.com To: {your-server}/webhook/email with authentication Option B: Gmail API - Enable Gmail API https://developers.google.com/gmail/api/quickstart/python in Google Cloud Console - Download credentials JSON to ./credentials.json - App auto-fetches labeled emails periodically Option C: Manual Testing curl -X POST http://localhost:8000/webhook/email \ -H "X-Webhook-Token: your-secret-token-here" \ -H "Content-Type: application/json" \ -d '{ "from": "customer@example.com", "subject": "Payment processing is broken", "body": "Hi, our recurring invoices havent charged for 2 days. This is urgent ", "timestamp": "2024-01-15T14:30:00Z" }' In Linear Settings Integrations Webhooks, add: URL: {your-server}/webhook/linear-event Events: Issue created, issue updated- Useful for closing issues via email replies Email arrives at tickets@yourdomain.com 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 curl -X POST http://localhost:8000/webhook/email \ -H "X-Webhook-Token: your-secret-token-here" \ -H "Content-Type: application/json" \ -d '{ "from": "sarah@acmecorp.com", "subject": " BUG Dashboard crashes on mobile", "body": "When I open the dashboard on iPhone, it instantly crashes. Happens every time. Our team cant work.", "timestamp": "2024-01-15T09:30:00Z" }' Response 201 Created : { "status": "success", "linear issue id": "INB-234", "linear issue url": "https://linear.app/acme/issue/INB-234", "triage result": { "priority": "urgent", "issue type": "bug", "customer domain": "acmecorp.com", "summary": "Dashboard mobile app crashes on iOS", "suggested assignee": "eng-mobile" }, "slack notification sent": true, "processing time ms": 3200 } Ingest raw email and create Linear issue Headers: X-Webhook-Token: {SMTP SECRET TOKEN} Content-Type: application/json Request Body: { "from": "customer@example.com", "subject": "Issue title", "body": "Email body text", "html body": "<p HTML version optional </p ", "timestamp": "2024-01-15T10:00:00Z", "attachments": { "filename": "screenshot.png", "content base64": "iVBORw0KGgoAAAANS...", "mime type": "image/png" } } Response 201 Created : { "status": "success|error", "linear issue id": "INB-123", "linear issue url": "string", "triage result": { "priority": "urgent|high|normal|low", "issue type": "bug|feature|support|billing", "customer domain": "string", "customer name": "string optional ", "summary": "string", "suggested assignee": "string optional " }, "slack notification sent": boolean, "error": "string if status='error' " } Manually override AI triage decision Headers: X-API-Key: {LINEAR API KEY} Content-Type: application/json Request Body: { "priority": "high", "issue type": "bug", "notes": "Manually corrected from 'low' due to context" } Response 200 OK : { "status": "updated", "triage record id": "uuid", "changes": { "priority": {"old": "normal", "new": "high"} } } Retrieve triage history and metrics Query Parameters: limit=50 default offset=0 priority filter=urgent|high|normal|low optional date from=2024-01-01 optional date to=2024-01-31 optional Response 200 OK : { "total processed": 342, "results": { "id": "uuid", "email from": "customer@example.com", "linear issue id": "INB-234", "priority": "high", "issue type": "bug", "created at": "2024-01-15T09:30:00Z", "processing time ms": 3200, "model confidence": 0.94 } , "statistics": { "avg processing time ms": 2800, "priority distribution": { "urgent": 15, "high": 87, "normal": 198, "low": 42 }, "issue type distribution": { "bug": 124, "feature": 56, "support": 142, "billing": 20 } } } Service health check Response 200 OK : { "status": "healthy", "timestamp": "2024-01-15T10:00:00Z", "dependencies": { "anthropic": "ok", "linear": "ok", "slack": "ok", "database": "ok" } } | Variable | Required | Default | Description | |---|---|---|---| ANTHROPIC API KEY | ✓ | — | Claude API key from Anthropic Console | LINEAR API KEY | ✓ | — | Linear API token from Settings API | LINEAR TEAM ID | ✓ | — | Linear team slug e.g., 'acme' | LINEAR PROJECT ID | INB | Linear project key for new issues | | LINEAR DEFAULT STATUS | backlog | Initial issue status backlog/todo/in progress | | SMTP SECRET TOKEN | ✓ | — | Secret token for webhook authentication | SLACK WEBHOOK URL | — | Slack webhook URL leave empty to disable | | ENABLE SLACK NOTIFICATIONS | true | Post notifications for urgent/high | | ENABLE AUTO ASSIGN | false | Automatically assign based on issue type | | TRIAGE MODEL | claude-3-5-sonnet-20241022 | Claude model 3-opus-20250219 for best accuracy | | DATABASE URL | sqlite:///./triage.db | PostgreSQL or SQLite connection string | | GMAIL CREDENTIALS PATH | ./credentials.json | Path to Gmail API credentials if using Gmail | | EMAIL DOMAIN | — | Your email domain for reply-to headers | | LOG LEVEL | INFO | Logging level DEBUG/INFO/WARNING/ERROR | Edit app/config.py to customize: Claude model settings TRIAGE MODEL = "claude-3-5-sonnet-20241022" Change to claude-3-opus-20250219 for higher accuracy Triage classification thresholds PRIORITY KEYWORDS = { "urgent": "critical", "down", "broken", "asap", "emergency" , "high": "bug", "broken", "failing", "urgent" , "normal": "feature", "improve" , "low": "typo", "minor", "nice-to-have" } Linear field mappings LINEAR PRIORITY MAP = { "urgent": 4, Urgent in Linear "high": 3, "normal": 2, "low": 1 } Edit app/agents/triage agent.py : TRIAGE SYSTEM PROMPT = """You are an expert customer support triage system... Analyze the email and extract: 1. Priority urgent/high/normal/low - consider customer tone, service impact, frequency 2. Issue type bug/feature/support/billing - classify by nature 3. Customer identifier - extract domain or company name 4. Concise summary - max 10 words 5. Suggested team - based on issue type """ In app/models/triage.py , extend TriageResult : class TriageResult BaseModel : priority: str issue type: str customer domain: str summary: str custom field 1: str | None = None Add your field Then update the Claude prompt to extract it, and Linear creation logic in app/integrations/linear.py : custom field id = "LIN CUSTOM 1" issue data "fieldValues" .append { "fieldId": custom field id, "value": triage result.custom field 1 } In app/integrations/linear.py , modify project selection: php def get target project triage result: TriageResult - str: if triage result.issue type == "billing": return "BIL" Billing project elif triage result.customer domain == "enterprise.com": return "ENT" Enterprise project return settings.LINEAR PROJECT ID In app/integrations/slack.py , edit the Slack payload: blocks = { "type": "section", "text": { "type": "mrkdwn", "text": f"🔴 URGENT: {triage result.summary} \nCustomer: {triage result.customer domain}\n<{issue url}|View in Linear " } } For higher accuracy slower + more expensive : TRIAGE MODEL=claude-3-opus-20250219 python -m uvicorn app.main:app For lower cost faster : TRIAGE MODEL=claude-3-5-haiku-20241022 python -m uvicorn app.main:app Switch from SQLite to PostgreSQL: pip install psycopg2-binary export DATABASE URL=postgresql://user:password@localhost:5432/triage python -m alembic upgrade head pytest tests/ -v python -m app.agents.triage agent --email-from "customer@example.com" --subject "Payment failed" --body "We can't process payments today" python scripts/test email webhook.py docker-compose up -d See docker-compose.yml for production config PostgreSQL, environment variables . git push heroku main heroku config:set ANTHROPIC API KEY=sk-ant-... heroku config:set LINEAR API KEY=lin api ... pip install aws-wsgi See Dockerfile.lambda for container image setup "Invalid Linear API Key" - Verify token in Settings API Personal API Keys https://linear.app/settings/api - Ensure token has read and write scopes "Claude rate limit exceeded" - Upgrade Anthropic plan or implement request queueing - Batch emails in peak hours "Slack notification not sent" - Verify SLACK WEBHOOK URL is set and valid - Check Slack workspace webhook permissions - Set ENABLE SLACK NOTIFICATIONS=false to skip errors "Database connection error" - For SQLite: ensure triage.db directory is writable - For PostgreSQL: verify host/port/credentials - Run python -c "from app.db import init db; init db " to reinitialize Typical performance on Sonnet 3.5: 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 MIT License — see LICENSE file for details. Built with Pydantic AI https://github.com/pydantic/pydantic-ai , FastAPI https://fastapi.tiangolo.com/ , and Linear API https://linear.app/docs .