Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: CommsHarbor Email API
version: 1d751aaf
description: Manage domain email, mailboxes, aliases and durable jobs. Each call uses its organization's identity.
servers:
- url: https://commsharbor.com
tags:
- name: Email
paths:
/api/email/workspaces/{id}:
get:
operationId: commsharbor_email_workspace_snapshot
summary: Read the aggregate used by the live email workspace
description: 'The ID must match X-Organization-Id. Membership is checked again for each snapshot and delivered event. Events contain only an opaque change ID. DNS checks run in the private backend, with a 24-hour deadline and a visible resume action after pause.
Returns: { plan, subscription, capabilities, bootstrap, activation_required?, access_state, usage, domains, mailboxes, aliases, jobs }'
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Selected organization ID.
example: $ORG
responses:
'200':
description: '{ plan, subscription, capabilities, bootstrap, activation_required?, access_state, usage, domains, mailboxes, aliases, jobs }'
content:
application/json:
schema:
type: object
properties:
plan:
type: string
description: Current free, paid or operator bootstrap plan.
nullable: true
subscription:
type: object
description: Observed service state and valid_until. Optional payment has state confirmed, plan, environment, valid_until and renewal_state from the current paid grant. A sandbox payment cannot activate a production service. Cancellation stops renewal and preserves the confirmed paid period. No payer or card data.
capabilities:
type: object
description: Observed smtp_send, storage_mode and storage_mb. Trial uses shared storage and denies sending. A paid upgrade can remain awaiting_activation while native mailbox policy is updated.
bootstrap:
type: boolean
description: Operator-managed adoption.
activation_required:
type: boolean
description: The confirmed payment environment cannot provision this control environment. Request operator activation. This field does not grant provisioning.
access_state:
type: string
description: Active or expired paid access. Expiry preserves stored mailbox data.
usage:
type: object
description: Reserved domain, mailbox, alias and storage counts.
domains:
type: array
items:
type: object
description: 'Domains with observed state, DNS provider, copyable setup instructions and verified webmail URLs. dns_progress has completed, total, percent, ready, checked_at and records. Each record has verified, status (pending: no answer of this type; mismatch: different published value; unavailable: lookup failed; verified: matched) and observed (up to 16 published values, 4096 characters each). No observation means not checked yet. dns_monitor has state and, when scheduled, next_check_at in UTC; checking is true while the job runs. A due time is not a propagation estimate. Percent counts confirmed records, not delivery readiness. DNS completion alone does not grant mailbox creation. Assistance has job_id, state and requested_at.'
mailboxes:
type: array
items:
type: object
description: Mailbox addresses, display names and quotas. No passwords.
aliases:
type: array
items:
type: object
description: Alias addresses and destinations.
jobs:
type: array
items:
type: object
description: At most 20 recent jobs. Monitoring is an active scheduled observation, not a completed setup. Each job also has its direct status_url.
required:
- plan
- subscription
- capabilities
- bootstrap
- access_state
- usage
- domains
- mailboxes
- aliases
- jobs
'401':
description: No signed-in session, or the API key is invalid or revoked (`invalid_api_key`); an old `ch_…` key answers `api_key_retired`.
'403':
description: The session or key lacks the permission this operation needs (an API key never reaches billing, erasure, exports or the audit trail), an account key was used where an organization key is needed (`organization_key_required`), or an owner/admin has no second factor (`organization_mfa_required`).
'404':
description: The organization is not available to this session or key (no membership, CommsHarbor is not enabled for it, or the key belongs to another organization), or the resource does not exist in it. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
'503':
description: The shared account is unavailable.
tags:
- Email
/api/email/plans:
get:
operationId: commsharbor_email_plans
summary: Read the free Trial, three paid packages, storage allowances and activation…
description: 'Returns: { currency, country, brl_per_usd, price_is_estimate, billing_currency, interval, auto_renew, cancellation, paid_access, trial_days, trial, plans, checkout_live, on_demand_activation }'
security: []
parameters:
- name: lingua
in: query
required: false
schema:
type: string
enum:
- en
- pt
description: Selected language. Without it, use the shared request language policy.
responses:
'200':
description: '{ currency, country, brl_per_usd, price_is_estimate, billing_currency, interval, auto_renew, cancellation, paid_access, trial_days, trial, plans, checkout_live, on_demand_activation }'
content:
application/json:
schema:
type: object
properties:
currency:
type: string
description: 'Display currency: BRL only for Portuguese and country BR from the trusted origin. Otherwise USD, including unknown country.'
country:
type: string
description: Country supplied by the trusted origin, or empty when unknown. A query or client header cannot set it.
brl_per_usd:
type: number
description: Configured reference exchange rate. This is not your card issuer's exchange rate.
price_is_estimate:
type: boolean
description: True for USD display prices. Card charges use billing_currency and billing_price_cents.
billing_currency:
type: string
description: BRL. The current subscription provider charges Brazilian reais.
interval:
type: string
description: Monthly billing.
auto_renew:
type: boolean
description: Monthly automatic renewal until cancellation.
cancellation:
type: string
description: Cancellation stops future charges.
paid_access:
type: string
description: Access lasts until the end of the paid period.
trial_days:
type: integer
description: Zero. There is no automatic trial conversion.
trial:
type: object
description: 'Free receive-only trial for `days` (7) days, once per organization: storage_mb 1024 shared across unlimited mailboxes (mailboxes null), one domain, smtp_send false, no card and no automatic renewal (`expires` true). After it ends, writes without a paid plan answer 402 `email_trial_expired`. activation_ready is true only after native quota and protocol proof. Activation uses the organization trial route. A paid subscription enables sending only after backend confirmation.'
plans:
type: array
items:
type: object
description: Three packages with price_cents in display currency, billing_price_cents in BRL, domains, mailboxes, mailbox_gb, email_storage_gb, files_gb, aliases, features and on_demand.
checkout_live:
type: boolean
description: Whether new real subscriptions are open.
on_demand_activation:
type: string
description: Agree scope and activation date before charging for on-demand services.
required:
- currency
- country
- brl_per_usd
- price_is_estimate
- billing_currency
- interval
- auto_renew
- cancellation
- paid_access
- trial_days
- trial
- plans
- checkout_live
- on_demand_activation
tags:
- Email
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Use an organisation API key (`mmk_…`) for permitted work in that organisation. Account operations require the shared account session. Paid routes accept a global credit token (`cred_…`). Monthly purchases require a recent human session.
globalAccount:
type: apiKey
in: cookie
name: __Host-mm-auth
description: Global session in the product's HttpOnly cookie; writes require exact Origin and X-CSRF-Token.
contaChaveApi:
type: http
scheme: bearer
bearerFormat: mmk_…
description: 'Account API key: `Authorization: Bearer mmk_…` or `X-Api-Key: mmk_…`. Created on the account page (API keys), valid only in the product where it was created; it acts as the account (or the organization that owns it).'
carteiraAgente:
type: http
scheme: bearer
bearerFormat: mmw_…
description: 'Wallet credential of an agent without an account (`Authorization: Bearer mmw_…`, 30 days, this product only): POST /api/auth/wallet/agent/start, sign the message with the wallet, POST /api/auth/wallet/agent/token. The owner is `x402:<address>`.'
x-service-info:
categories:
- email
- mailbox-management
docs:
homepage: https://commsharbor.com/
apiReference: https://commsharbor.com/developers
llms: https://commsharbor.com/llms.txt