# CommsHarbor

> Transactional email and permission-based marketing with tenant isolation.
> English is the default product language; the human UI is also available in pt-BR.

## Descoberta

- [API catalog](https://commsharbor.com/api/)
- [OpenAPI](https://commsharbor.com/openapi.json)
- [Remote MCP](https://commsharbor.com/mcp)
- [Human workspace](https://commsharbor.com/app)

## Endpoints principais

- `GET /api/health` — Read build and environment health (auth: none)
- `GET /mcp` — Inspect the remote MCP transport (auth: none)
- `POST /api/auth/start` — Send a one-time login code (auth: none)
- `POST /api/auth/verify` — Verify an OTP and create a session (auth: none)
- `POST /api/auth/logout` — Revoke the current session (auth: session)
- `GET /api/me` — Read profile, memberships and platform role (auth: session)
- `PATCH /api/me` — Update the current profile (auth: session)
- `GET /api/organizations` — List organizations of the current user (auth: session)
- `POST /api/organizations` — Create one organization trial for a verified owner and domain (auth: session)
- `GET /api/context` — Resolve current organization identity (auth: organization)
- `GET /api/organizations/:organization_id` — Read an organization (auth: organization)
- `PATCH /api/organizations/:organization_id` — Update an organization (auth: organization_admin)
- `GET /api/organizations/:organization_id/members` — List organization members (auth: organization)
- `PATCH /api/organizations/:organization_id/members/:user_id` — Change a non-owner member role (auth: organization_admin)
- `GET /api/organizations/:organization_id/invitations` — List organization invitations without their tokens (auth: organization_admin)
- `POST /api/organizations/:organization_id/invitations` — Create an invitation and reveal its token once (auth: organization_admin)
- `POST /api/invitations/accept` — Accept an invitation into its existing organization trial (auth: session)
- `GET /api/organizations/:organization_id/api-keys` — List API keys without token hashes or secrets (auth: organization_admin)
- `POST /api/organizations/:organization_id/api-keys` — Create a scoped API key and reveal it once (auth: organization_admin)
- `DELETE /api/organizations/:organization_id/api-keys/:api_key_id` — Revoke an API key immediately (auth: organization_admin)
- `GET /api/organizations/:organization_id/audit` — List append-only organization audit events (auth: organization_admin)
- `GET /api/platform/context` — Confirm an explicitly granted platform administrator (auth: platform_admin)
- `GET /api/organizations/:organization_id/domains` — List tenant sending domains and their last observed state (auth: organization)
- `POST /api/organizations/:organization_id/domains` — Register the organization's sending domain and queue idempotent SES provisioning (auth: organization)
- `GET /api/organizations/:organization_id/domains/:domain_id` — Read a sending domain without inferring current DNS state (auth: organization)
- `POST /api/organizations/:organization_id/domains/:domain_id/verify` — Observe SES, DKIM, DMARC and custom MAIL FROM state in real time (auth: organization)
- `POST /api/organizations/:organization_id/domains/:domain_id/smoke` — Queue one controlled domain smoke to the server-side recipient secret (auth: organization)
- `GET /api/organizations/:organization_id/domains/:domain_id/deliveries` — List domain deliveries without recipient addresses (auth: organization)
- `GET /api/organizations/:organization_id/deliveries/:delivery_id` — Read one delivery and its SES MessageId without recipient data (auth: organization)
- `GET /api/organizations/:organization_id/deliveries/:delivery_id/events` — List normalized SES feedback events for one delivery (auth: organization)
- `POST /api/aws/sns` — Receive a signed Amazon SNS callback for the configured SES topic (auth: aws_sns)
- `GET /api/billing` — Read the versioned trial, pass and top-up catalog and x402 network (auth: none)
- `GET /api/organizations/:organization_id/billing` — Read the tenant entitlement, quota allocation and expiration warning (auth: organization)
- `POST /api/organizations/:organization_id/billing/purchases/:action` — Request pass or top-up; returns a standard x402 challenge while live checkout is disabled (auth: organization_admin)
- `GET /api/organizations/:organization_id/operations` — List current tenant operational alerts without recipient PII (auth: organization_admin)
- `POST /api/organizations/:organization_id/operations` — Refresh alerts, quota and global capacity observations (auth: organization_admin)
- `GET /api/organizations/:organization_id/data-exports` — List tenant data exports retained for seven days (auth: organization_admin)
- `POST /api/organizations/:organization_id/data-exports` — Create a tenant-scoped JSON data export retained for seven days (auth: organization_admin)
- `GET /api/organizations/:organization_id/data-exports/:export_id` — Download one tenant-scoped JSON export (auth: organization_admin)
- `GET /api/organizations/:organization_id/deletion-requests` — Read the latest tenant deletion request and grace-period state (auth: organization_admin)
- `POST /api/organizations/:organization_id/deletion-requests` — Schedule tenant erasure after a seven-day grace period (auth: organization_admin)
- `POST /api/organizations/:organization_id/deletion-requests/:request_id/cancel` — Cancel a tenant deletion while it is still scheduled (auth: organization_admin)
- `GET /api/organizations/:organization_id/crm/contacts` — List CRM contacts (auth: organization)
- `POST /api/organizations/:organization_id/crm/contacts` — Create a CRM contact (auth: organization)
- `GET /api/organizations/:organization_id/crm/contacts/:contact_id` — Read a CRM contact (auth: organization)
- `PATCH /api/organizations/:organization_id/crm/contacts/:contact_id` — Update a CRM contact (auth: organization)
- `DELETE /api/organizations/:organization_id/crm/contacts/:contact_id` — Delete a CRM contact (auth: organization)
- `GET /api/organizations/:organization_id/crm/companies` — List CRM companies (auth: organization)
- `POST /api/organizations/:organization_id/crm/companies` — Create a CRM company (auth: organization)
- `GET /api/organizations/:organization_id/crm/companies/:company_id` — Read a CRM company (auth: organization)
- `PATCH /api/organizations/:organization_id/crm/companies/:company_id` — Update a CRM company (auth: organization)
- `DELETE /api/organizations/:organization_id/crm/companies/:company_id` — Delete a CRM company (auth: organization)
- `GET /api/organizations/:organization_id/crm/pipelines` — List CRM pipelines (auth: organization)
- `POST /api/organizations/:organization_id/crm/pipelines` — Create a CRM pipeline (auth: organization)
- `GET /api/organizations/:organization_id/crm/pipelines/:pipeline_id` — Read a CRM pipeline (auth: organization)
- `PATCH /api/organizations/:organization_id/crm/pipelines/:pipeline_id` — Update a CRM pipeline (auth: organization)
- `DELETE /api/organizations/:organization_id/crm/pipelines/:pipeline_id` — Delete a CRM pipeline (auth: organization)
- `GET /api/organizations/:organization_id/crm/deals` — List CRM deals (auth: organization)
- `POST /api/organizations/:organization_id/crm/deals` — Create a CRM deal (auth: organization)
- `GET /api/organizations/:organization_id/crm/deals/:deal_id` — Read a CRM deal (auth: organization)
- `PATCH /api/organizations/:organization_id/crm/deals/:deal_id` — Update a CRM deal (auth: organization)
- `DELETE /api/organizations/:organization_id/crm/deals/:deal_id` — Delete a CRM deal (auth: organization)
- `GET /api/organizations/:organization_id/crm/activities` — List CRM activities (auth: organization)
- `POST /api/organizations/:organization_id/crm/activities` — Create a CRM activity (auth: organization)
- `GET /api/organizations/:organization_id/crm/activities/:activity_id` — Read a CRM activity (auth: organization)
- `PATCH /api/organizations/:organization_id/crm/activities/:activity_id` — Update a CRM activity (auth: organization)
- `DELETE /api/organizations/:organization_id/crm/activities/:activity_id` — Delete a CRM activity (auth: organization)
- `GET /api/organizations/:organization_id/crm/tasks` — List CRM tasks (auth: organization)
- `POST /api/organizations/:organization_id/crm/tasks` — Create a CRM task (auth: organization)
- `GET /api/organizations/:organization_id/crm/tasks/:task_id` — Read a CRM task (auth: organization)
- `PATCH /api/organizations/:organization_id/crm/tasks/:task_id` — Update a CRM task (auth: organization)
- `DELETE /api/organizations/:organization_id/crm/tasks/:task_id` — Delete a CRM task (auth: organization)
- `GET /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages` — List CRM stages (auth: organization)
- `POST /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages` — Create a CRM stage (auth: organization)
- `GET /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id` — Read a CRM stage (auth: organization)
- `PATCH /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id` — Update a CRM stage (auth: organization)
- `DELETE /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id` — Delete a CRM stage (auth: organization)
- `GET /api/platform/crm/leads` — List CRM leads (auth: platform_admin)
- `POST /api/platform/crm/leads` — Create a CRM lead (auth: platform_admin)
- `GET /api/platform/crm/leads/:lead_id` — Read a CRM lead (auth: platform_admin)
- `PATCH /api/platform/crm/leads/:lead_id` — Update a CRM lead (auth: platform_admin)
- `DELETE /api/platform/crm/leads/:lead_id` — Delete a CRM lead (auth: platform_admin)
- `GET /api/platform/crm/tasks` — List CRM tasks (auth: platform_admin)
- `POST /api/platform/crm/tasks` — Create a CRM task (auth: platform_admin)
- `GET /api/platform/crm/tasks/:task_id` — Read a CRM task (auth: platform_admin)
- `PATCH /api/platform/crm/tasks/:task_id` — Update a CRM task (auth: platform_admin)
- `DELETE /api/platform/crm/tasks/:task_id` — Delete a CRM task (auth: platform_admin)
- `GET /api/platform/crm/leads/:lead_id/activities` — List CRM activities (auth: platform_admin)
- `POST /api/platform/crm/leads/:lead_id/activities` — Create a CRM activity (auth: platform_admin)
- `GET /api/platform/crm/leads/:lead_id/activities/:activity_id` — Read a CRM activity (auth: platform_admin)
- `PATCH /api/platform/crm/leads/:lead_id/activities/:activity_id` — Update a CRM activity (auth: platform_admin)
- `DELETE /api/platform/crm/leads/:lead_id/activities/:activity_id` — Delete a CRM activity (auth: platform_admin)
- `GET /api/organizations/:organization_id/crm/contacts/:contact_id/marketing` — Read consent and marketing preference for one CRM contact (auth: organization)
- `PUT /api/organizations/:organization_id/crm/contacts/:contact_id/marketing` — Record permission-based marketing consent without restoring an unsubscribe (auth: organization)
- `POST /api/organizations/:organization_id/crm/contacts/:contact_id/preference-token` — Create a signed preference and one-click unsubscribe capability (auth: organization)
- `GET /api/preferences/:token` — Read preferences through a signed capability without login (auth: preference_capability)
- `POST /api/preferences/:token/unsubscribe` — Apply RFC 8058 one-click unsubscribe idempotently (auth: preference_capability)
- `POST /api/organizations/:organization_id/domains/:domain_id/marketing-smoke` — Queue one controlled permission-based marketing message to the server-side recipient (auth: organization)
- `GET /api/organizations/:organization_id/contact-imports` — List contact imports with an opaque cursor (auth: organization)
- `POST /api/organizations/:organization_id/contact-imports` — Upload a consent-declared CSV and return a safe preview (auth: organization)
- `GET /api/organizations/:organization_id/contact-imports/:import_id` — Read one durable contact import (auth: organization)
- `POST /api/organizations/:organization_id/contact-imports/:import_id/confirm` — Confirm an import idempotently and enqueue its durable ID (auth: organization)
- `GET /api/organizations/:organization_id/contact-imports/:import_id/errors` — List row-numbered import errors with an opaque cursor (auth: organization)
- `GET /api/organizations/:organization_id/contact-files/:file_id` — Download a tenant-owned CSV before its seven-day expiry (auth: organization)
- `POST /api/organizations/:organization_id/contacts/export` — Create a safe CSV export retained for seven days (auth: organization)
- `GET /api/organizations/:organization_id/suppressions` — List organization suppressions without exposing email hashes (auth: organization)
- `POST /api/organizations/:organization_id/suppressions` — Suppress one recipient in the active organization (auth: organization)
- `GET /api/organizations/:organization_id/audiences` — List static audiences and saved segments (auth: organization)
- `POST /api/organizations/:organization_id/audiences` — Create a static audience or allowlisted saved segment (auth: organization)
- `GET /api/organizations/:organization_id/audiences/:audience_id` — Read one tenant-owned audience (auth: organization)
- `PATCH /api/organizations/:organization_id/audiences/:audience_id` — Update an audience name or saved filter (auth: organization)
- `DELETE /api/organizations/:organization_id/audiences/:audience_id` — Delete an audience and its memberships (auth: organization)
- `GET /api/organizations/:organization_id/audiences/:audience_id/members` — List audience contacts with an opaque cursor (auth: organization)
- `POST /api/organizations/:organization_id/audiences/:audience_id/members` — Add a tenant CRM contact to a static audience (auth: organization)
- `DELETE /api/organizations/:organization_id/audiences/:audience_id/members/:contact_id` — Remove a contact from a static audience (auth: organization)
- `GET /api/organizations/:organization_id/templates` — List versioned email templates (auth: organization)
- `POST /api/organizations/:organization_id/templates` — Create a canonical block template draft (auth: organization_template_write)
- `GET /api/organizations/:organization_id/templates/:template_id` — Read one tenant-owned template draft (auth: organization)
- `PATCH /api/organizations/:organization_id/templates/:template_id` — Update a template as a new draft (auth: organization_template_write)
- `DELETE /api/organizations/:organization_id/templates/:template_id` — Archive a template without deleting versions (auth: organization_template_write)
- `POST /api/organizations/:organization_id/templates/:template_id/publish` — Publish an immutable content-hashed version (auth: organization_template_write)
- `GET /api/organizations/:organization_id/templates/:template_id/versions` — List immutable published template versions (auth: organization)
- `POST /api/organizations/:organization_id/templates/preview` — Compile and safely render a draft preview (auth: organization_template_write)
- `GET /api/organizations/:organization_id/templates/:template_id/export` — Export the latest published HTML, text and MJML (auth: organization)
- `POST /api/organizations/:organization_id/templates/import-html` — Import a conservative HTML subset without active content (auth: organization_template_write)
- `POST /api/messages` — Queue one idempotent transactional delivery for the active organization (auth: organization_messages_send)
- `POST /api/organizations/:organization_id/messages` — Compatibility path for one idempotent transactional delivery (auth: organization_messages_send)
- `GET /api/organizations/:organization_id/campaigns` — List tenant campaigns with an opaque cursor (auth: organization)
- `POST /api/organizations/:organization_id/campaigns` — Create a campaign draft using an active domain, audience and published marketing template (auth: organization_campaign_write)
- `GET /api/organizations/:organization_id/campaigns/:campaign_id` — Read one campaign without recipient data (auth: organization)
- `PATCH /api/organizations/:organization_id/campaigns/:campaign_id` — Edit a draft or pause, resume or cancel a launched campaign (auth: organization_campaign_write)
- `POST /api/organizations/:organization_id/campaigns/:campaign_id/launch` — Freeze eligible recipients and launch or schedule a campaign idempotently (auth: organization_campaign_write)
- `GET /api/organizations/:organization_id/campaigns/:campaign_id/report` — Reconcile campaign deliveries and normalized feedback (auth: organization)
- `GET /api/organizations/:organization_id/messaging-settings` — Read IANA timezone and organization marketing pause state (auth: organization)
- `PATCH /api/organizations/:organization_id/messaging-settings` — Update IANA timezone or manually pause and safely resume marketing (auth: organization_campaign_write)
- `GET /api/organizations/:organization_id/deliverability` — Read delivery, backlog, suppression, reputation and DLQ aggregates without recipient PII (auth: organization)
- `GET /api/organizations/:organization_id/domains/:domain_id/report` — Read delivery and feedback aggregates for one domain (auth: organization)
- `GET /api/organizations/:organization_id/webhooks` — List webhook endpoints without signing secrets (auth: organization)
- `POST /api/organizations/:organization_id/webhooks` — Create an HTTPS webhook and reveal its derived signing secret once (auth: organization_campaign_write)
- `GET /api/organizations/:organization_id/webhooks/:webhook_id` — Read one webhook without its signing secret (auth: organization)
- `DELETE /api/organizations/:organization_id/webhooks/:webhook_id` — Disable a webhook without deleting delivery evidence (auth: organization_campaign_write)
- `GET /api/organizations/:organization_id/webhooks/:webhook_id/deliveries` — List signed webhook attempts and retry state (auth: organization)
- `GET /api/organizations/:organization_id/dead-letters` — Inspect tenant dead letters by opaque resource ID (auth: organization)
- `POST /api/organizations/:organization_id/dead-letters/:record_id/replay` — Replay one nominal campaign or webhook dead letter (auth: organization_campaign_write)

## MCP

POST https://commsharbor.com/mcp using Streamable HTTP and JSON-RPC 2.0.
The MCP uses the same API handlers and does not maintain a second backend.
Send X-Organization-Id with a human session. An API key determines its own organization and rejects a conflicting header.
A domain smoke never accepts a recipient in the request; the controlled destination is a server-side secret.
Domain active state is returned only by the verify operation after live SES and DNS observations.
Contact import confirmation requires Idempotency-Key. Reusing the same key returns the same import and never creates a second Queue message.
Marketing requires explicit consent or a documented relationship. Global, organization and SES tenant suppressions are checked before quota and enqueue.
Contact import and export files expire after seven days; durable audit and row-level result records remain.
Templates use canonical blocks, typed variables and immutable content-hashed published versions. Imported HTML rejects active content, forms and unsafe URLs.
POST /api/messages requires Idempotency-Key. An equivalent replay returns the same delivery; a different payload conflicts before quota or Queue work.
Delivery responses omit recipient and message content. Open and Click remain additive events and counters; they never replace delivery state.
Campaign launch freezes eligible recipients exactly once. Queue messages carry only a campaign batch cursor; D1 outbox state remains authoritative and recoverable.
Webhook signing secrets are revealed once. Deliveries use timestamped HMAC-SHA256, exponential retry and tenant-scoped dead-letter replay.
SES tenant or reputation risk pauses organization marketing. A healthy observation is required before an operator can resume it.
Billing is organization-scoped and versioned. Passes and top-ups never auto-renew; the bootstrap global cap of 1,000 real recipients per month always prevails.
Live checkout is disabled. A purchase request returns a standard x402 Base Sepolia challenge; only the gated homologation path may grant test entitlement during bootstrap.
Tenant exports expire after seven days. Erasure requires the exact organization confirmation, waits seven days and retains only pseudonymous financial and audit evidence.
Operational alerts cover DLQ, backlog, worker and SNS failure, reputation, paused sending, quota and conservative SES/SNS cost capacity without recipient PII.