Xobni.ai

https://www.xobni.ai/docs/
Admin
Xobni.ai provides digital email identities for AI agents, enabling them to send and receive emails...
Tokens:13,856
Snippets:62
Trust Score:2.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Python MCP Client

Source: https://www.xobni.ai/docs/mcp/examples

Installs the official `mcp` Python SDK using pip. This is the first step to using the Python client.

```bash
pip install mcp
```

--------------------------------

### Python MCP Client Example

Source: https://www.xobni.ai/docs/mcp/examples

Demonstrates connecting to the MCP server using the Python SDK. It shows how to list tools, get agent information, read the inbox, send an email, and search emails semantically. Requires an API key and MCP URL.

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

API_KEY = "xobni_<your-key>"
MCP_URL = "https://api.xobni.ai/mcp/"

async def main():
    headers = {"Authorization": f"Bearer {API_KEY}"}

    async with streamablehttp_client(MCP_URL, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print("Available tools:")
            for t in tools.tools:
                print(f"  - {t.name}: {t.description[:60]}...")

            # Get agent info
            result = await session.call_tool("get_agent_info", {{}})
            print(f"\nAgent: {result}")

            # Read inbox (latest 5 emails)
            result = await session.call_tool("read_inbox", {{"limit": 5}})
            print(f"\nInbox: {result}")

            # Send an email
            result = await session.call_tool("send_email", {{
                "to": ["friend@example.com"],
                "subject": "Hello from my AI agent!",
                "body_text": "This email was sent via MCP through Xobni.ai."
            }})
            print(f"\nSent: {result}")

            # Search emails semantically
            result = await session.call_tool("search_emails", {{
                "query": "meeting next week",
                "limit": 5
            }})
            print(f"\nSearch results: {result}")

asyncio.run(main())

```

--------------------------------

### Install TypeScript/Node.js MCP SDK

Source: https://www.xobni.ai/docs/mcp/examples

Installs the official `@modelcontextprotocol/sdk` package using npm. This is required for using the TypeScript/Node.js client.

```bash
npm install @modelcontextprotocol/sdk
```

--------------------------------

### MCP Server Connection and Tool Usage (Python)

Source: https://www.xobni.ai/docs/mcp/examples

This example demonstrates how to use the official `mcp` Python SDK to connect to the MCP server, list available tools, and call specific tools like `get_agent_info`, `read_inbox`, `send_email`, and `search_emails`.

```APIDOC
## MCP Code Examples (Python)

### Description
This section provides a full example using the official `mcp` Python SDK to connect to the MCP server and utilize its tools.

### Installation
```bash
pip install mcp
```

### Usage
```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

API_KEY = "xobni_<your-key>"
MCP_URL = "https://api.xobni.ai/mcp/"

async def main():
    headers = {"Authorization": f"Bearer {API_KEY}"}

    async with streamablehttp_client(MCP_URL, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print("Available tools:")
            for t in tools.tools:
                print(f"  - {t.name}: {t.description[:60]}...")

            # Get agent info
            result = await session.call_tool("get_agent_info", {{}})
            print(f"\nAgent: {result}")

            # Read inbox (latest 5 emails)
            result = await session.call_tool("read_inbox", {{"limit": 5}})
            print(f"\nInbox: {result}")

            # Send an email
            result = await session.call_tool("send_email", {{
                "to": ["friend@example.com"],
                "subject": "Hello from my AI agent!",
                "body_text": "This email was sent via MCP through Xobni.ai."
            }})
            print(f"\nSent: {result}")

            # Search emails semantically
            result = await session.call_tool("search_emails", {{
                "query": "meeting next week",
                "limit": 5
            }})
            print(f"\nSearch results: {result}")

asyncio.run(main())
```
```

--------------------------------

### MCP Server Connection and Tool Usage (TypeScript/Node.js)

Source: https://www.xobni.ai/docs/mcp/examples

This example demonstrates how to use the `@modelcontextprotocol/sdk` package in TypeScript/Node.js to connect to the MCP server, list tools, and call tools like `read_inbox` and `search_emails`.

```APIDOC
## MCP Code Examples (TypeScript / Node.js)

### Description
This section provides a full example using the `@modelcontextprotocol/sdk` package in TypeScript/Node.js to connect to the MCP server and utilize its tools.

### Installation
```bash
npm install @modelcontextprotocol/sdk
```

### Usage
```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const API_KEY = "xobni_<your-key>";

async function main() {
  const transport = new StreamableHTTPClientTransport(
    new URL("https://api.xobni.ai/mcp/"),
    { requestInit: { headers: { Authorization: `Bearer ${API_KEY}` } } }
  );

  const client = new Client({ name: "my-app", version: "1.0.0" });
  await client.connect(transport);

  // List tools
  const { tools } = await client.listTools();
  console.log("Tools:", tools.map(t => t.name));

  // Read inbox
  const inbox = await client.callTool({
    name: "read_inbox",
    arguments: { limit: 5 }
  });
  console.log("Inbox:", inbox);

  // Search
  const search = await client.callTool({
    name: "search_emails",
    arguments: { query: "project update", limit: 3 }
  });
  console.log("Search:", search);

  await client.close();
}

main();
```
```

--------------------------------

### TypeScript/Node.js MCP Client Example

Source: https://www.xobni.ai/docs/mcp/examples

Demonstrates connecting to the MCP server using the TypeScript/Node.js SDK. It shows how to list tools, read the inbox, and search emails. Requires an API key and MCP URL. The client is initialized with an app name and version.

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const API_KEY = "xobni_<your-key>";

async function main() {
  const transport = new StreamableHTTPClientTransport(
    new URL("https://api.xobni.ai/mcp/"),
    { requestInit: { headers: { Authorization: `Bearer ${API_KEY}` } } }
  );

  const client = new Client({ name: "my-app", version: "1.0.0" });
  await client.connect(transport);

  // List tools
  const { tools } = await client.listTools();
  console.log("Tools:", tools.map(t => t.name));

  // Read inbox
  const inbox = await client.callTool({
    name: "read_inbox",
    arguments: { limit: 5 }
  });
  console.log("Inbox:", inbox);

  // Search
  const search = await client.callTool({
    name: "search_emails",
    arguments: { query: "project update", limit: 3 }
  });
  console.log("Search:", search);

  await client.close();
}

main();

```

--------------------------------

### Test a Webhook via Xobni.ai REST API (curl)

Source: https://www.xobni.ai/docs/rest-api/examples

This example demonstrates how to test a previously created webhook. It requires the webhook's UUID. The request is made via a POST request to the /api/v1/event-hooks/<webhook-uuid>/test endpoint.

```curl
curl -X POST https://api.xobni.ai/api/v1/event-hooks/<webhook-uuid>/test \
  -H "Authorization: Bearer xobni_<your-key>"
```

--------------------------------

### Create a Webhook via Xobni.ai REST API (curl)

Source: https://www.xobni.ai/docs/rest-api/examples

This example shows how to create a webhook for receiving event notifications from Xobni.ai. It requires an agent ID, a URL for the webhook, a list of events to subscribe to, and an optional description. The request is made via a POST request to the /api/v1/event-hooks endpoint with a JSON payload.

```curl
curl -X POST https://api.xobni.ai/api/v1/event-hooks \
  -H "Authorization: Bearer xobni_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent-uuid>",
    "url": "https://your-service.com/webhook",
    "events": ["email.received", "email.sent"],
    "description": "My automation webhook"
  }'
```

--------------------------------

### List Inbox Emails via Xobni.ai REST API (curl)

Source: https://www.xobni.ai/docs/rest-api/examples

This example demonstrates how to list emails from an inbox using the Xobni.ai REST API. It requires an account ID. The request is made via a GET request to the /api/v1/emails endpoint, with the account ID as a query parameter.

```curl
curl "https://api.xobni.ai/api/v1/emails?account_id=<account-uuid>" \
  -H "Authorization: Bearer xobni_<your-key>"
```

--------------------------------

### Create Webhook via cURL

Source: https://www.xobni.ai/docs/webhooks

This example demonstrates how to create a new webhook using cURL. It specifies the agent ID, target URL, events to subscribe to, and a description. The response will contain a secret key for signature verification.

```bash
curl -X POST https://api.xobni.ai/api/v1/event-hooks \
  -H "Authorization: Bearer xobni_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent-uuid>",
    "url": "https://your-n8n.example.com/webhook/abc123",
    "events": ["email.received"],
    "description": "n8n email processor"
  }'
```

--------------------------------

### Test Webhook API

Source: https://www.xobni.ai/docs/rest-api/examples

Tests a previously created webhook by sending a test event.

```APIDOC
## POST /api/v1/event-hooks/{webhook-uuid}/test

### Description
Tests a previously created webhook by sending a test event.

### Method
POST

### Endpoint
https://api.xobni.ai/api/v1/event-hooks/<webhook-uuid>/test

### Parameters
#### Path Parameters
- **webhook-uuid** (string) - Required - The UUID of the webhook to test.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
"https://api.xobni.ai/api/v1/event-hooks/<webhook-uuid>/test"
```

### Response
#### Success Response (200)
Details of the success response are not provided in the source text.

#### Response Example
None provided in the source text.
```

--------------------------------

### Perform Semantic Search via Xobni.ai REST API (curl)

Source: https://www.xobni.ai/docs/rest-api/examples

This example shows how to perform a semantic search using the Xobni.ai REST API. It requires a search query, account ID, and an optional limit for results. The request is made via a POST request to the /api/v1/search endpoint with a JSON payload.

```curl
curl -X POST https://api.xobni.ai/api/v1/search \
  -H "Authorization: Bearer xobni_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "meeting about project deadline",
    "account_id": "<account-uuid>",
    "limit": 10
  }'
```

--------------------------------

### Create Webhook API

Source: https://www.xobni.ai/docs/rest-api/examples

Creates a webhook to receive event notifications. Requires agent ID, URL, and a list of events.

```APIDOC
## POST /api/v1/event-hooks

### Description
Creates a webhook to receive event notifications. Requires agent ID, URL, and a list of events.

### Method
POST

### Endpoint
https://api.xobni.ai/api/v1/event-hooks

### Parameters
#### Query Parameters
None

#### Request Body
- **agent_id** (string) - Required - The UUID of the agent associated with the webhook.
- **url** (string) - Required - The URL where the webhook events will be sent.
- **events** (array of strings) - Required - A list of event types to subscribe to (e.g., "email.received", "email.sent").
- **description** (string) - Optional - A description for the webhook.

### Request Example
```json
{
  "agent_id": "<agent-uuid>",
  "url": "https://your-service.com/webhook",
  "events": ["email.received", "email.sent"],
  "description": "My automation webhook"
}
```

### Response
#### Success Response (200)
Details of the success response are not provided in the source text.

#### Response Example
None provided in the source text.
```

--------------------------------

### Create API Key using REST API (curl)

Source: https://www.xobni.ai/docs/authentication

This example demonstrates how to create a new API key using a curl command. You can specify a name for the key and optionally scope it to a specific agent by providing the agent_id.

```bash
curl -X POST https://api.xobni.ai/api/v1/api-keys \
  -H "Authorization: Bearer xobni_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-integration", "agent_id": "<agent-uuid>"}'
```

--------------------------------

### List Inbox API

Source: https://www.xobni.ai/docs/rest-api/examples

Retrieves a list of emails from the inbox for a given account.

```APIDOC
## GET /api/v1/emails

### Description
Retrieves a list of emails from the inbox for a given account.

### Method
GET

### Endpoint
https://api.xobni.ai/api/v1/emails

### Parameters
#### Query Parameters
- **account_id** (string) - Required - The UUID of the account whose inbox to list.

#### Request Body
None

### Request Example
```json
"https://api.xobni.ai/api/v1/emails?account_id=<account-uuid>"
```

### Response
#### Success Response (200)
Details of the success response are not provided in the source text.

#### Response Example
None provided in the source text.
```

--------------------------------

### Semantic Search API

Source: https://www.xobni.ai/docs/rest-api/examples

Performs a semantic search based on a query. Requires account ID and a limit for results.

```APIDOC
## POST /api/v1/search

### Description
Performs a semantic search based on a query. Requires account ID and a limit for results.

### Method
POST

### Endpoint
https://api.xobni.ai/api/v1/search

### Parameters
#### Query Parameters
None

#### Request Body
- **query** (string) - Required - The search query.
- **account_id** (string) - Required - The UUID of the account to search within.
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "query": "meeting about project deadline",
  "account_id": "<account-uuid>",
  "limit": 10
}
```

### Response
#### Success Response (200)
Details of the success response are not provided in the source text.

#### Response Example
None provided in the source text.
```

--------------------------------

### Send Email via Xobni.ai REST API (curl)

Source: https://www.xobni.ai/docs/rest-api/examples

This example demonstrates how to send an email using the Xobni.ai REST API. It requires an agent ID, recipient email address, subject, and body content. The request is made via a POST request to the /api/v1/emails/send endpoint with JSON payload.

```curl
curl -X POST https://api.xobni.ai/api/v1/emails/send \
  -H "Authorization: Bearer xobni_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent-uuid>",
    "to": ["recipient@example.com"],
    "subject": "Hello from my AI agent",
    "body_text": "This email was sent by my AI agent via Xobni.ai!"
  }'
```

--------------------------------

### Send Email API

Source: https://www.xobni.ai/docs/rest-api/examples

Sends an email using the Xobni.ai API. Requires agent ID, recipients, subject, and body.

```APIDOC
## POST /api/v1/emails/send

### Description
Sends an email using the Xobni.ai API. Requires agent ID, recipients, subject, and body.

### Method
POST

### Endpoint
https://api.xobni.ai/api/v1/emails/send

### Parameters
#### Query Parameters
None

#### Request Body
- **agent_id** (string) - Required - The UUID of the agent sending the email.
- **to** (array of strings) - Required - A list of recipient email addresses.
- **subject** (string) - Required - The subject line of the email.
- **body_text** (string) - Required - The plain text content of the email.

### Request Example
```json
{
  "agent_id": "<agent-uuid>",
  "to": ["recipient@example.com"],
  "subject": "Hello from my AI agent",
  "body_text": "This email was sent by my AI agent via Xobni.ai!"
}
```

### Response
#### Success Response (200)
Details of the success response are not provided in the source text.

#### Response Example
None provided in the source text.
```

--------------------------------

### Create Webhook

Source: https://www.xobni.ai/docs/webhooks

This endpoint allows you to create a new webhook to receive event notifications from Xobni.ai. You need to provide the agent ID, a target URL, the events to subscribe to, and an optional description.

```APIDOC
## POST /api/v1/event-hooks

### Description
Creates a new webhook to receive event notifications when specific events occur within an agent's inbox.

### Method
POST

### Endpoint
https://api.xobni.ai/api/v1/event-hooks

### Parameters
#### Request Body
- **agent_id** (string) - Required - The unique identifier for the agent.
- **url** (string) - Required - The URL where the webhook notifications will be sent.
- **events** (array of strings) - Required - A list of event types to subscribe to (e.g., `"email.received"`, `"email.sent"`).
- **description** (string) - Optional - A human-readable description for the webhook.

### Request Example
```json
{
  "agent_id": "<agent-uuid>",
  "url": "https://your-n8n.example.com/webhook/abc123",
  "events": ["email.received"],
  "description": "n8n email processor"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created webhook.
- **agent_id** (string) - The agent ID associated with the webhook.
- **url** (string) - The configured webhook URL.
- **events** (array of strings) - The list of subscribed event types.
- **description** (string) - The description of the webhook.
- **secret** (string) - The signing secret for verifying webhook signatures. This is shown only once and must be saved securely.

#### Response Example
```json
{
  "id": "whk_12345abc",
  "agent_id": "agent-uuid-12345",
  "url": "https://your-n8n.example.com/webhook/abc123",
  "events": ["email.received"],
  "description": "n8n email processor",
  "secret": "your-secure-signing-secret"
}
```
```

--------------------------------

### Create API Key

Source: https://www.xobni.ai/docs/authentication

This endpoint allows you to create new API keys. You can optionally scope the key to a specific agent.

```APIDOC
## POST /api/v1/api-keys

### Description
Creates a new API key. Keys can be named and optionally scoped to a specific agent using `agent_id`.

### Method
POST

### Endpoint
/api/v1/api-keys

### Parameters
#### Request Headers
- **Authorization** (string) - Required - `Bearer xobni_<your-api-key>`
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **name** (string) - Required - A name for the API key (e.g., `"my-integration"`).
- **agent_id** (string) - Optional - The UUID of the agent to scope the key to. If omitted, the key has full account access.

### Request Example
```json
{
  "name": "my-integration",
  "agent_id": "<agent-uuid>"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created API key.
- **key** (string) - The generated API key. This is only shown at creation time.
- **name** (string) - The name of the API key.
- **agent_id** (string) - The agent ID the key is scoped to, if applicable.

#### Response Example
```json
{
  "id": "key-uuid-1234",
  "key": "xobni_live_key_abcdef123456",
  "name": "my-integration",
  "agent_id": "agent-uuid-5678"
}
```
```

--------------------------------

### MCP Server Connection

Source: https://www.xobni.ai/docs/mcp

Details on how to connect AI clients like Claude Desktop and Claude Code to your agent's email using the Model Context Protocol (MCP).

```APIDOC
## MCP Server Connection

### Description
Connect AI clients like Claude Desktop, Claude Code, or any MCP-compatible client to your agent's email via the Model Context Protocol.

### Connection Details
- **URL**: `https://api.xobni.ai/mcp/`
- **Transport**: Streamable HTTP
- **Auth**: `Authorization: Bearer xobni_<your-key>`

### Important
Create an API key **scoped to a specific agent** for the best MCP experience. The MCP tools will automatically operate in the context of that agent's inbox — no need to pass account IDs.

### Claude Desktop Configuration
Add the following to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "xobni-email": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.xobni.ai/mcp/",
        "--header",
        "Authorization: Bearer xobni_<your-api-key>"
      ]
    }
  }
}
```

### Claude Code Configuration
Add as an MCP server in Claude Code settings or `.mcp.json`:

```json
{
  "mcpServers": {
    "xobni-email": {
      "type": "url",
      "url": "https://api.xobni.ai/mcp/",
      "headers": {
        "Authorization": "Bearer xobni_<your-api-key>"
      }
    }
  }
}
```
```

--------------------------------

### Configure Claude Desktop for MCP Server

Source: https://www.xobni.ai/docs/mcp

This JSON configuration allows Claude Desktop to connect to the Xobni AI MCP server. It specifies the command to run and arguments, including the MCP server URL and authentication header.

```json
{
  "mcpServers": {
    "xobni-email": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.xobni.ai/mcp/",
        "--header",
        "Authorization: Bearer xobni_<your-api-key>"
      ]
    }
  }
}
```

--------------------------------

### Webhook Tools

Source: https://www.xobni.ai/docs/mcp/tools

Tools for managing event hooks for integration with automation platforms.

```APIDOC
## Webhook Tools

### Description
Tools for managing event hooks for integration with automation platforms.

### Tools

#### `list_webhooks`

##### Description
List all webhooks configured for the current agent, including URL, events, active status, and creation date.

##### Method
GET

##### Endpoint
/webhooks

#### `create_webhook`

##### Description
Create a new webhook to receive HTTP notifications when emails arrive or are sent. Returns a signing secret (shown once) for HMAC-SHA256 verification.

##### Method
POST

##### Endpoint
/webhooks

##### Request Body
- **url** (string) - Required - Target URL to receive POST requests.
- **events** (list[string]) - Required - Events to subscribe to: email.received, email.sent.
- **description** (string | null) - Optional - Optional label for the webhook.

#### `delete_webhook`

##### Description
Delete a webhook by ID. Removes the webhook and all its delivery history.

##### Method
DELETE

##### Endpoint
/webhooks/{webhook_id}

##### Path Parameters
- **webhook_id** (string) - Required - UUID of the webhook to delete.

#### `list_webhook_deliveries`

##### Description
List recent delivery attempts for a webhook, showing event type, HTTP status, success/failure status, and timestamps.

##### Method
GET

##### Endpoint
/webhooks/{webhook_id}/deliveries

##### Path Parameters
- **webhook_id** (string) - Required - UUID of the webhook.

##### Query Parameters
- **limit** (int) - Optional - Maximum results (1-100, default 20).

```

--------------------------------

### Email Tools

Source: https://www.xobni.ai/docs/mcp/tools

Tools for reading, sending, searching, and managing emails and attachments.

```APIDOC
## Email Tools

### Description
Tools for reading, sending, searching, and managing emails and attachments.

### Tools

#### `get_agent_info`

##### Description
Get the current agent's name, email address, slug, description, and status.

##### Method
GET

##### Endpoint
/agent/info

#### `read_inbox`

##### Description
List emails in the agent's inbox with optional filters and pagination.

##### Method
GET

##### Endpoint
/emails

##### Query Parameters
- **status** (string | null) - Optional - Filter by email status (received, read, sent, draft, archived).
- **limit** (int) - Optional - Maximum number of results (1-100, default 20).
- **offset** (int) - Optional - Skip N emails (default 0).

#### `read_email`

##### Description
Get the full content of a specific email including headers, body (text and HTML), and attachment list.

##### Method
GET

##### Endpoint
/emails/{email_id}

##### Path Parameters
- **email_id** (string) - Required - UUID of the email to read.

#### `send_email`

##### Description
Send an email from the agent's email address with support for threading (replies).

##### Method
POST

##### Endpoint
/emails/send

##### Request Body
- **to** (list[string]) - Required - Recipient email addresses.
- **body_text** (string) - Required - Plain text body.
- **subject** (string | null) - Optional - Email subject line.
- **cc** (list[string] | null) - Optional - CC recipients.
- **bcc** (list[string] | null) - Optional - BCC recipients.
- **body_html** (string | null) - Optional - HTML body.
- **in_reply_to_email_id** (string | null) - Optional - UUID of email being replied to (for threading).

#### `get_thread`

##### Description
Get all emails in a conversation thread, sorted chronologically.

##### Method
GET

##### Endpoint
/threads/{thread_id}

##### Path Parameters
- **thread_id** (string) - Required - UUID of the thread.

#### `list_attachments`

##### Description
List all attachments for a specific email with filenames, types, and sizes.

##### Method
GET

##### Endpoint
/emails/{email_id}/attachments

##### Path Parameters
- **email_id** (string) - Required - UUID of the email.

#### `download_attachment`

##### Description
Get a pre-signed URL to download an attachment. URL is valid for 15 minutes.

##### Method
GET

##### Endpoint
/attachments/{attachment_id}/download

##### Path Parameters
- **attachment_id** (string) - Required - UUID of the attachment.

#### `mark_email`

##### Description
Update an email's status or starred flag.

##### Method
POST

##### Endpoint
/emails/{email_id}/mark

##### Path Parameters
- **email_id** (string) - Required - UUID of the email.

##### Request Body
- **action** (string) - Required - One of: read, unread, starred, unstarred, archived.

#### `search_emails`

##### Description
Semantic search across emails and document attachments using natural language. Results include source_type (email_body or attachment) and attachment_id when matching attachment content.

##### Method
GET

##### Endpoint
/search/emails

##### Query Parameters
- **query** (string) - Required - Natural language search query.
- **limit** (int) - Optional - Maximum results (1-50, default 10).

#### `get_attachment_text`

##### Description
Get the extracted text content of a document attachment. Returns full text from various document types processed by the RAG pipeline.

##### Method
GET

##### Endpoint
/attachments/{attachment_id}/text

##### Path Parameters
- **attachment_id** (string) - Required - UUID of the attachment.

```

--------------------------------

### Configure Claude Code for MCP Server

Source: https://www.xobni.ai/docs/mcp

This JSON configuration sets up an MCP server connection within Claude Code. It defines the server type as 'url' and provides the MCP server URL along with the necessary Authorization header.

```json
{
  "mcpServers": {
    "xobni-email": {
      "type": "url",
      "url": "https://api.xobni.ai/mcp/",
      "headers": {
        "Authorization": "Bearer xobni_<your-api-key>"
      }
    }
  }
}
```

--------------------------------

### Agents API

Source: https://www.xobni.ai/docs/rest-api

Endpoints for managing agents, including listing, creating, retrieving, updating, and deleting them.

```APIDOC
## GET /agents

### Description
List your agents.

### Method
GET

### Endpoint
`/agents`

### Response
#### Success Response (200)
- **agents** (array) - A list of agent objects.

#### Response Example
```json
{
  "agents": [
    {
      "id": "agent_xyz",
      "name": "Support Bot",
      "model": "gpt-4"
    }
  ]
}
```

## POST /agents

### Description
Create a new agent.

### Method
POST

### Endpoint
`/agents`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the agent.
- **model** (string) - Optional - The model to use for the agent (e.g., 'gpt-4').

### Request Example
```json
{
  "name": "Sales Assistant",
  "model": "gpt-3.5-turbo"
}
```

### Response
#### Success Response (200)
- **agent** (object) - The newly created agent object.

#### Response Example
```json
{
  "agent": {
    "id": "agent_789",
    "name": "Sales Assistant",
    "model": "gpt-3.5-turbo"
  }
}
```

## GET /agents/{id}

### Description
Get details of a specific agent.

### Method
GET

### Endpoint
`/agents/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the agent to retrieve.

### Response
#### Success Response (200)
- **agent** (object) - The agent object.

#### Response Example
```json
{
  "agent": {
    "id": "agent_xyz",
    "name": "Support Bot",
    "model": "gpt-4"
  }
}
```

## PATCH /agents/{id}

### Description
Update an existing agent.

### Method
PATCH

### Endpoint
`/agents/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the agent to update.
#### Request Body
- **name** (string) - Optional - The new name for the agent.
- **model** (string) - Optional - The new model for the agent.

### Request Example
```json
{
  "name": "Updated Support Bot"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Agent updated successfully."
}
```

## DELETE /agents/{id}

### Description
Delete an agent (soft delete).

### Method
DELETE

### Endpoint
`/agents/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the agent to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Agent deleted successfully."
}
```
```

--------------------------------

### Search API

Source: https://www.xobni.ai/docs/rest-api

Endpoint for performing semantic search across emails and attachments.

```APIDOC
## POST /search

### Description
Perform semantic search across emails and attachments.

### Method
POST

### Endpoint
`/search`

### Parameters
#### Request Body
- **query** (string) - Required - The search query.
- **account_id** (string) - Required - The ID of the account to search within.

### Request Example
```json
{
  "query": "latest sales report",
  "account_id": "acc_abc"
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results.

#### Response Example
```json
{
  "results": [
    {
      "id": "email_123",
      "type": "email",
      "score": 0.95,
      "snippet": "...latest sales report details..."
    }
  ]
}
```
```

--------------------------------

### Webhook Signature Verification

Source: https://www.xobni.ai/docs/webhooks/security

This section details how to verify the HMAC-SHA256 signature included with every Xobni AI webhook delivery to ensure the request is authentic and has not been tampered with.

```APIDOC
## Signature Verification

Every webhook delivery includes an HMAC-SHA256 signature. Verify it to ensure the request is authentic.

### Signature Headers

These headers are included with every webhook delivery:

- `X-Xobni-Signature`: `sha256=<hex_digest>`
- `X-Xobni-Event`: Event name (e.g. `email.received`)
- `X-Xobni-Delivery`: Unique delivery UUID
- `X-Xobni-Timestamp`: Unix timestamp of delivery

### How Signing Works

The signature is computed as:

```
HMAC-SHA256(secret, "{timestamp}.{json_body}")
```

Where `secret` is the signing secret returned when you created the webhook, `timestamp` is the value of the `X-Xobni-Timestamp` header, and `json_body` is the raw request body.

### Python Verification

```python
import hmac
import hashlib

def verify_webhook(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    """Verify a Xobni webhook signature."""
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
# secret = "your-webhook-secret"  (from webhook creation)
# timestamp = request.headers["X-Xobni-Timestamp"]
# body = await request.body()
# signature = request.headers["X-Xobni-Signature"]
# if not verify_webhook(secret, timestamp, body, signature):
#     return Response(status_code=401)
```

### Node.js Verification

```javascript
const crypto = require("crypto");

function verifyWebhook(secret, timestamp, body, signature) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + body)
    .digest("hex");
  return signature === "sha256=" + expected;
}

// In your Express handler:
// const secret = "your-webhook-secret";
// const timestamp = req.headers["x-xobni-timestamp"];
// const body = req.rawBody;  // use express.raw() middleware
// const signature = req.headers["x-xobni-signature"];
// if (!verifyWebhook(secret, timestamp, body, signature)) {
//   return res.status(401).send("Invalid signature");
// }
```
```

--------------------------------

### Event Hooks (Webhooks) API

Source: https://www.xobni.ai/docs/rest-api

Endpoints for managing event hooks (webhooks), including listing, creating, retrieving, updating, deleting, and testing them, as well as viewing delivery logs.

```APIDOC
## GET /event-hooks

### Description
List webhooks for a specific agent.

### Method
GET

### Endpoint
`/event-hooks?agent_id={id}`

### Parameters
#### Query Parameters
- **agent_id** (string) - Required - The ID of the agent to list webhooks for.

### Response
#### Success Response (200)
- **event_hooks** (array) - A list of webhook objects.

#### Response Example
```json
{
  "event_hooks": [
    {
      "id": "hook_111",
      "url": "https://example.com/webhook",
      "events": ["email.created", "email.updated"],
      "status": "active",
      "agent_id": "agent_xyz"
    }
  ]
}
```

## POST /event-hooks

### Description
Create a new webhook. The secret is returned only once upon creation.

### Method
POST

### Endpoint
`/event-hooks`

### Parameters
#### Request Body
- **url** (string) - Required - The URL to send webhook events to.
- **events** (array of strings) - Required - A list of events to subscribe to (e.g., `["email.created", "email.updated"]`).
- **agent_id** (string) - Required - The ID of the agent this webhook is associated with.

### Request Example
```json
{
  "url": "https://my-service.com/webhook-handler",
  "events": ["email.sent", "thread.created"],
  "agent_id": "agent_xyz"
}
```

### Response
#### Success Response (200)
- **webhook** (object) - The newly created webhook object, including its secret.

#### Response Example
```json
{
  "webhook": {
    "id": "hook_222",
    "url": "https://my-service.com/webhook-handler",
    "events": ["email.sent", "thread.created"],
    "status": "active",
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxx",
    "agent_id": "agent_xyz"
  }
}
```

## GET /event-hooks/{id}

### Description
Get details of a specific webhook.

### Method
GET

### Endpoint
`/event-hooks/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the webhook to retrieve.

### Response
#### Success Response (200)
- **webhook** (object) - The webhook object.

#### Response Example
```json
{
  "webhook": {
    "id": "hook_111",
    "url": "https://example.com/webhook",
    "events": ["email.created", "email.updated"],
    "status": "active",
    "agent_id": "agent_xyz"
  }
}
```

## PATCH /event-hooks/{id}

### Description
Update webhook URL, events, or status.

### Method
PATCH

### Endpoint
`/event-hooks/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the webhook to update.
#### Request Body
- **url** (string) - Optional - The new URL for the webhook.
- **events** (array of strings) - Optional - The new list of events to subscribe to.
- **status** (string) - Optional - The new status ('active' or 'inactive').

### Request Example
```json
{
  "status": "inactive"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Webhook updated successfully."
}
```

## DELETE /event-hooks/{id}

### Description
Delete a webhook.

### Method
DELETE

### Endpoint
`/event-hooks/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the webhook to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Webhook deleted successfully."
}
```

## GET /event-hooks/{id}/deliveries

### Description
List delivery logs for a specific webhook.

### Method
GET

### Endpoint
`/event-hooks/{id}/deliveries`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the webhook to list deliveries for.

### Response
#### Success Response (200)
- **deliveries** (array) - A list of delivery log objects.

#### Response Example
```json
{
  "deliveries": [
    {
      "id": "delivery_333",
      "event_id": "event_abc",
      "status_code": 200,
      "response_body": "OK",
      "timestamp": "2023-10-27T12:00:00Z"
    }
  ]
}
```

## POST /event-hooks/{id}/test

### Description
Send a test event to the webhook.

### Method
POST

### Endpoint
`/event-hooks/{id}/test`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the webhook to test.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the test event was sent.

#### Response Example
```json
{
  "message": "Test event sent successfully."
}
```
```

--------------------------------

### API Authentication Header

Source: https://www.xobni.ai/docs/authentication

All API requests must include an 'Authorization' header with a Bearer token. The token is your API key prefixed with 'xobni_'.

```http
Authorization: Bearer xobni_<your-api-key>
```

--------------------------------

### Authentication - Bearer Token

Source: https://www.xobni.ai/docs/authentication

All API requests to Xobni.ai require authentication using an API key. This key must be sent in the `Authorization` header as a Bearer token.

```APIDOC
## Authentication - Bearer Token

### Description
API requests must be authenticated using an API key provided as a Bearer token in the `Authorization` header.

### Method
N/A (This describes a header requirement for all requests)

### Endpoint
N/A

### Parameters
#### Request Headers
- **Authorization** (string) - Required - The API key prefixed with `xobni_`, formatted as `Bearer xobni_<your-api-key>`.

### Request Example
```
Authorization: Bearer xobni_<your-api-key>
```

### Response
N/A (This is a request header requirement)
```

--------------------------------

### API Keys API

Source: https://www.xobni.ai/docs/rest-api

Endpoints for managing API keys, including listing, creating, and revoking them.

```APIDOC
## GET /api-keys

### Description
List your API keys.

### Method
GET

### Endpoint
`/api-keys`

### Response
#### Success Response (200)
- **api_keys** (array) - A list of API key objects.

#### Response Example
```json
{
  "api_keys": [
    {
      "id": "key_abc",
      "name": "My App Key",
      "created_at": "2023-10-27T09:00:00Z"
    }
  ]
}
```

## POST /api-keys

### Description
Create a new API key.

### Method
POST

### Endpoint
`/api-keys`

### Parameters
#### Request Body
- **name** (string) - Required - A name for the API key.

### Request Example
```json
{
  "name": "New Service Key"
}
```

### Response
#### Success Response (200)
- **api_key** (object) - The newly created API key object, including the secret.

#### Response Example
```json
{
  "api_key": {
    "id": "key_def",
    "name": "New Service Key",
    "secret": "sk_test_xxxxxxxxxxxxxxxxxxxx",
    "created_at": "2023-10-27T09:05:00Z"
  }
}
```

## DELETE /api-keys/{id}

### Description
Revoke an API key.

### Method
DELETE

### Endpoint
`/api-keys/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the API key to revoke.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "API key revoked successfully."
}
```
```
Tokens:
Raw