Innbocks Partner API

Build your CRM and billing system on top of Innbocks operations.

Use `/api/v1` to provision invited customers, map external CRM IDs, read compliance and mail state, request mail actions, inspect webhooks, and reconcile active mailbox usage.

Tooling

Interactive API ReferenceOpenAPI JSONAPI Keys

No account yet? Create your store to create API keys.

Authentication

Create scoped keys in Dashboard Settings, then send them as `Authorization: Bearer ib_live_...`.

Idempotency

Send `Idempotency-Key` on customer creation, updates, deactivation, and mail-action requests to safely retry CRM jobs.

Errors

Errors use `"error": { "code", "message", "request_id" }. Every response includes `X-Request-Id`.

Rate limits

1200 requests per minute per API key. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds until the window resets), and `RateLimit-Policy`, plus the legacy `X-RateLimit-*` trio. A 429 also carries `Retry-After`. Self-throttle from these headers instead of retrying blindly.

Versioning & deprecation policy

The Innbocks Partner API is versioned in the URL path (`/api/v1`). Breaking changes ship only in a new version path; `v1` responses may gain fields but never lose or repurpose them, so ignore unknown fields. When an endpoint or version is scheduled for removal, its responses carry `Deprecation` and `Sunset` headers ahead of the removal date, and this section documents the timeline and migration path. No sunsets are currently scheduled.

Innbocks MCP server

An MCP (Model Context Protocol) server runs at `https://www.innbocks.com/api/mcp` over Streamable HTTP, with a manifest at `/.well-known/mcp.json`. Anonymous clients get documentation resources (llms.txt, this page, the OpenAPI spec) and the `list_api_operations` / `get_api_operation` discovery tools. The `call_partner_api` tool executes real Partner API requests when your MCP client sends `Authorization: Bearer ib_live_...`, using a key from Dashboard Settings or one granted through the OAuth 2.1 flow advertised at `/.well-known/oauth-authorization-server`.

Inbound Mail Operations

Partners with `mail:write` can create inbound mail/package records for their own customers. The API requires `customer_id`, `type`, at least one photo URL, and `performed_by`. Innbocks verifies that the customer belongs to the partner, has active billing/prepay, and is approved for mailbox receipt before emitting `mail.arrived` or `package.arrived`. Reassignment is intentionally not exposed; delete a partner-created mail record and recreate it if your system assigned it incorrectly.

MVP Endpoints

POST/api/v1/customersCreate an invited customer and mailbox
GET/api/v1/customersList customers
GET/api/v1/customers/{customer_id}Retrieve a customer
PATCH/api/v1/customers/{customer_id}Update CRM-managed fields
POST/api/v1/customers/{customer_id}/deactivateDeactivate service
GET/api/v1/customers/{customer_id}/complianceRead Form 1583 and ID status
GET/api/v1/customers/{customer_id}/mailList customer mail
GET/api/v1/customers/{customer_id}/mailboxRead mailbox assignment
POST/api/v1/mailCreate inbound mail/package
GET/api/v1/mail/{mail_id}Retrieve a mail item
DELETE/api/v1/mail/{mail_id}Delete partner-created mail
POST/api/v1/mail/{mail_id}/scanRequest scan
POST/api/v1/mail/{mail_id}/forwardRequest forwarding
POST/api/v1/mail/{mail_id}/shredRequest shredding
POST/api/v1/mail/{mail_id}/pickupRequest pickup
GET/api/v1/webhook-eventsList event types
GET/api/v1/webhook-deliveriesList webhook delivery attempts
GET/api/v1/billing/usageRead active-mailbox usage

Scopes

customers:readcustomers:writemail:readmail:writemail_actions:writewebhooks:readbilling:readplans:read

Create Customer

curl -X POST https://www.innbocks.com/api/v1/customers \
  -H "Authorization: Bearer ib_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm_customer_123_create" \
  -d '{
    "external_customer_id": "crm_customer_123",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "phone": "+15555555555",
    "prepay": true
  }'

Create Inbound Mail

curl -X POST https://www.innbocks.com/api/v1/mail \
  -H "Authorization: Bearer ib_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inbound_mail_789" \
  -d '{
    "customer_id": "cus_123",
    "type": "package",
    "photos": ["https://example.com/package-front.jpg"],
    "performed_by": "warehouse_user_42",
    "tracking_number": "1Z9999999999999999"
  }'

Webhook Verification

import crypto from "crypto";

export function verifyInnbocksWebhook(rawBody, timestamp, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  const received = signatureHeader
    ?.split(",")
    .map((part) => part.trim())
    .find((part) => part.startsWith("v1="))
    ?.slice(3);

  return Boolean(received) &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}