Public developer docs

The communication-to-work layer for agentic software.

Connex is not just an inbox. It is the layer that turns email, app events, and agent messages into governed JSON operations: statuses, tasks, approvals, drafts, trust, graph hints, and outcomes. Production integrations use a Connex API key in Authorization: Bearer cxk_live_....

Role

Where Connex fits.

RoleCommunication-to-work layer

Connex sits between email, agents, and your SaaS workflow. It converts conversations into governed work your app can understand.

ValueNo more blind inboxes

Your product gets status, routing, tasks, approvals, drafts, trust signals, and outcome memory without building an agent-mail system from scratch.

ControlYour app stays in charge

You keep the customer record, workflow statuses, sender identity, and final apply/send decisions. Connex returns recommendations and safe operations.

BoundaryPublic contract, private intelligence

The API exposes inputs and outputs, not proprietary scoring logic, trust weighting, routing heuristics, or relationship-graph internals.

Integration modes

Use Connex without giving up your product.

Shadow intelligenceBest for existing SaaS

Your app keeps sending and receiving. Connex receives copies/events, classifies them, and returns workflow operations.

Connex mailboxBest for agent-native inboxes

Connex owns the mailbox identity and can expose a human inbox plus governed agent actions when policy allows.

Agent networkBest for cross-app agents

Agents exchange structured events, approvals, trust, and outcomes without inventing uncontrolled private languages.

Integration answer

Yes, production integrations need a Connex API key.

Where to get itLog in to Connex, then Settings, then API keys

Create a Connex API key from a signed-in Connex account. Keys use the cxk_live_* format and raw keys are shown once.

Where to put itAuthorization: Bearer cxk_live_...

Store the key only in your backend, MCP server, or secure automation runtime. Do not put it in browser JavaScript or public agent config.

What to callintegration-event and integration-outcome

Send email/app events to Connex, receive JSON operations, apply them in your app, then report the outcome back.

Minimum production call

Send one event with an API key.

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 before moving forward",
      "body": "Can you confirm terms before we proceed?"
    }
  }'

Zero friction

Preview without auth, read docs from one URL, then graduate to a Connex API key from your account.

Source identity

Connex distinguishes Connex-owned, source-app-owned, and customer-domain-owned mailboxes so replies happen from the right place.

Governed work

Messages become tasks, approvals, drafts, workflow moves, audit events, and graph memory instead of loose agent chatter.

Outcome learning

Apps report downstream results so Connex learns which workflows, relationships, and agents create value.

Mechanism

Email in. JSON operations out.

1Email or event happens

A source app, mailbox webhook, MCP tool, or agent runtime sends Connex the message/event plus app context.

2Connex normalizes it

Connex parses the human message into structured JSON: status, priority, tasks, drafts, approvals, routing, trust, and graph hints.

3Your 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.

4Outcomes teach the network

Your app reports approved, rejected, advanced, won, lost, spam, or override outcomes so Connex learns what works.

Output shape

Connex turns communication into governed work.

{
  "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" }
  ]
}

Availability

What can integrate today?

LivePreview, ingest, outcome, insights, trust, discovery, OpenAPI

Any AI software can integrate server-to-server once it has a Connex API key. The no-auth preview endpoint works immediately for dry runs.

Account-gatedAPI keys, Connex mailbox UI, internal dispatch, graph events

These require a signed-in Connex account/session and current private-beta access.

Planned public protocolMCP server, mailbox create/list API, webhooks, WebSockets

These are the target surfaces for zero-friction agent mailbox adoption, but they are not yet public self-serve endpoints.

Transport

REST is live. MCP is the target.

Use REST todaypreview to API key to event to outcome

Best for SaaS backends, webhooks, workflow tools, and AI runtimes that can hold a server-side secret.

Use MCP when releasedplanned Connex MCP server

The MCP package is the zero-friction agent path we are designing toward. It is not the live public mailbox protocol yet.

Fast path

Start with preview. Graduate into trust.

Read /.well-known/connex-agent.
Call /api/connex/integration-preview without auth.
Create a Connex API key from Settings. It uses the cxk_live_* format.
Send production events to /api/connex/integration-event.
Report results to /api/connex/integration-outcome.
Use trust and insights to graduate from preview/event ingestion into supervised mailbox actions.

Auth

API keys stay server-side.

Production authAuthorization: Bearer cxk_live_...

Create a Connex API key from Settings, validate with key-check, and never expose it in a browser, public agent config, screenshot, commit, or log.

Account-gatedSupabase Connex session

API-key creation, internal dispatch, graph writes, mailbox UI, and intelligence dashboards require a signed-in Connex account today.

Core endpoints

One mailbox. One operations ledger.

PreviewPOST /api/connex/integration-preview

No-auth dry run for app, MCP, mailbox, or agent events. Stores nothing and calls no live model.

IngestPOST /api/connex/integration-event

Server-to-server event intake that returns status, operations, graph hints, materialization, and reasoning metadata.

OutcomePOST /api/connex/integration-outcome

Report what happened after an app applied, rejected, approved, or overrode a Connex operation.

TrustPOST /api/connex/trust

Read policy gates, trust band, abuse signals, and recommendation for the calling tenant.

DiscoveryGET /.well-known/connex-agent

Agent-readable capability and endpoint discovery for software and MCP clients.

Example

No-auth preview request

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?"
    }
  }'

Errors

Common integration failures.

401Missing or invalid API key

Send the key only from your backend using the Authorization header.

403Forbidden scope

Create a key with status:evaluate for event, outcome, insights, and trust calls.

413 / 429Payload or quota limit

Send compact context and respect tenant quotas. Connex is an operations layer, not a bulk-send loophole.