Skip to content

API reference

InboxCNX API 0.1.0

Section titled “InboxCNX API 0.1.0”

Read and act on your users’ mailboxes through one API: connect a mailbox, then query its messages and threads, act on messages and receive webhooks.

Preview. The API is under active development. Endpoints and schemas may still change without a version bump.

Authentication. Every /v1/* request carries Authorization: Bearer <credential>. The credential is either an Application API key (icnx_…, created in the dashboard, server-side only) or a grant token (icnxg_…, minted with POST /v1/grants/{id}/token, scoped to one mailbox).

Errors. Every error response has the shape { "error": { "code": "…", "message": "…" } }. Branch on code, not on message. A 429 rate_limited comes with a Retry-After header.

OpenAPI spec (JSON)

Information

  • OpenAPI version: 3.1.0

Operations

Section titled “Operations”
GET
/v1/me
GET
/v1/connections
POST
/v1/grants/{id}/token
GET
/v1/grants/{id}/labels
DELETE
/v1/grants/{id}
PATCH
/v1/grants/{id}
GET
/v1/grants/{id}/backfill
POST
/v1/grants/{id}/backfill
DELETE
/v1/grants/{id}/backfill
GET
/v1/grants/{id}/backfill-estimate
GET
/v1/backfills
GET
/v1/messages
POST
/v1/messages/query
GET
/v1/messages/{id}
PATCH
/v1/messages/{id}
GET
/v1/attachments/{id}
GET
/v1/raw/{id}
POST
/v1/messages/batch
POST
/v1/messages/batch/trash
POST
/v1/messages/batch/untrash
POST
/v1/messages/batch/report-spam
POST
/v1/messages/batch/not-spam
POST
/v1/messages/{id}/trash
POST
/v1/messages/{id}/untrash
POST
/v1/messages/{id}/report-spam
POST
/v1/messages/{id}/not-spam
GET
/v1/threads
POST
/v1/threads/query
GET
/v1/threads/{id}
PATCH
/v1/application
GET
/v1/profiles
POST
/v1/profiles
GET
/v1/profiles/{key}
DELETE
/v1/profiles/{key}
PATCH
/v1/profiles/{key}
GET
/v1/status
GET
/v1/usage
GET
/v1/webhook-event-types
GET
/v1/webhook-endpoints
POST
/v1/webhook-endpoints
GET
/v1/webhook-endpoints/{id}
DELETE
/v1/webhook-endpoints/{id}
PATCH
/v1/webhook-endpoints/{id}
POST
/v1/webhook-endpoints/{id}/rotate-secret
GET
/v1/deliveries
GET
/v1/deliveries/stats
POST
/v1/deliveries/{id}/replay
POST
message.received WEBHOOK
POST
message.updated WEBHOOK
POST
message.deleted WEBHOOK
POST
message.enrich WEBHOOK
POST
usage.period.closed WEBHOOK
POST
grant.revoked WEBHOOK
POST
connection.error WEBHOOK
POST
connection.restored WEBHOOK
POST
grant.revocation_scheduled WEBHOOK
POST
grant.cap_reached WEBHOOK
POST
grant.created WEBHOOK
POST
grant.backfill_completed WEBHOOK

Authentication

Section titled “Authentication”

apiKey

Section titled “apiKey”

An application API key, icnx_…. Created in the dashboard with the scopes the application needs. Server-side only: never ship it to a browser or an app.

Security scheme type: http

grantToken

Section titled “grantToken”

A grant token, icnxg_…, minted with POST /v1/grants/{id}/token. Valid for 5 minutes and confined to one end user’s mailbox. It carries only the mail scopes (read:messages, modify:messages, delete:messages, report:spam) its API key holds. In a Whitelabel application, mail is readable only with a grant token: an API key gets 403 grant_token_required.

Security scheme type: http