# Inbrix Developer & AI Agent Integration Manual
Version: 1.1.0 (2026)
Base URL: https://app.inbrix.us
Protocol: HTTPS / JSON / Server-Sent Events (MCP)

---

## Overview
Inbrix provides autonomous, non-per-seat email infrastructure for custom domains, creators, applications, and AI agents.
This document gives AI coding agents (Claude, Cursor, OpenAI, Antigravity) all specifications, endpoint contracts, schema models, and SDK code needed to programmatically interact with Inbrix.

---

## 1. Authentication & Scopes
All API and MCP requests require an API Bearer token (`ix_live_...`) generated in Inbrix Settings > API & Integrations (https://app.inbrix.us/settings/connections).

Header:
  Authorization: Bearer <INBRIX_API_TOKEN>

### Token Scopes:
- `mail:send` : Send mail, draft replies, and forward messages.
- `mail:read` : Read mailboxes, search emails, view threads, and download attachments.
- `admin`     : Manage custom domains, DNS verification, addresses/aliases, and team accounts.
- `tasks:read` / `tasks:write` : Access and manage workspace tasks and action items.
- `followups:read` / `followups:write` : Access and resolve Follow-up Radar items.
- `ai:read` / `ai:generate` : Generate executive briefs, thread summaries, action item extractions, and reply drafts.

---

## 2. Inbrix Developer API v1
Inbrix provides a Developer API for sending mail from a verified custom-domain address.

### 2.1 Send Email (`POST /api/v1/emails`)
Requires Scope: `mail:send`
Content-Type: application/json

Sends a message from one of the workspace's verified addresses.

Request Body:
{
  "from": "Acme <ada@yourdomain.com>",
  "to": "newuser@example.com",
  "subject": "Welcome to Acme",
  "html": "<h1>Welcome aboard</h1><p>Thanks for signing up.</p>",
  "text": "Welcome aboard. Thanks for signing up."
}

Response (200 OK):
{
  "object": "email",
  "id": "email-uuid"
}

---

## 3. Core Workspace Mail API (`POST /api/mail`)
Endpoint: POST /api/mail
Requires Scope: `mail:send`
Content-Type: application/json

Request Body:
{
  "to": "recipient@example.com",
  "subject": "Invoice #1042 Available",
  "html": "<h1>Invoice Ready</h1><p>Thank you for your payment.</p>",
  "text": "Invoice Ready. Thank you for your payment.",
  "fromAddressId": "optional-address-uuid",
  "cc": "billing@example.com",
  "bcc": "audit@example.com",
  "replyTo": "support@yourdomain.com",
  "attachments": [
    {
      "filename": "receipt.pdf",
      "contentType": "application/pdf",
      "content": "base64EncodedContentHere"
    }
  ]
}

Response (200 OK):
{
  "ok": true,
  "id": "email-uuid",
  "threadId": "thread-uuid",
  "status": "delivered"
}

---

## 4. Querying & Reading Inboxes
Endpoint: GET /api/mail
Requires Scope: `mail:read`

Query Parameters:
- `limit` (integer, default 25, max 100)
- `cursor` (string, opaque pagination token)
- `category` (optional: "primary", "updates", "promotions", "social", "forums", "spam")
- `unread` (boolean: true/false)
- `domain` (optional domain UUID)
- `mailbox` (optional mailbox UUID)

Response (200 OK):
{
  "emails": [
    {
      "id": "email-uuid",
      "from_addr": "sender@external.com",
      "from_name": "Jane Doe",
      "to_addr": "support@yourdomain.com",
      "subject": "Question regarding my account",
      "body_text": "Hello, I wanted to inquire...",
      "status": "delivered",
      "is_read": 0,
      "is_starred": 0,
      "created_at": "2026-10-04T14:22:00.000Z"
    }
  ],
  "nextCursor": "string-or-null"
}

---

## 5. Single Message, Attachment Access & Incremental Sync
### 5.1 Single Message (`GET /api/mail/:id`)
Requires Scope: `mail:read`
Returns full RFC 5322 MIME parsed payload, HTML body, plain text, headers, and attachment manifest:
{
  "email": {
    "id": "email-uuid",
    "subject": "...",
    "body_html": "...",
    "body_text": "...",
    "attachments": [
      {
        "id": "att-uuid",
        "filename": "contract.pdf",
        "contentType": "application/pdf",
        "sizeBytes": 45200,
        "url": "/api/mail/email-uuid/attachments/att-uuid"
      }
    ]
  }
}

### 5.2 Incremental Mail Sync (`GET /api/mail/sync`)
Requires Scope: `mail:read`
Query Parameters:
- `cursor` (optional: pass previous cursor to fetch only new/modified messages since last check)

Response (200 OK):
{
  "messages": [...],
  "deleted": ["email-uuid-1", ...],
  "nextCursor": "0:1790620000000:42"
}

---

## 6. AI Agent Integration: Universal Model Context Protocol (MCP) & REST

Inbrix provides a universal agent protocol compatible with **any AI agent framework**:
- **MCP Clients:** Claude Desktop, Cursor, Windsurf, Zed, Continue.dev, Cline, Goose.
- **Python Frameworks:** LangChain, LangGraph, CrewAI, AutoGen, LlamaIndex, OpenAI SDK.
- **TypeScript Frameworks:** Vercel AI SDK (`ai`), LangChain.js, Node.js, Bun.
- **Direct REST:** Call any tool directly via simple HTTP POST with zero wrapper boilerplate.

### Universal Endpoints:
- MCP Server Endpoint: `https://app.inbrix.us/mcp`
- OpenAI Tools Schema: `https://app.inbrix.us/mcp?format=openai`
- Anthropic Tools Schema: `https://app.inbrix.us/mcp?format=anthropic`
- Google Gemini Tools: `https://app.inbrix.us/mcp?format=gemini`
- OpenAPI 3.1 Schema: `https://app.inbrix.us/mcp?format=openapi`

Headers:
  Authorization: Bearer <YOUR_INBRIX_API_KEY>
  Content-Type: application/json

---

### Integration Guide by Framework:

#### 1. MCP Clients (Claude Desktop, Cursor, Windsurf, Zed, Continue, Cline)
Add to your client configuration (`claude_desktop_config.json`, Cursor Settings > MCP, or `~/.codeium/windsurf/mcp_config.json`):
```json
{
  "mcpServers": {
    "inbrix": {
      "type": "http",
      "url": "https://app.inbrix.us/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_INBRIX_API_KEY"
      }
    }
  }
}
```

#### 2. Python: LangChain, CrewAI & OpenAI Agent Loops
```python
import requests

INBRIX_KEY = "YOUR_INBRIX_API_KEY"

# Dynamically fetch OpenAI function calling schemas:
tools = requests.get(
    "https://app.inbrix.us/mcp?format=openai",
    headers={"Authorization": f"Bearer {INBRIX_KEY}"}
).json()["tools"]

# Direct tool execution from your agent:
res = requests.post(
    "https://app.inbrix.us/mcp",
    headers={"Authorization": f"Bearer {INBRIX_KEY}"},
    json={
        "name": "send_message",
        "arguments": {
            "to": "ada@example.com",
            "subject": "October Product Update",
            "text": "The new release is live."
        }
    }
).json()
```

#### 3. TypeScript / Node.js: Vercel AI SDK
```typescript
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const INBRIX_KEY = "YOUR_INBRIX_API_KEY";

// Direct execution helper
async function callInbrix(name: string, args: Record<string, unknown>) {
  const res = await fetch("https://app.inbrix.us/mcp", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${INBRIX_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ name, arguments: args })
  });
  return res.json();
}
```

---

### The 26 Unified Agent Tools:

#### Identity & Mailbox Operations
1. `whoami`(): Returns user identity, active organization, plan limits, and available sending aliases.
2. `list_threads`({ view: "inbox", unread: true }): Lists conversations newest first. Filter by view (inbox, sent, archive, starred, drafts, spam, trash), category, unread, or search query.
3. `search_mail`({ q: "query" }): Full-text FTS5 search across subject lines, body content, and participants.
4. `get_thread`({ id: "thread_id" }): Retrieves full conversation thread including message bodies, participants, headers, and attachments.
5. `send_message`({ to: "email", subject: "...", text: "...", html: "..." }): Sends an outbound email from the workspace.
6. `reply`({ id: "msg_id", text: "..." }): Replies directly to a thread, preserving conversation headers and references.
7. `update_thread`({ id: "thread_id", isStarred: true }): Sets thread flags: star, unread, archive, trash, spam, or category.
8. `list_attachments`({ id: "thread_id" }): Lists attachment metadata and secure download URLs.
9. `list_labels`(): Lists custom workspace labels.
10. `set_thread_labels`({ id: "thread_id", labelIds: ["..."] }): Applies custom labels to a conversation.

#### Domain Onboarding & DNS Management
11. `get_setup_status`(): Returns current domains, verification state, mailboxes, and addresses.
12. `add_domain`({ domain: "myapp.com" }): Registers domain and generates required MX, SPF, DKIM, and DMARC DNS records (supports Cloudflare Email Routing and Amazon SES).
13. `get_dns_records`({ domain: "myapp.com" }): Returns active DNS records to add at registrar.
14. `verify_domain`({ domain: "myapp.com" }): Triggers live DNS propagation verification.
15. `create_mailbox`({ name: "Support" }): Creates a named shared mailbox.
16. `add_address`({ localPart: "support", domain: "myapp.com" }): Creates an email alias routed to a mailbox.
17. `list_addresses`(): Lists all configured sender aliases.

#### Tasks, Follow-up Radar & Sender Security
18. `list_tasks`({ status: "open", priority: "high" }): Lists workspace tasks with status and priority filtering.
19. `create_task`({ title: "...", description: "...", thread_id: "..." }): Creates an autonomous task, optionally linked to an email thread.
20. `update_task`({ id: "...", status: "done" }): Updates task status, priority, title, or notes.
21. `list_followups`(): Lists email conversations awaiting follow-up or outbound reply.
22. `add_sender_policy`({ pattern: "*@spam.com", policy: "block" }): Sets inbound sender security policy (allow, block, quarantine).

#### Calendar & Mailbox Import
23. `list_calendar_events`({ start?: "...", end?: "..." }): Lists workspace calendar events.
24. `create_calendar_event`({ title: "...", start_time: "...", end_time: "..." }): Creates a calendar event.
25. `start_imap_import`(): Starts an import from an external mailbox.
26. `get_imap_import_status`(): Returns the status of an in-progress mailbox import.

---

## 7. Real-Time Webhooks
Endpoint: POST /api/webhooks
Event Subscriptions: ["message.inbound"]

Webhook Registration Payload:
{
  "url": "https://your-api.com/webhooks/inbrix",
  "secret": "your-webhook-secret-key",
  "events": ["message.inbound"]
}

### Webhook Verification (HMAC-SHA256):
Inbrix sends a signature header on every webhook delivery:
  X-Inbrix-Signature: t=1790623000,v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Verification Algorithm:
1. Extract timestamp `t` and signature `v1` from `X-Inbrix-Signature`.
2. Construct signature payload: `${t}.${rawBody}`.
3. Compute HMAC-SHA256 hash using your webhook secret.
4. Compare computed hash with `v1` using constant-time comparison.

Webhook Payload Example:
{
  "event": "message.inbound",
  "timestamp": "2026-10-04T14:30:00Z",
  "data": {
    "messageId": "msg-uuid",
    "from": "customer@example.com",
    "to": "support@yourdomain.com",
    "subject": "Help with order",
    "bodyText": "Can you check my order status?",
    "bodyHtml": "<p>Can you check my order status?</p>",
    "hasAttachments": false
  }
}

---

## 8. Inbound Routing Rules & Auto-Reply
Programmatically manage inbox routing rules:
Endpoint: POST /api/routing-rules
Request:
{
  "name": "Auto-archive newsletters",
  "match_field": "subject",       // "from" | "to" | "subject" | "body"
  "match_operator": "contains",   // "contains" | "exact" | "starts_with" | "ends_with" | "regex"
  "match_value": "unsubscribe",
  "action": "move_folder",        // "mark_read" | "star" | "move_folder" | "move_trash" | "apply_label" | "forward"
  "action_value": "archive"
}