Email Inbound

The Email Inbound API handles incoming email from external mail services (Mailgun) and provides endpoints for the unified inbox.

Endpoints

Method	Path	Description
POST	/api/v1/email/inbound	Receive inbound email from Mailgun webhook
POST	/api/v1/inbox/upload	Upload documents to the unified inbox
GET	/api/v1/inbox/document/{id}/related	Get related emails and documents for an inbox document

Mailgun Webhook

POST /api/v1/email/inbound

This endpoint receives inbound email from Mailgun. It is authenticated via Mailgun's HMAC signature verification (not via API key). The system automatically:

1. Parses the email (headers, body, attachments)
2. Creates a correspondence record
3. Extracts and stores attachments as documents
4. Attempts to match the sender to an existing party
5. Runs AI triage (category, priority, suggested assignment)

Request (from Mailgun)

The request body is application/x-www-form-urlencoded with Mailgun's standard fields:

Field	Description
from	Sender email address
to	Recipient email address
subject	Email subject line
body-plain	Plain text body
body-html	HTML body
attachment-N	Attached files (multipart)
timestamp	Mailgun timestamp
token	Mailgun token
signature	HMAC-SHA256 signature

Response

Returns 200 OK on successful processing. The system processes the email asynchronously.

Upload to Inbox

POST /api/v1/inbox/upload
Content-Type: multipart/form-data

Upload one or more documents directly to the unified inbox. Documents go through the same processing pipeline as emailed documents.

Form Fields

Field	Type	Required	Description
files	File[]	Yes	One or more files to upload
source	string	No	Source identifier (e.g., "scanner", "drag-drop")

Response

{
  "uploaded": [
    {
      "document_id": "doc_01ABCDEF",
      "filename": "contract.pdf",
      "status": "processing"
    }
  ]
}

Related Documents

GET /api/v1/inbox/document/{document_id}/related

Returns all emails and documents related to an inbox document -- emails from the same sender, documents in the same case, etc.

Response

{
  "emails": [
    {
      "id": "corr_01",
      "subject": "RE: Contract Review",
      "from": "client@example.com",
      "received_at": "2026-05-20T14:00:00Z"
    }
  ],
  "documents": [
    {
      "id": "doc_01ABCDEF",
      "filename": "contract_v2.pdf",
      "case_id": "550e8400-..."
    }
  ]
}

Next Steps

• Email Outbound -- Send emails and manage drafts
• Documents -- Document management