# Lucion AI Mailing — Public API

Programmatic access to a multi-tenant AI email management platform.
Base URL: https://mail.lucionesports.com

## Authentication
All requests require: `Authorization: Bearer lct_xxxxxxxxxxxxxxx`
Get a token at: https://mail.lucionesports.com/developers

## Scopes (set on each token)
- `inboxes:read` — list and read inboxes
- `drafts:read` — list and read drafts
- `drafts:write` — create/edit/approve/reject drafts
- `drafts:send` — actually send a draft (separate from write — least-privilege)
- `email:ai` — call AI tools (compose, summarize-thread, suggest-reply)
- `campaigns:read` — list and read campaigns
- `campaigns:write` — create campaigns and generate drafts
- `audit:read` — read audit log and activity feed
- `threads:read` — read threads + messages
- `escalations:read` / `escalations:write` — read/respond to escalations
- `kb:read` / `kb:write` — read/manage the tenant's knowledge base
- `metrics:read` — dashboard metrics
- `webhooks:manage` — outbound webhook CRUD
- `*` — full access (use sparingly)

## Endpoints
- GET /api/v1/activity — V1 Activity
- GET /api/v1/ai-questions — V1 List Ai Questions
- GET /api/v1/audit-log — V1 Audit Log
- POST /api/v1/campaigns — V1 Create Campaign
- GET /api/v1/campaigns — V1 List Campaigns
- GET /api/v1/campaigns/{campaign_id} — V1 Get Campaign
- POST /api/v1/campaigns/{campaign_id}/generate-drafts — V1 Campaign Generate Drafts
- POST /api/v1/drafts — V1 Create Draft
- GET /api/v1/drafts — V1 List Drafts
- GET /api/v1/drafts/{draft_id} — V1 Get Draft
- PATCH /api/v1/drafts/{draft_id} — V1 Patch Draft
- POST /api/v1/drafts/{draft_id}/approve — V1 Approve Draft
- POST /api/v1/drafts/{draft_id}/reject — V1 Reject Draft
- POST /api/v1/drafts/{draft_id}/send — V1 Send Draft
- POST /api/v1/email/compose — V1 Email Compose
- POST /api/v1/email/suggest-reply — V1 Email Suggest
- POST /api/v1/email/summarize-thread — V1 Email Summarize
- GET /api/v1/escalations — V1 List Escalations
- POST /api/v1/escalations/{esc_id}/respond — V1 Respond Escalation
- GET /api/v1/inboxes — V1 List Inboxes
- GET /api/v1/inboxes/{inbox_id} — V1 Get Inbox
- GET /api/v1/kb — V1 List Kb
- GET /api/v1/kb/{kb_id} — V1 Get Kb
- GET /api/v1/metrics/dashboard — V1 Metrics
- GET /api/v1/threads — V1 List Threads
- GET /api/v1/threads/{thread_id} — V1 Get Thread
- GET /api/v1/whoami — V1 Whoami

## Example: Send an email via Drafts API

```bash
TOKEN="lct_REPLACE_WITH_YOUR_DEV_TOKEN"  # generate at /developers
BASE="https://mail.lucionesports.com"

# 1. List inboxes
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/inboxes"

# 2. Create a draft
curl -X POST "$BASE/api/v1/drafts" -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" -d '{"inbox_id":"ibx_xxx","to_email":"customer@example.com","subject":"Hello","body":"Hi there"}'

# 3. Send it (requires drafts:send scope)
curl -X POST "$BASE/api/v1/drafts/{draft_id}/send" -H "Authorization: Bearer $TOKEN"
```

## Example: AI-compose a reply

```bash
curl -X POST "$BASE/api/v1/email/suggest-reply" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"thread_id":"thr_xxx","tone":"professional"}'
```

## Outbound webhooks
Register a URL at Portal → Settings → Developers → Webhooks to receive HMAC-signed POSTs
for events: thread.created, escalation.created, escalation.resolved, ai_question.opened,
draft.sent, kb.updated, and more. Verify signature using `X-Webhook-Signature` header.

## Interactive docs
OpenAPI JSON:  https://mail.lucionesports.com/api/v1/openapi.json
Swagger UI:    https://mail.lucionesports.com/api/v1/docs
This file:     https://mail.lucionesports.com/api/v1/llms.txt