Developers

API reference

Deliciousmail API 1.0.0 — 170 operations under /api/v1. This page is generated from docs/api/openapi.yaml at build time, and the scopes and responses below are pinned by a behavioral test against the running API.

The Deliciousmail tenant API. Every path below is relative to the /api/v1 base path.

Authentication

Two credential kinds reach these endpoints:

API keys — Authorization: Bearer dm_live_<48 hex>. A key is either workspace-scoped (it acts on its own workspace) or org-level (it names the target workspace with the X-Workspace-Id header; without that header, workspace-scoped endpoints answer 403).
Sessions — the app's cookie sessions, which carry the full scope set (all).

Scopes are fail-closed: an empty, stale or unknown scope list passes no gate. all implies every scope. A workspace outside the caller's org is a plain 404, indistinguishable from a missing resource.

Error envelope

Every failure is { "error": { "code": ..., "message": ... } }. Codes are part of the contract — branch on them: invalid_request, unauthorized, forbidden, not_found, plan_limit, conflict, not_configured, rate_limited, restricted, lane_resting, manual_only, node_unreachable, not_implemented, approval_required, gateway_unavailable, upstream, internal.

Writes, 202 and idempotency

Enqueue-style writes answer 202 with an {id, status, reused} body; poll GET /jobs/{id}. Send-path and fill writes accept an Idempotency-Key header (the body's idempotency_key is the fallback): the same key replays the original result (reused: true) without re-gating.

Not in this document

The operator console (/api/v1/operator/*), the staff console (/api/v1/admin/*), the provider webhook ingest (POST /api/v1/billing/webhook/{gateway}) and the build stamp (GET /api/v1/version) are not part of the customer API surface.

Auth & sessions

Self-serve sign-up and sign-in: magic links, passwords, TOTP, invites, impersonation.

Method	Path	What it does	Key scope	Response
post	/auth/magic-link	Request a magic-link sign-in email	none — public	409
get	/auth/magic-link/verify	Verify a magic link and sign in	none — public	410
post	/auth/password	Set the account password	none — public	401
post	/auth/login	Sign in with email and password	none — public	401
get	/auth/session	Check the current session	none — public	200
post	/auth/logout	Sign out	none — public	204
post	/auth/impersonate/end	End an impersonated session	none — public	401
post	/auth/totp/verify	Complete sign-in with a TOTP code	none — public	401
post	/auth/totp/enrol	Enrol in TOTP two-factor	none — public	401
post	/auth/reset	Request a password-reset email	none — public	409
post	/auth/invites/accept	Accept an invite token	none — public	404

Public

Unauthenticated endpoints: checkout, leads, the Identity Pixel beacon and the email spam test.

Method	Path	What it does	Key scope	Response
get	/checkout-config	List sellable checkout gateways	none — public	200
post	/leads	Save a checkout lead	none — public	201
post	/checkout/session	Create a checkout session	none — public	404
get	/checkout/session/{ref}	Poll a checkout session	none — public	404
post	/pixel/{key}	Identity Pixel beacon	none — public	204
get	/spam-test/limit	Spam test limit	none — public	200
post	/spam-test/tests	Mint a one-time test address	none — public	503
get	/spam-test/reports/{id}	Spam test share-link report	none — public	404

Account & workspaces

Plan and usage, first-run setup and workspace management.

Method	Path	What it does	Key scope	Response
get	/account	Read plan and usage	any API key	200
post	/account/first-run	Finish first-run setup	all	200
get	/workspaces	List the org's workspaces	any API key	200
post	/workspaces	Create a workspace	all	201
patch	/workspaces/{workspaceId}	Rename a workspace	all	200

API keys

Minting, listing and revoking API keys — 'all' only: minting with a narrow key would be escalation.

Method	Path	What it does	Key scope	Response
get	/workspaces/{workspaceId}/api_keys	List API keys	all	200
post	/workspaces/{workspaceId}/api_keys	Mint an API key	all	201
delete	/workspaces/{workspaceId}/api_keys/{keyId}	Revoke an API key	all	204

Invites

Teammate invites.

Method	Path	What it does	Key scope	Response
get	/workspaces/{workspaceId}/invites	List invites	all	200
post	/workspaces/{workspaceId}/invites	Invite a teammate	all	201

Jobs

The job queue: enqueue (per-type scopes) and poll.

Method	Path	What it does	Key scope	Response
get	/jobs	List jobs	jobs:read	200
post	/jobs	Enqueue a job	domains:writemailboxes:writecampaigns:writeall	202
get	/jobs/{id}	Poll a job	jobs:read	200

Domains

Sending domains and DKIM.

Method	Path	What it does	Key scope	Response
get	/domains	List domains	domains:write	200
get	/domains/{domainId}	Read a domain	domains:write	200
post	/domains/{domainId}/rotate_dkim	Rotate DKIM keys	domains:write	202

Mailboxes

Mailbox inventory and the credential reveal.

Method	Path	What it does	Key scope	Response
get	/mailboxes	List mailboxes	mailboxes:write	200
get	/mailboxes/{mailboxId}	Read a mailbox	mailboxes:write	200
get	/mailboxes/{mailboxId}/credentials	Reveal mailbox credentials	all	200

Sends

Sending: the send primitive and thread replies.

Method	Path	What it does	Key scope	Response
post	/mailboxes/{mailboxId}/send	Send an email from a mailbox	mailboxes:write	202
post	/conversations/{threadId}/replies	Reply in a conversation	mailboxes:write	202

Warming

Warming controls and own-server mailboxes.

Method	Path	What it does	Key scope	Response
post	/mailboxes/warming	Set warming state in bulk	mailboxes:write	202
get	/warming/own-server	List own-server mailboxes	mailboxes:write	200
post	/warming/own-server	Connect own-server mailboxes	mailboxes:write	202
post	/warming/own-server/{id}/start	Start warming an own-server mailbox	mailboxes:write	200
post	/warming/own-server/{id}/pause	Pause an own-server mailbox	mailboxes:write	200
post	/warming/own-server/{id}/resume	Resume an own-server mailbox	mailboxes:write	200
delete	/warming/own-server/{id}	Remove an own-server mailbox	mailboxes:write	204

Inbox

The Unibox: conversations, threads and their state.

Method	Path	What it does	Key scope	Response
get	/conversations	List conversations	inbox:read	200
get	/conversations/{threadId}	Read a conversation	inbox:read	200
patch	/conversations/{threadId}	Update conversation state	inbox:read	200

Suppressions

The suppression ledger.

Method	Path	What it does	Key scope	Response
get	/suppressions	List suppressions	inbox:read	200
post	/suppressions	Add suppressions	mailboxes:write	201
delete	/suppressions/{email}	Delete a manual suppression	mailboxes:write	204

Webhooks

Outbound webhook endpoints and their delivery health.

Method	Path	What it does	Key scope	Response
get	/webhooks	List webhook endpoints	webhooks:write	200
post	/webhooks	Create a webhook endpoint	webhooks:write	201
patch	/webhooks/{endpointId}	Update a webhook endpoint	webhooks:write	200
delete	/webhooks/{endpointId}	Delete a webhook endpoint	webhooks:write	204
get	/webhooks/{endpointId}/deliveries	List webhook deliveries	webhooks:write	200

Prospects

Audience building, lists, imports and the Identity Pixel key.

Method	Path	What it does	Key scope	Response
get	/prospects/search	Preview a prospect search	prospects:write	200
post	/prospects/build	Build a prospect audience	prospects:write	201
get	/prospects/lists	List prospect lists	prospects:write	200
post	/prospects/lists	Create a prospect list	prospects:write	201
get	/prospects/lists/{listId}	Read a prospect list	prospects:write	200
patch	/prospects/lists/{listId}	Rename a prospect list	prospects:write	200
delete	/prospects/lists/{listId}	Delete a prospect list	prospects:write	204
post	/prospects/import	Import prospects	prospects:write	201
get	/prospects/lists/{listId}/export.csv	Export a list's members as CSV	prospects:write	200
get	/prospects/lists/{listId}/fill-precheck	Precheck an audience fill	prospects:write	200
get	/prospects/pixel	Read the Identity Pixel key and snippet	prospects:write	200

Campaigns

Campaign drafts, the live state machine and the kill switch.

Method	Path	What it does	Key scope	Response
get	/campaigns	List campaigns	campaigns:write	200
post	/campaigns	Create a campaign draft	campaigns:write	201
get	/campaigns/kill-switch	Read the sending kill switch	campaigns:write	200
post	/campaigns/kill-switch	Set the sending kill switch	campaigns:write	200
get	/campaigns/overview	Campaign overview totals	campaigns:write	200
get	/campaigns/{campaignId}	Read a campaign	campaigns:write	200
patch	/campaigns/{campaignId}	Edit a draft campaign	campaigns:write	200
delete	/campaigns/{campaignId}	Archive a campaign	campaigns:write	204
get	/campaigns/{campaignId}/progress	Read campaign progress	campaigns:write	200
put	/campaigns/{campaignId}/steps	Replace campaign steps	campaigns:write	200
post	/campaigns/{campaignId}/mailboxes	Assign the sending pool	campaigns:write	200
delete	/campaigns/{campaignId}/mailboxes/{mailboxId}	Unassign a sending mailbox	campaigns:write	204
post	/campaigns/{campaignId}/fill	Fill the audience from a list	campaigns:write	202
post	/campaigns/{campaignId}/rehearsal	Send a rehearsal	campaigns:write	202
post	/campaigns/{campaignId}/launch	Launch a campaign	campaigns:write	200
post	/campaigns/{campaignId}/pause	Pause a live campaign	campaigns:write	200
post	/campaigns/{campaignId}/resume	Resume a paused campaign	campaigns:write	200
post	/campaigns/{campaignId}/leave-dry-run	Leave dry-run mode	campaigns:write	200
post	/campaigns/{campaignId}/steps/{stepId}/winner	Declare the A/B winner	campaigns:write	200
delete	/campaigns/{campaignId}/steps/{stepId}/winner	Reopen a decided step	campaigns:write	200

CRM

Leads, lists, opportunities, tasks and pipeline settings.

Method	Path	What it does	Key scope	Response
get	/crm/settings	Read CRM settings	crm:write	200
post	/crm/settings/statuses	Create a lead status	crm:write	201
patch	/crm/settings/statuses/{id}	Edit a lead status	crm:write	200
delete	/crm/settings/statuses/{id}	Delete a lead status	crm:write	200
post	/crm/settings/stages	Create an opportunity stage	crm:write	201
patch	/crm/settings/stages/{id}	Edit an opportunity stage	crm:write	200
post	/crm/settings/custom_fields	Add a custom lead field	crm:write	201
delete	/crm/settings/custom_fields/{id}	Remove a custom lead field	crm:write	200
get	/crm/leads	List leads	crm:write	200
post	/crm/leads	Create a lead	crm:write	201
get	/crm/leads/{id}	Read a lead	crm:write	200
patch	/crm/leads/{id}	Edit a lead	crm:write	200
delete	/crm/leads/{id}	Delete a lead	crm:write	200
post	/crm/leads/import	Import leads from CSV	crm:write	201
get	/crm/lists	List CRM lists	crm:write	200
post	/crm/lists	Create a CRM list	crm:write	201
get	/crm/lists/{id}	Read a CRM list	crm:write	200
patch	/crm/lists/{id}	Edit a CRM list	crm:write	200
delete	/crm/lists/{id}	Delete a CRM list	crm:write	200
get	/crm/opportunities	List opportunities	crm:write	200
post	/crm/opportunities	Create an opportunity	crm:write	201
get	/crm/opportunities/{id}	Read an opportunity	crm:write	200
patch	/crm/opportunities/{id}	Edit an opportunity	crm:write	200
get	/crm/tasks	List tasks	crm:write	200
post	/crm/tasks	Create a task	crm:write	201
patch	/crm/tasks/{id}	Edit a task	crm:write	200
delete	/crm/tasks/{id}	Delete a task	crm:write	200
get	/crm/home	CRM home totals	crm:write	200
get	/crm/reports	Pipeline reports	crm:write	200

Basil

The Basil assistant: conversations, approvals, actions, memory, artifacts, tasks.

Method	Path	What it does	Key scope	Response
get	/basil/state	Read the Basil model state	basil:write	200
get	/basil/conversations	List Basil conversations	basil:write	200
post	/basil/conversations	Open a Basil conversation	basil:write	201
get	/basil/conversations/{id}	Read a Basil conversation	basil:write	200
post	/basil/conversations/{id}/messages	Continue a Basil conversation	basil:write	201
get	/basil/approvals	List approval cards	basil:write	200
post	/basil/approvals	Create an approval card	basil:write	201
post	/basil/approvals/{id}/approve	Approve an approval card	basil:write	200
post	/basil/approvals/{id}/skip	Skip an approval card	basil:write	200
post	/basil/actions/{action}	Run a gated Basil action	basil:write	200
get	/basil/memory	List memory entries	basil:write	200
post	/basil/memory	Add a memory entry	basil:write	201
patch	/basil/memory/{id}	Edit a memory entry	basil:write	200
delete	/basil/memory/{id}	Forget a memory entry	basil:write	204
get	/basil/memory/business	Read the business profile	basil:write	200
put	/basil/memory/business	Upsert the business profile	basil:write	200
get	/basil/memory/profiles	List persona profiles	basil:write	200
post	/basil/memory/profiles	Add a persona profile	basil:write	201
delete	/basil/memory/profiles/{id}	Remove a persona profile	basil:write	204
get	/basil/memory/guidance	List guidance rules	basil:write	200
post	/basil/memory/guidance	Add a guidance rule	basil:write	201
delete	/basil/memory/guidance/{id}	Remove a guidance rule	basil:write	204
get	/basil/artifacts	List artifacts	basil:write	200
post	/basil/artifacts	Save an artifact	basil:write	201
get	/basil/tasks	List delegated tasks	basil:write	200
post	/basil/tasks	Delegate a task	basil:write	201
post	/basil/tasks/{id}/pause	Pause a delegated task	basil:write	200
post	/basil/tasks/{id}/resume	Resume a delegated task	basil:write	200

Dedicated IPs

Dedicated-IP requests — requests, never provisioning.

Method	Path	What it does	Key scope	Response
get	/ip-request	Read the dedicated-IP request	domains:write	200
post	/ip-request	Request a dedicated IP	domains:write	201
patch	/ip-request	Update the dedicated-IP request	domains:write	200
delete	/ip-request	Release the dedicated-IP request	domains:write	204

Exports

Bulk CSV exports and the export ledger.

Method	Path	What it does	Key scope	Response
get	/exports/{entity}.csv	Export a CSV	prospects:writecampaigns:writeinbox:read	200
get	/exports/history	Read export history	any API key	200

Notifications

The bell: feed, read state, preferences.

Method	Path	What it does	Key scope	Response
get	/notifications	Read the notification feed	any API key	200
post	/notifications/read_all	Mark the whole feed read	any API key	200
post	/notifications/{id}/read	Mark one notification read	any API key	200
get	/notifications/prefs	Read notification preferences	any API key	200
put	/notifications/prefs	Write notification preferences	any API key	200

Offer

Your offer and offer groups.

Method	Path	What it does	Key scope	Response
get	/offer	Read your offer	any API key	200
put	/offer	Write your offer	all	200
post	/offer/groups	Create an offer group	all	201
patch	/offer/groups/{groupId}	Edit an offer group	all	200
delete	/offer/groups/{groupId}	Delete an offer group	all	204

Postmaster

Google Postmaster connection and sync.

Method	Path	What it does	Key scope	Response
get	/postmaster/status	Read the Postmaster connection state	any API key	200
post	/postmaster/connect	Connect Google Postmaster	all	409
delete	/postmaster/disconnect	Disconnect Google Postmaster	all	204
post	/postmaster/sync	Sync Google Postmaster now	all	409

Affiliate

The referral program: overview, ledger and payout details.

Method	Path	What it does	Key scope	Response
get	/affiliate	Read the affiliate overview	affiliate:write	200
put	/affiliate/payout-details	Save payout details	affiliate:write	200

Billing

Subscription management doors the provider owns.

Method	Path	What it does	Key scope	Response
post	/billing/payment-method-update	Start a payment-method update	all	409
post	/billing/plan-change	Preview or confirm a plan switch	all	409