API docs by Redocly

CentralBox API (1.0.0)

Download OpenAPI specification:

CentralBox is private, hosted email on your own domain, built on Amazon SES. This is the SOURCE OF TRUTH for the API contract. npm run generate:schema emits src/schema/api/* (Zod schemas + operation/route table) consumed by the router; generate:api-docs and generate:api-tests also derive from here. Phase 2 adds domains & addresses; Phase 3 adds mail (send + inbox). contacts/campaigns/billing endpoints land in later phases per design-docs/centralbox-execution-plan.md.

misc

Health and utility endpoints

Health check

Responses

Response samples

Content type
application/json
{
  • "message": "pong"
}

domains

Domain identity (DKIM/SPF/DMARC/MX) lifecycle

Add a domain — returns DKIM/SPF/DMARC/MX DNS records to add

Authorizations:
apiKey(dashboardOriginsession)
Request Body schema: application/json
required
domain
required
string

Responses

Request samples

Content type
application/json
{
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "domain": "string",
  • "status": "pending",
  • "dkimTokens": [
    ],
  • "mailFromDomain": "string",
  • "dnsRecords": [
    ],
  • "configurationSetName": "string",
  • "createdAt": 0
}

List domains on this account

Authorizations:
apiKey(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Get DNS/verification detail for a domain

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "domain": "string",
  • "status": "pending",
  • "dkimTokens": [
    ],
  • "mailFromDomain": "string",
  • "dnsRecords": [
    ],
  • "configurationSetName": "string",
  • "createdAt": 0
}

Delete a domain

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Idempotent poll — re-check DNS + SES verification status

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "domain": "string",
  • "status": "pending",
  • "dkimTokens": [
    ],
  • "mailFromDomain": "string",
  • "dnsRecords": [
    ],
  • "configurationSetName": "string",
  • "createdAt": 0
}

addresses

Mailboxes/aliases + team role grants

Create a mailbox/alias on a verified domain

Authorizations:
apiKey(dashboardOriginsession)
Request Body schema: application/json
required
address
required
string
displayName
string
signature
string

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "displayName": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "address": "string",
  • "displayName": "string",
  • "signature": "string",
  • "grants": [
    ],
  • "createdAt": 0
}

List addresses on this account

Authorizations:
apiKey(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "addresses": [
    ]
}

Get an address

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "address": "string",
  • "displayName": "string",
  • "signature": "string",
  • "grants": [
    ],
  • "createdAt": 0
}

Update display name / signature

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
displayName
string
signature
string

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "address": "string",
  • "displayName": "string",
  • "signature": "string",
  • "grants": [
    ],
  • "createdAt": 0
}

Delete an address

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Share an address to team members with a role

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
required
Array of objects (Grant)

Responses

Request samples

Content type
application/json
{
  • "grants": [
    ]
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "address": "string",
  • "displayName": "string",
  • "signature": "string",
  • "grants": [
    ],
  • "createdAt": 0
}

mail

Send outbound mail; read/manage the inbox

Send from an owned address (SES simple/raw send)

Authorizations:
apiKey(dashboardOriginsession)
Request Body schema: application/json
required
from
required
string
to
required
string
subject
required
string
text
string
html
string

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "to": "string",
  • "subject": "string",
  • "text": "string",
  • "html": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "sortKey": "string",
  • "threadId": "string",
  • "address": "string",
  • "folder": "inbox",
  • "direction": "inbound",
  • "subject": "string",
  • "snippet": "string",
  • "flags": {
    },
  • "s3Key": "string",
  • "sesMessageId": "string",
  • "createdAt": 0,
  • "rawMimeUrl": "string"
}

List messages by address/folder, paginated

Authorizations:
apiKey(dashboardOriginsession)
query Parameters
address
string
folder
string
Enum: "inbox" "sent" "drafts" "spam" "trash"

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ]
}

Read a message (parsed body + presigned raw-MIME S3 link)

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "sortKey": "string",
  • "threadId": "string",
  • "address": "string",
  • "folder": "inbox",
  • "direction": "inbound",
  • "subject": "string",
  • "snippet": "string",
  • "flags": {
    },
  • "s3Key": "string",
  • "sesMessageId": "string",
  • "createdAt": 0,
  • "rawMimeUrl": "string"
}

Mark read/star/move/label

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
read
boolean
starred
boolean
labels
Array of strings
folder
string
Enum: "inbox" "sent" "drafts" "spam" "trash"

Responses

Request samples

Content type
application/json
{
  • "read": true,
  • "starred": true,
  • "labels": [
    ],
  • "folder": "inbox"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "sortKey": "string",
  • "threadId": "string",
  • "address": "string",
  • "folder": "inbox",
  • "direction": "inbound",
  • "subject": "string",
  • "snippet": "string",
  • "flags": {
    },
  • "s3Key": "string",
  • "sesMessageId": "string",
  • "createdAt": 0,
  • "rawMimeUrl": "string"
}

Trash a message (soft-delete; 30-day expiry lifecycle)

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Full conversation for a thread

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ]
}

Create a draft (compose flow) — stored in the drafts folder

Authorizations:
apiKey(dashboardOriginsession)
Request Body schema: application/json
required
from
required
string
to
Array of strings
cc
Array of strings
bcc
Array of strings
subject
string
text
string
html
string

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "bcc": [
    ],
  • "subject": "string",
  • "text": "string",
  • "html": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "sortKey": "string",
  • "threadId": "string",
  • "address": "string",
  • "folder": "inbox",
  • "direction": "inbound",
  • "subject": "string",
  • "snippet": "string",
  • "flags": {
    },
  • "s3Key": "string",
  • "sesMessageId": "string",
  • "createdAt": 0,
  • "rawMimeUrl": "string"
}

Update a draft's content

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
to
Array of strings
cc
Array of strings
bcc
Array of strings
subject
string
text
string
html
string

Responses

Request samples

Content type
application/json
{
  • "to": [
    ],
  • "cc": [
    ],
  • "bcc": [
    ],
  • "subject": "string",
  • "text": "string",
  • "html": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "sortKey": "string",
  • "threadId": "string",
  • "address": "string",
  • "folder": "inbox",
  • "direction": "inbound",
  • "subject": "string",
  • "snippet": "string",
  • "flags": {
    },
  • "s3Key": "string",
  • "sesMessageId": "string",
  • "createdAt": 0,
  • "rawMimeUrl": "string"
}

Send a draft — validates recipients, sends, and removes the draft

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "sortKey": "string",
  • "threadId": "string",
  • "address": "string",
  • "folder": "inbox",
  • "direction": "inbound",
  • "subject": "string",
  • "snippet": "string",
  • "flags": {
    },
  • "s3Key": "string",
  • "sesMessageId": "string",
  • "createdAt": 0,
  • "rawMimeUrl": "string"
}

auth

Dashboard passwordless (magic-link) authentication

Register (or re-send a link for) an account, and email a magic link

Authorizations:
(dashboardOriginrecaptcha)
Request Body schema: application/json
required
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Email a magic link to an existing account

Authorizations:
(dashboardOriginrecaptcha)
Request Body schema: application/json
required
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Consume a one-time magic-link token and start a session

Authorizations:
dashboardOrigin
Request Body schema: application/json
required
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Destroy the current session

Authorizations:
(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

user

Dashboard user profile

Get the current dashboard user's profile

Authorizations:
(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "userId": "string",
  • "name": "string",
  • "createdAt": 0
}

account

Dashboard account (plan, billing linkage)

Current account — plan, billing linkage, and the caller's role

Authorizations:
(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "plan": "trial",
  • "createdAt": 0,
  • "role": "owner",
  • "hasBilling": true
}

keys

Send-API key management (dashboard session only)

Create a Send-API key — the full key is returned exactly once

Authorizations:
(dashboardOriginsession)
Request Body schema: application/json
required
label
required
string
scopes
Array of strings
domains
Array of strings

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "scopes": [
    ],
  • "domains": [
    ]
}

Response samples

Content type
application/json
{
  • "keyId": "string",
  • "accountId": "string",
  • "label": "string",
  • "scopes": [
    ],
  • "domains": [
    ],
  • "status": "active",
  • "createdAt": 0,
  • "lastUsedAt": 0,
  • "fullKey": "string"
}

List Send-API keys on this account (metadata only)

Authorizations:
(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Revoke a Send-API key (status flip; rotation = re-issue)

Authorizations:
(dashboardOriginsession)
path Parameters
keyId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

contacts

Contact CRUD

Create a contact

Authorizations:
apiKey(dashboardOriginsession)
Request Body schema: application/json
required
email
required
string
name
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "contactId": "string",
  • "email": "string",
  • "name": "string",
  • "status": "subscribed",
  • "createdAt": 0
}

List contacts on this account

Authorizations:
apiKey(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "contacts": [
    ]
}

Get a contact

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "contactId": "string",
  • "email": "string",
  • "name": "string",
  • "status": "subscribed",
  • "createdAt": 0
}

Update a contact

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
name
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "contactId": "string",
  • "email": "string",
  • "name": "string",
  • "status": "subscribed",
  • "createdAt": 0
}

Delete a contact

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

lists

Contact lists / audiences, membership, CSV import, unsubscribe

Create a contact list / audience

Authorizations:
apiKey(dashboardOriginsession)
Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "listId": "string",
  • "name": "string",
  • "memberCount": 0,
  • "createdAt": 0
}

List contact lists on this account

Authorizations:
apiKey(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "lists": [
    ]
}

Get a contact list

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "listId": "string",
  • "name": "string",
  • "memberCount": 0,
  • "createdAt": 0
}

Delete a contact list

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Add a contact to a list

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
contactId
required
string

Responses

Request samples

Content type
application/json
{
  • "contactId": "string"
}

Response samples

Content type
application/json
{
  • "listId": "string",
  • "contactId": "string",
  • "subscribed": true,
  • "unsubToken": "string"
}

Remove a contact from a list

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
contactId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

CSV import (one contact per line, `email[,name]`)

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
csv
required
string

Responses

Request samples

Content type
application/json
{
  • "csv": "string"
}

Response samples

Content type
application/json
{
  • "imported": 0
}

Unsubscribe a contact from a list

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
contactId
required
string

Responses

Request samples

Content type
application/json
{
  • "contactId": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

One-click unsubscribe (RFC 8058) — public, no auth

path Parameters
token
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

campaigns

Bulk/marketing email campaigns

Create a campaign (draft)

Authorizations:
apiKey(dashboardOriginsession)
Request Body schema: application/json
required
fromAddress
required
string
listId
required
string
subject
required
string
text
string
html
string

Responses

Request samples

Content type
application/json
{
  • "fromAddress": "string",
  • "listId": "string",
  • "subject": "string",
  • "text": "string",
  • "html": "string"
}

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "campaignId": "string",
  • "fromAddress": "string",
  • "listId": "string",
  • "subject": "string",
  • "text": "string",
  • "html": "string",
  • "templateName": "string",
  • "status": "draft",
  • "stats": {
    },
  • "createdAt": 0
}

List campaigns on this account

Authorizations:
apiKey(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "campaigns": [
    ]
}

Get a campaign

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "campaignId": "string",
  • "fromAddress": "string",
  • "listId": "string",
  • "subject": "string",
  • "text": "string",
  • "html": "string",
  • "templateName": "string",
  • "status": "draft",
  • "stats": {
    },
  • "createdAt": 0
}

Delete a campaign

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Send a test email to a single address

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string
Request Body schema: application/json
required
testAddress
required
string

Responses

Request samples

Content type
application/json
{
  • "testAddress": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Enqueue the bulk send (SES v2 bulk/templated)

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "string",
  • "campaignId": "string",
  • "fromAddress": "string",
  • "listId": "string",
  • "subject": "string",
  • "text": "string",
  • "html": "string",
  • "templateName": "string",
  • "status": "draft",
  • "stats": {
    },
  • "createdAt": 0
}

Opens/clicks/bounces/complaints rollup

Authorizations:
apiKey(dashboardOriginsession)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "property1": 0,
  • "property2": 0
}

billing

Stripe checkout, portal, and webhooks

Start a Stripe Checkout Session for a paid plan

Authorizations:
(dashboardOriginsession)
Request Body schema: application/json
required
plan
required
string
Enum: "personal" "team"

Responses

Request samples

Content type
application/json
{
  • "plan": "personal"
}

Response samples

Content type
application/json
{
  • "url": "string"
}

Open the Stripe Billing Portal

Authorizations:
(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "url": "string"
}

Stripe webhook (signature-verified; handled outside normal dispatch for the raw body)

Request Body schema: application/json
required
Schema not provided

Responses

Request samples

Content type
application/json
{
  • "placeholder": true
}

Response samples

Content type
application/json
{
  • "received": true
}

analytics

Usage and deliverability rollups

Usage by month (sends/inbound/storage)

Authorizations:
apiKey(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "usage": [
    ]
}

Delivery/bounce/complaint/open/click rates

Authorizations:
apiKey(dashboardOriginsession)

Responses

Response samples

Content type
application/json
{
  • "domains": [
    ],
  • "deliveries": 0,
  • "bounces": 0,
  • "complaints": 0,
  • "opens": 0,
  • "clicks": 0,
  • "perDomain": {
    }
}