Developers

Pixu API Reference

Build on the authenticated Pixu API for mailboxes, conversations, compose, encrypted document signing, AI agents, knowledge, rules, analytics, deliverability, and webhooks.

Base URL

https://pixu.in/api/v1

Auth

API key bearer tokens or the X-API-Key header.

Schema

OpenAPI JSON

Authentication

API calls accept Pixu API keys created by organization admins in Settings > API Keys. Send the key as Authorization: Bearer pixu_live_... or X-API-Key: pixu_live_.... Keys inherit the current role, tenant, and mailbox visibility of the user who created them, and each key is limited to its selected scopes. Revoked or expired keys stop working immediately.

curl https://pixu.in/api/v1 \
  -H "Authorization: Bearer pixu_live_your_key"

The API returns 401 for missing or invalid credentials and uses the same organization and mailbox scoping as the dashboard.

Core Resources

Area	Typical endpoints
API index	GET /api/v1 Discover the authenticated surface and current principal.
Capabilities	GET /api/v1/capabilities Inspect scopes, limits, resource coverage, and MCP tool metadata.
Mailboxes	GET, POST /api/v1/mailboxes Create, edit, assign, connect, and inspect mailboxes.
Conversations	GET /api/v1/conversations List scoped threads, read messages, reply, label, snooze, and upload attachments.
Compose	POST /api/v1/compose/send Send or schedule new mail with cc, bcc, attachments, signatures, and encryption flags.
Agent chat	POST /api/v1/chat Run agentic commands against mailbox context, knowledge, templates, and rules.
MCP tools	POST /mcp Connect Claude Code, Cursor, and other MCP clients to Pixu tools using the client model for reasoning.
India Stack	/api/v1/india/* GST, UPI, ONDC, DigiLocker, MCA, e-sign, data residency, and audited provider readiness.
INR billing	/api/v1/billing/inr-plans Read rupee plans, GST billing posture, payment modes, and checkout configuration.
Knowledge	/api/v1/knowledge Manage tenant articles/files and search RAG context.
Templates	/api/v1/templates Create reusable templates and AI-generated HTML/text bodies.
Rules	/api/v1/rules Create routing, forwarding, labeling, department, and automation rules.
Analytics	/api/v1/analytics Read scoped performance, deliverability, mailbox, and tenant metrics.
Webhooks	/api/v1/webhooks Register signed event callbacks for external systems.

Common Requests

Connect Pixu as an MCP server

MCP lets Claude Code, Cursor, and other agent clients use their own model to reason while Pixu executes scoped mailbox, domain, knowledge, rules, compose, and reply tools.

Claude Code

claude mcp add --transport http pixu https://pixu.in/mcp \
  --header "Authorization: Bearer pixu_live_your_key"

Cursor

{
  "mcpServers": {
    "pixu": {
      "url": "https://pixu.in/mcp",
      "headers": {
        "Authorization": "Bearer pixu_live_your_key"
      }
    }
  }
}

curl https://pixu.in/mcp \
  -H "Authorization: Bearer pixu_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

MCP requires a Pixu API key with mcp.access. Each tool then requires the matching resource scope, for example mail.read, mail.send, mailboxes.manage, domains.manage, knowledge.manage, rules.manage, or analytics.read.

MCP exposes guarded tools for scoped mail search, analytics overview, deliverability health, audit review, mailbox/domain automation, and draft/send actions. Durable tool calls and failures are written to the organization audit log.

Send a message

Compose supports cc, bcc, HTML/plain bodies, attachments, signatures, scheduled sending, and encrypted send flags.

curl https://pixu.in/api/v1/compose/send \
  -H "Authorization: Bearer pixu_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mailbox_uuid",
    "to": ["customer@example.com"],
    "cc": [],
    "bcc": [],
    "subject": "Welcome to Pixu",
    "body_text": "Hi Jordan,\n\nThanks for reaching out...",
    "body_html": "<p>Hi Jordan,</p><p>Thanks for reaching out...</p>",
    "attachment_tokens": [],
    "encrypt": false
  }'

Reply inside an existing thread

Replies preserve conversation context and threading headers so provider inboxes keep the exchange together.

curl https://pixu.in/api/v1/conversations/conversation_uuid/reply \
  -H "Authorization: Bearer pixu_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "body_text": "Hi,\n\nHere is the update...",
    "cc": ["manager@example.com"],
    "bcc": [],
    "attachment_tokens": []
  }'

Run the agentic command API

The chat endpoint can summarize, draft, route, search knowledge, inspect mailbox state, and prepare actions inside the authenticated scope.

curl https://pixu.in/api/v1/chat \
  -H "X-API-Key: pixu_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mailbox_uuid",
    "message": "Summarize unread billing conversations and draft follow-ups"
    }'

Security Model

API access is tenant-scoped by design. Regular users can only access assigned mailboxes and department conversations. Admins can access their organization. Superadmins retain platform controls, but API keys still resolve through the user who created them.

Store keys as secrets; Pixu only shows the full value once when it is created.
Use scopes such as mail.read, mail.send, agent.run, and webhooks.manage instead of full access unless the integration genuinely needs it.
Use separate keys for production, automation, and test integrations so each can be revoked independently.
For server-to-server workflows, prefer API keys over browser session JWTs.
Secure Send supports encrypted document envelopes with digital typed and handwritten drawn signatures, proof gates, activity tracking, and no-store certificate JSON at /api/public/secure/:id/certificate.
Mailbox visibility, department routing, and organization boundaries are enforced on every request.

Webhook Events

Webhooks notify external systems about mail received, sends, bounces, complaints, domain verification, rule execution, and agent actions. Pixu signs outgoing webhook payloads with the shared secret configured by the tenant administrator.

mail.receivedmail.sentmail.failedconversation.updatedagent.actionrule.matchedbounce.receivedcomplaint.receiveddomain.verified

Support

For integration help, email developers@pixu.in.