Add trusted forwarded contact intake

.env.example

@@ -294,6 +294,11 @@ EMAIL_RESUME_INTAKE_ENABLED=false
 EMAIL_RESUME_ALLOWED_EXTENSIONS=pdf,doc,docx
 EMAIL_RESUME_MAX_FILE_SIZE_MB=10
 EMAIL_REQUIRE_SENDER_AUTH_HEADERS=true
+CONTACT_EMAIL_ACTION_CLASSIFIER_ENABLED=true
+# CONTACT_EMAIL_ACTION_CLASSIFIER_MODEL=gpt-4.1-mini
+CONTACT_EMAIL_ACTION_CLASSIFIER_TIMEOUT_SECONDS=8.0
+CONTACT_EMAIL_EXTRACTION_ENABLED=true
+# CONTACT_EMAIL_EXTRACTION_MODEL=gpt-4.1-mini
 
 # Migadu mailbox automation settings are dashboard-managed in normal deployments.
 # Set non-empty env values only when you intentionally want env to lock dashboard edits.

ENVIRONMENT.md

@@ -142,6 +142,14 @@ Pydantic import errors.
 - `Required when EMAIL_RESUME_INTAKE_ENABLED=true`: `EMAIL_USERNAME`, `EMAIL_PASSWORD`, `IMAP_SERVER`
 - Note: resume intake writes LinkedIn URLs to `cLinkedIn`, leaves the intake-completed field unset, and matches resume filenames using `resume,cv,curriculum`.
 
+- Optional: CONTACT_EMAIL_INTAKE_ADDRESS (default: contacts@508.dev; only messages with this value in Delivered-To or X-Original-To become dashboard contact candidates).
+- Note: mail not delivery-addressed to CONTACT_EMAIL_INTAKE_ADDRESS stays on the existing resume intake path. Contact candidates are stored for dashboard approval and only create or update EspoCRM after an explicit review action.
+- `Optional`: `CONTACT_EMAIL_ACTION_CLASSIFIER_ENABLED` (default: `true`; use the configured OpenAI-compatible provider to classify non-alias workflow-mailbox mail as create-contact, review-contact, resume, or ignore)
+- `Optional`: `CONTACT_EMAIL_ACTION_CLASSIFIER_MODEL` (defaults to the configured fast, fallback, or primary model) and `CONTACT_EMAIL_ACTION_CLASSIFIER_TIMEOUT_SECONDS` (default: `8.0`)
+- `Optional`: `CONTACT_EMAIL_EXTRACTION_ENABLED` (default: `true`) and `CONTACT_EMAIL_EXTRACTION_MODEL` (defaults to the action classifier model) enable schema-validated name, email, and link extraction for review candidates, including `contacts@` mail.
+- Note: enabling contact extraction sends the forwarded message content to the configured OpenAI-compatible provider for extraction. Disable it when that data-sharing path is not appropriate for the mailbox.
+- Note: the model returns only schema-validated proposals. A create-contact proposal still requires an authenticated privileged sender and a forwarded, distinct name/email; it is persisted and audit-logged before CRM creation or linking. A review-contact proposal creates a dashboard candidate. `contacts@` extraction never creates a CRM contact; the dashboard remains the required approval point. If either classifier is unavailable, a conservative deterministic fallback is used.
+
 ## Onboarding Email Sending
 
 - `Optional`: `ONBOARDING_EMAIL_SMTP_SERVER` (dashboard-configurable; falls back to `SMTP_SERVER`; for Migadu use `smtp.migadu.com`)

apps/admin_dashboard/src/main.tsx

@@ -61,6 +61,12 @@ import {
   type JobPostChannel,
   type JobPostChannelTag,
 } from "@/views/configuration-view"
+import {
+  type ContactEmailCandidate,
+  type ContactEmailCandidateDecision,
+  ContactEmailCandidatesPanel,
+} from "@/views/contact-email-candidates"
+import { ContactEmailIntakePanel } from "@/views/contact-email-intake-panel"
 import {
   type NewsletterStatus,
   type NewsletterSuppression,
@@ -889,6 +895,7 @@ function App() {
   const [newsletterSuppressions, setNewsletterSuppressions] = useState<NewsletterSuppression[]>([])
   const [newsletterStatus, setNewsletterStatus] = useState<NewsletterStatus | null>(null)
   const [onboarding, setOnboarding] = useState<Person[]>([])
+  const [contactEmailCandidates, setContactEmailCandidates] = useState<ContactEmailCandidate[]>([])
   const [auditEvents, setAuditEvents] = useState<AuditEvent[]>([])
   const [agentReport, setAgentReport] = useState<AgentReport | null>(null)
   const [configurationItems, setConfigurationItems] = useState<ConfigurationItem[]>([])
@@ -1916,15 +1923,54 @@ function App() {
   async function loadOnboarding() {
     setBusy("onboarding", true)
     try {
-      const payload = await requestJson<Person[]>(onboardingUrl())
-      setOnboarding(payload)
+      const [peoplePayload, candidatesPayload] = await Promise.all([
+        requestJson<Person[]>(onboardingUrl()),
+        requestJson<ContactEmailCandidate[]>("/dashboard/api/onboarding/contact-candidates"),
+      ])
+      setOnboarding(peoplePayload)
+      setContactEmailCandidates(candidatesPayload)
     } catch (error) {
       showError(error, "Unable to load onboarding")
     } finally {
       setBusy("onboarding", false)
     }
   }
 
+  async function reviewContactEmailCandidate(
+    candidate: ContactEmailCandidate,
+    decision: ContactEmailCandidateDecision,
+  ) {
+    const key = `contact-email-candidate:${candidate.id}`
+    setBusy(key, true)
+    try {
+      const result = await requestJson<ContactEmailCandidate & { crm_action?: string }>(
+        "/dashboard/api/onboarding/contact-candidates/" +
+          encodeURIComponent(candidate.id) +
+          "/review",
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(decision),
+        },
+      )
+      setContactEmailCandidates((current) =>
+        current.filter((currentCandidate) => currentCandidate.id !== result.id),
+      )
+      showToast(
+        decision.decision === "dismiss"
+          ? "Dismissed contact candidate"
+          : result.crm_action === "linked_existing"
+            ? "Linked existing CRM contact"
+            : "Created CRM contact",
+        "ok",
+      )
+    } catch (error) {
+      showError(error, "Unable to review contact candidate")
+    } finally {
+      setBusy(key, false)
+    }
+  }
+
   async function draftOnboardingEmail(
     contactId: string | undefined,
     options: OnboardingEmailOptions,
@@ -2868,6 +2914,7 @@ function App() {
           {view === "onboarding" ? (
             <OnboardingView
               people={sortedOnboarding}
+              contactEmailCandidates={contactEmailCandidates}
               sort={sort.onboarding}
               loading={loading}
               onboardingQuery={onboardingQuery}
@@ -2884,6 +2931,7 @@ function App() {
               onDraftEmail={draftOnboardingEmail}
               onSendEmail={sendOnboardingEmail}
               onSetupEngineer={setupEngineer}
+              onReviewContactEmailCandidate={reviewContactEmailCandidate}
               setOnboardingQuery={setOnboardingQuery}
               setOnboardingState={setOnboardingState}
               setOnboarderFilter={setOnboarderFilter}
@@ -6726,6 +6774,7 @@ function PeopleView(props: {
 
 function OnboardingView(props: {
   people: Person[]
+  contactEmailCandidates: ContactEmailCandidate[]
   sort: { key: string; direction: SortDirection }
   loading: Record<string, boolean>
   canWrite: boolean
@@ -6750,6 +6799,10 @@ function OnboardingView(props: {
     markdownBody: string,
   ) => Promise<OnboardingEmailDraft | null>
   onSetupEngineer: (payload: EngineerSetupRequest) => Promise<EngineerSetupResult | null>
+  onReviewContactEmailCandidate: (
+    candidate: ContactEmailCandidate,
+    decision: ContactEmailCandidateDecision,
+  ) => void
   canConfigure: boolean
   onOpenConfiguration: () => void
   setOnboardingQuery: (value: string) => void
@@ -6765,6 +6818,18 @@ function OnboardingView(props: {
   const filterOptions = peopleFilterDefinitions[props.onboardingFilterKind]?.options || []
   return (
     <>
+      <ContactEmailIntakePanel />
+      <ContactEmailCandidatesPanel
+        candidates={props.contactEmailCandidates}
+        canWrite={props.canWrite}
+        loading={
+          props.loading.onboarding ||
+          Object.keys(props.loading).some(
+            (key) => key.startsWith("contact-email-candidate:") && props.loading[key],
+          )
+        }
+        onReview={props.onReviewContactEmailCandidate}
+      />
       {props.canWrite ? (
         <EngineerSetupPanel loading={props.loading.engineerSetup} onSetup={props.onSetupEngineer} />
       ) : null}

apps/admin_dashboard/src/views/contact-email-candidates.test.tsx

@@ -0,0 +1,47 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react"
+import { afterEach, describe, expect, it, vi } from "vitest"
+
+import { ContactEmailCandidatesPanel } from "./contact-email-candidates"
+
+afterEach(cleanup)
+
+describe("ContactEmailCandidatesPanel", () => {
+  it("keeps the candidate editable and dispatches an explicit approval action", () => {
+    const onReview = vi.fn()
+    render(
+      <ContactEmailCandidatesPanel
+        canWrite
+        loading={false}
+        onReview={onReview}
+        candidates={[
+          {
+            id: "candidate-1",
+            status: "pending",
+            delivered_to: "contacts@508.dev",
+            proposed_name: "Ada Lovelace",
+            proposed_email: "ada@example.com",
+            subject: "Introduction",
+            body_text: "See https://example.com/ada",
+            links: ["https://example.com/ada"],
+            extraction_method: "inline_forward",
+          },
+        ]}
+      />,
+    )
+
+    fireEvent.change(screen.getByLabelText("Contact name for candidate-1"), {
+      target: { value: "Ada Byron" },
+    })
+    fireEvent.click(screen.getByRole("button", { name: "Approve contact" }))
+
+    expect(onReview).toHaveBeenCalledWith(expect.objectContaining({ id: "candidate-1" }), {
+      decision: "approve",
+      name: "Ada Byron",
+      email: "ada@example.com",
+    })
+    expect(screen.getByRole("link", { name: /https:\/\/example.com\/ada/ })).toHaveAttribute(
+      "href",
+      "https://example.com/ada",
+    )
+  })
+})

apps/admin_dashboard/src/views/contact-email-candidates.tsx

@@ -0,0 +1,172 @@
+import { ExternalLink, UserCheck, UserX } from "lucide-react"
+import { useState } from "react"
+
+import { Empty } from "@/components/empty"
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+
+export type ContactEmailCandidate = {
+  id: string
+  status: "pending" | "approved" | "dismissed"
+  delivered_to: string
+  forwarded_by_name?: string | null
+  forwarded_by_email?: string | null
+  proposed_name?: string | null
+  proposed_email?: string | null
+  subject?: string | null
+  body_text?: string | null
+  links?: string[]
+  extraction_method?: string
+  created_at?: string
+}
+
+export type ContactEmailCandidateDecision = {
+  decision: "approve" | "dismiss"
+  name?: string
+  email?: string
+}
+
+function CandidateCard({
+  candidate,
+  canWrite,
+  loading,
+  onReview,
+}: {
+  candidate: ContactEmailCandidate
+  canWrite: boolean
+  loading: boolean
+  onReview: (candidate: ContactEmailCandidate, decision: ContactEmailCandidateDecision) => void
+}) {
+  const [name, setName] = useState(candidate.proposed_name || "")
+  const [email, setEmail] = useState(candidate.proposed_email || "")
+  const forwarder = [candidate.forwarded_by_name, candidate.forwarded_by_email]
+    .filter(Boolean)
+    .join(" · ")
+
+  return (
+    <article className="grid gap-3 rounded-md border p-3">
+      <div className="flex flex-wrap items-start justify-between gap-2">
+        <div>
+          <h3 className="font-semibold">{candidate.subject || "Forwarded contact"}</h3>
+          <p className="text-sm text-muted-foreground">
+            {forwarder ? `Forwarded by ${forwarder}` : "Forwarded email"} ·{" "}
+            {candidate.extraction_method?.replace(/_/g, " ") || "deterministic extraction"}
+          </p>
+        </div>
+        <Badge variant="queued">Needs review</Badge>
+      </div>
+
+      <div className="grid gap-3 md:grid-cols-2">
+        <Label>
+          Contact name
+          <Input
+            aria-label={`Contact name for ${candidate.id}`}
+            value={name}
+            autoComplete="off"
+            onChange={(event) => setName(event.target.value)}
+            disabled={!canWrite || loading}
+          />
+        </Label>
+        <Label>
+          Contact email
+          <Input
+            aria-label={`Contact email for ${candidate.id}`}
+            value={email}
+            type="email"
+            autoComplete="off"
+            onChange={(event) => setEmail(event.target.value)}
+            disabled={!canWrite || loading}
+          />
+        </Label>
+      </div>
+
+      {candidate.links?.length ? (
+        <div className="flex flex-wrap gap-2 text-sm">
+          {candidate.links.map((link) => (
+            <a
+              key={link}
+              className="inline-flex max-w-full items-center gap-1 text-primary underline"
+              href={link}
+              target="_blank"
+              rel="noreferrer"
+            >
+              <span className="truncate">{link}</span>
+              <ExternalLink className="size-3 shrink-0" aria-hidden="true" />
+            </a>
+          ))}
+        </div>
+      ) : null}
+
+      {candidate.body_text ? (
+        <details className="rounded-md bg-muted/40 p-3 text-sm">
+          <summary className="cursor-pointer font-semibold">Source email</summary>
+          <pre className="mt-2 whitespace-pre-wrap break-words font-sans text-muted-foreground">
+            {candidate.body_text}
+          </pre>
+        </details>
+      ) : null}
+
+      {canWrite ? (
+        <div className="flex flex-wrap gap-2">
+          <Button
+            type="button"
+            disabled={loading || !name.trim() || !email.trim()}
+            onClick={() => onReview(candidate, { decision: "approve", name, email })}
+          >
+            <UserCheck />
+            Approve contact
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            disabled={loading}
+            onClick={() => onReview(candidate, { decision: "dismiss" })}
+          >
+            <UserX />
+            Dismiss
+          </Button>
+        </div>
+      ) : null}
+    </article>
+  )
+}
+
+export function ContactEmailCandidatesPanel({
+  candidates,
+  canWrite,
+  loading,
+  onReview,
+}: {
+  candidates: ContactEmailCandidate[]
+  canWrite: boolean
+  loading: boolean
+  onReview: (candidate: ContactEmailCandidate, decision: ContactEmailCandidateDecision) => void
+}) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Contact candidates</CardTitle>
+        <span className="text-sm text-muted-foreground">
+          {loading ? "Loading" : `${candidates.length} awaiting review`}
+        </span>
+      </CardHeader>
+      <CardContent className="grid gap-3">
+        <Empty hidden={candidates.length !== 0}>
+          No forwarded contacts are waiting for review.
+        </Empty>
+        {candidates.map((candidate) => (
+          <CandidateCard
+            key={candidate.id}
+            candidate={candidate}
+            canWrite={canWrite}
+            loading={loading}
+            onReview={onReview}
+          />
+        ))}
+      </CardContent>
+    </Card>
+  )
+}