# ConnexMail API > Communication-to-work API for SaaS products, MCP-capable agents, and AI organizations. - **Base URL**: `https://connexmail.com` - **Auth**: Connex API key in `Authorization: Bearer cxk_live_...` for production server-to-server calls - **Status**: private beta, event/status API live - **Interactive page**: https://connexmail.com/docs - **OpenAPI JSON**: https://connexmail.com/api/connex/openapi This file is a static markdown mirror of the Connex developer docs. Crawl it, paste it into an LLM, link to it, or use it as the first integration briefing for an AI coding agent. --- ## What Role Connex Plays Connex is the communication-to-work layer between email, agents, and SaaS workflows. It is not just an inbox and it is not a bulk-email tool. Connex receives email/app/agent events and returns governed operations your product can safely apply: statuses, tasks, approvals, drafts, trust signals, graph hints, and outcome memory. ### What your app keeps - Your customer records. - Your workflow statuses. - Your sender identity and domain rules. - Your final apply/send decisions. - Your app-specific business logic. ### What Connex provides - Communication normalization. - Status and inbox routing suggestions. - Human approval gates. - Draft and task operations. - Trust and abuse signals. - Agent relationship and outcome memory. - A shared protocol for agent-native communication across products. ### What remains private These docs expose the public contract, not the secret sauce. Connex does not publish proprietary scoring logic, trust weighting, routing heuristics, model prompts, relationship-graph internals, or abuse-detection thresholds. --- ## Integration Modes ### Shadow intelligence Best for existing SaaS products. Your app keeps sending and receiving. Connex receives copies/events, classifies them, and returns workflow operations. ### Connex mailbox Best for agent-native inboxes. Connex owns the mailbox identity and can expose a human inbox plus governed agent actions when policy allows. ### Agent network Best for cross-app agents. Agents exchange structured events, approvals, trust, and outcomes without inventing uncontrolled private languages. --- ## Production Integration Requires A Connex API Key For production, yes: you need a Connex API key. - **Where to get it**: log in to Connex, open Settings, create an API key. - **Key format**: `cxk_live_...`. - **How to send it**: `Authorization: Bearer cxk_live_your_key_here`. - **Where to store it**: backend, MCP server, serverless function, or secure automation runtime only. - **Where not to store it**: browser JavaScript, public repos, screenshots, public agent config, or client-side bundles. Minimum production call: ```bash curl -sS https://connexmail.com/api/connex/integration-event \ -H 'content-type: application/json' \ -H 'authorization: Bearer cxk_live_your_key_here' \ -d '{ "app":"your-saas", "sourceSystem":"your-saas", "sourceEventId":"evt_123", "eventType":"inbound_reply", "message":{"subject":"Need approval","body":"Can you confirm terms?"} }' ``` For demos and first-contact testing, use `/api/connex/integration-preview` without an API key. Preview stores nothing and does not send email. --- ## What Connex Actually Does Connex turns messy communication into governed JSON operations. 1. **Email or app event happens** — a source app, mailbox webhook, MCP tool, or agent runtime sends Connex the message/event plus app context. 2. **Connex normalizes it** — Connex parses the human message into structured JSON: status, priority, tasks, drafts, approvals, routing, trust, and graph hints. 3. **Your app applies safely** — the source app decides what to apply. Connex can recommend or materialize safe internal work, but it does not auto-send risky email. 4. **Outcomes teach the network** — your app reports approved, rejected, advanced, won, lost, spam, or override outcomes so Connex learns what works. Example response shape: ```json { "canonical": { "status": "proof_of_funds_requested", "priority": "high", "approvalRequired": true, "nextBestAction": "Ask the buyer to upload proof of funds" }, "mapped": { "appName": "your-saas", "currentStatus": "LOI Sent", "status": "Needs POF", "inbox": "Human Approval" }, "operations": [ { "type": "create_task", "label": "Request proof of funds", "approvalRequired": true }, { "type": "route_inbox", "label": "Move to Human Approval" } ] } ``` --- ## Pick Your Transport First ### Use REST Today Use REST when your SaaS product, backend, workflow tool, or AI runtime can make server-side HTTP calls. This is the live production integration path today. - No-auth preview for dry runs. - API-key event ingestion for production. - Outcome reporting so Connex can learn what worked. - Trust and insight endpoints for tenant-scoped summaries. ### Use MCP When Released Connex is designing a public MCP server for agent clients. It is not released yet. Do not assume mailbox lifecycle, thread search, webhooks, WebSockets, or MCP tools are public until `/.well-known/connex-agent` marks them live. --- ## Current Availability | Surface | Status | Notes | |---|---|---| | No-auth preview | Live | No storage, no email send, no live model call | | Integration event | Live | Requires Connex API key | | Outcome reporting | Live | Requires Connex API key | | Insights and trust | Live | Requires Connex API key | | API key creation | Account-gated | Create from signed-in Connex settings | | Mailbox UI | Account-gated | Human ConnexMail inbox experience | | Internal dispatch / graph events | Account-gated | Connex account session required today | | MCP server / mailbox public API / webhooks / WebSockets | Planned | Target zero-friction agent protocol | --- ## Quick Start ### 1. Read Discovery GET https://connexmail.com/.well-known/connex-agent ### 2. Run A No-Auth Preview ```bash curl -sS https://connexmail.com/api/connex/integration-preview \ -H 'content-type: application/json' \ -d '{ "app":"your-saas", "sourceSystem":"your-saas", "eventType":"inbound_reply", "sourceMailbox":{"senderIdentityOwner":"source_app","replyPolicy":"source_app_only","externalReplyUrl":"https://your-saas.example/thread/123"}, "message":{"subject":"Need approval before moving forward","body":"Can you confirm terms before we proceed?"} }' ``` ### 3. Create A Connex API Key Log in to Connex, open Settings, and create an API key. Connex API keys currently use the `cxk_live_*` format. Copy it immediately; raw keys are shown once. ### 4. Validate The Key ```bash curl -sS https://connexmail.com/api/connex/key-check \ -H 'authorization: Bearer cxk_live_your_key_here' ``` ### 5. Ingest Production Events ```bash curl -sS https://connexmail.com/api/connex/integration-event \ -H 'content-type: application/json' \ -H 'authorization: Bearer cxk_live_your_key_here' \ -d '{ "app":"your-saas", "sourceSystem":"your-saas", "sourceEventId":"evt_123", "eventType":"inbound_reply", "applyMode":"recommend", "currentStatus":"Waiting", "externalIds":{"objectType":"opportunity","objectId":"opp_123","threadId":"thread_456"}, "sourceMailbox":{"senderIdentityOwner":"source_app","replyPolicy":"source_app_only","externalReplyUrl":"https://your-saas.example/opportunities/opp_123"}, "message":{"from":"customer@example.com","to":"agent@yourdomain.com","subject":"Need approval","body":"Can you confirm terms?"} }' ``` ### 6. Report Outcomes ```bash curl -sS https://connexmail.com/api/connex/integration-outcome \ -H 'content-type: application/json' \ -H 'authorization: Bearer cxk_live_your_key_here' \ -d '{ "sourceSystem":"your-saas", "sourceOutcomeId":"outcome_123", "outcomeType":"human_approved", "valueScore":50 }' ``` --- ## Core Endpoints | Endpoint | Auth | Purpose | |---|---|---| | `POST /api/connex/integration-preview` | none | Dry-run status, operations, trust, and reasoning metadata | | `POST /api/connex/key-check` | API key | Validate key and enabled endpoints | | `POST /api/connex/integration-event` | API key | Persist app/mailbox/agent event and return governed operations | | `POST /api/connex/integration-outcome` | API key | Record downstream result and learning signal | | `POST /api/connex/integration-insights` | API key | Read summary-only event/outcome intelligence | | `POST /api/connex/trust` | API key | Read trust band, policy gates, and abuse signals | | `GET /api/connex/reasoning` | none | Read safe reasoning-provider readiness | | `POST /api/connex/dispatch` | Connex user session | Account-gated internal task dispatch today | | `POST /api/connex/graph-event` | Connex user session | Account-gated graph event writes today | --- ## Mailbox Identity Rules - `senderIdentityOwner: "connex"`: Connex owns the visible mailbox. Replies are still gated by trust and policy. - `senderIdentityOwner: "source_app"`: another app owns the thread. Connex analyzes, routes, drafts, and audits; the source app replies. - `senderIdentityOwner: "customer_domain"`: the customer verified domain owns the visible sender. Connex must not reply from `@connexmail.com`. - `replyPolicy: "source_app_only"`: recommended for LOI/custom-domain flows where the customer or source app must remain the visible sender. ## Common Errors | Error | Cause | Fix | |---|---|---| | `Missing authorization` | No API key header | Add `Authorization: Bearer cxk_live_...` from a secure server | | `Invalid API key` | Key typo, revoked key, expired key | Generate a fresh key in Connex settings | | `Forbidden scope` | Key lacks `status:evaluate` | Create a key with the required scope | | `Payload too large` | Message/context exceeds endpoint limit | Send summary context or store bodies in your app | | `Account session required` | Calling an account-gated endpoint with only an API key | Use the live API-key endpoints or wait for public protocol release | ## Safety Guarantees - Preview stores nothing. - Model guidance cannot auto-send external email. - High-risk operations require approval. - API keys must never be exposed in browser bundles, screenshots, commits, logs, or public agents. - Connex distinguishes source-app-owned, customer-domain-owned, and Connex-owned mailbox identities.