Your DMARC data, in your tools. One key, every endpoint.

Pull domains, reports, senders and issues into your scripts, stage a DNS fix, and get a signed post when something changes. Send the key as a bearer token to https://api.trustyourinbox.com/v1.

Get an API key OpenAPI spec Postman collection

Start with one call. The key does the rest.

Mint a key in the app under Settings, Integrations, API keys. It carries a read scope and, if you choose, a write scope, and a write only works while the person who minted it can still edit. Call it from a server; there is no browser CORS.

Base URL: https://api.trustyourinbox.com/v1
Auth: Authorization: Bearer tyi_api_…Header only, never a cookie. Revoking the key, or the role behind it, takes effect on the next call.
Plan: Pro and up
Rate limit: 120 requests per key per 60 seconds Over the limit you get a 429 with Retry-After in seconds. Staging DNS fixes is capped separately at five per 24 hours.
Format: JSON in, JSON out, Cache-Control: no-store
Idempotency: Send Idempotency-Key on a creating write A retry with the same key replays the first answer. The same key with a different body answers idempotency_key_reused. Keys are kept for 24 hours.
Windows: range in days, default 30, up to 90Reports take limit instead: default 50, up to 200.
Versioning: /v1 is the stable contract

One call, one domain. kanbello.xyz, as the API sees it.

List the domains in the workspace. Each one comes back with its verification status, whether it sends mail or is monitored only, and the DNS provider we detected.

GET /v1/domainsRequest

curl https://api.trustyourinbox.com/v1/domains \
  -H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"

200 V1DomainsResponseResponse

{
  "domains": [
    {
      "name": "kanbello.xyz",
      "status": "verified",
      "purpose": "sending",
      "dnsProvider": "cloudflare",
      "createdAt": "2026-10-14T09:12:40.000Z"
    }
  ]
}

Errors you can switch on. One envelope, stable codes.

Every error is { "error", "message" }. Branch on error; the message is for a person. A 429 also carries retryAfterSec.

unauthorizedProvide a valid API key as a bearer token.
forbiddenThis API key does not have permission for that.
plan_requiredAPI access requires the Pro plan or higher.
not_foundNot found.
invalid_requestThe request was invalid.
rate_limitedToo many requests. Slow down and retry after the delay.
internalSomething went wrong on our end.
conflictThe request conflicts with the current state.
plan_limitThis action would exceed your plan's limit.
aup_blockThis domain does not meet our acceptable use policy.
idempotency_in_progressA request with this Idempotency-Key is still being processed. Retry shortly.
idempotency_key_reusedThis Idempotency-Key was already used for a different request.
workspace_requiredThis endpoint is workspace-scoped. Org-scoped keys must target a client workspace with ?workspace=<id>.
org_key_requiredThis endpoint is organization-scoped. Authenticate with an organization API key (minted in the MSP console).
workspace_archivedThis workspace is archived, so nothing can change.

Every endpoint. All 56, grouped by what they touch.

Domains3
Authentication & deliverability7
Reports2
Issues4
DNS fixes3
Delivery Diagnosis3
Mandate Monitor2
Lookalike Domains2
Sender Authorization Review1
Senders4
Webhooks4
Workspace1
MSP20

Domains3 endpoints

GET/v1/domainsList the domains in the workspace

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200The workspace's domains V1DomainsResponse
- domainsobject[]
  - namestring
  - status"pending" | "verified" | "paused" | "deleted"
  - purpose"sending" | "monitor_only"
  - dnsProviderstring | null
  - createdAtstring (date-time)
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
429Rate limited

POST/v1/domainsAdd a domain to the workspace

Write key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Request body

namestringThe domain to add, e.g. acme.com
purpose"sending" | "monitor_only" · optionalDefaults to sending.

Responses

201Domain added (pending verification); body carries the TXT to publish V1AddDomainResponse
- domainstring
- statusstring
- purpose"sending" | "monitor_only"
- verificationobject
  - recordTypestring
  - recordNamestring
  - recordValuestring
- dnsProviderstring | null
400invalid_request (missing or invalid name)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
409conflict (duplicate) or plan_limit
422aup_block (domain fails the acceptable use policy)
429Rate limited

POST/v1/domains/{domain}/recheckRe-detect the domain's DNS provider now

Write key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Re-checked (body reports the detected provider + whether it changed) V1RecheckResponse
- domainstring
- detectedboolean
- providerstring
- providerNamestring · optionalPresent only when detected is true.
- changedboolean
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
404Domain not found in the caller's workspace
429Rate limited

Authentication & deliverability7 endpoints

GET/v1/domains/{domain}/complianceThe four mandate compliance tiles for one domain

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Compliance tiles V1ComplianceResponse
- domainstring
- complianceobject
  - googleV1ComplianceTileOne mandate tile (Google/Yahoo, Microsoft, BIMI, or TLS) for a domain.
  - microsoftV1ComplianceTileOne mandate tile (Google/Yahoo, Microsoft, BIMI, or TLS) for a domain.
  - bimiV1ComplianceTileOne mandate tile (Google/Yahoo, Microsoft, BIMI, or TLS) for a domain.
  - tlsV1ComplianceTileOne mandate tile (Google/Yahoo, Microsoft, BIMI, or TLS) for a domain.
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

GET/v1/domains/{domain}/enforcement-simulationEnforcement Preview: what a stricter DMARC policy would have done

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Enforcement simulation V1EnforcementSimulationResponse
- domainstring
- windowDaysinteger
- purpose"sending" | "monitor_only"
- currentobject
  - hasRecordboolean
  - policystring | null
  - spstring | null
  - pctinteger | null
  - testModeboolean
- fullyEnforcedboolean
- alignmentPctinteger | nullAdjusted for unidentified sources, as the dashboard shows it: on a domain at enforcement, unidentified mail that receivers quarantined or rejected is left out. Never raw aligned over total.
- totalVolumeinteger
- nextStepobject
  - stepstring
  - reasonstring
  - fixTypestring | null
  - daysRemaininginteger | null
- scenariosV1EnforcementScenario[]One counterfactual per ladder scenario (the recommended next step first, then the p=reject end state). Empty at p=reject.
  - kind"policy_step" | "bump_pct" | "disable_test_mode"
  - targetPolicy"quarantine" | "reject"
  - effectiveSubdomainPolicy"none" | "quarantine" | "reject"
  - verdict"clear_to_flip" | "fix_senders_first" | "investigate" | "wait" | "already_enforced" | "no_data"
  - summarystring
  - totalsobject
  - newlyAffectedBySegmentV1EnforcementSegments
  - alreadyEnforcedBySegmentV1EnforcementSegments
  - forwardingWithOverrideinteger
  - senderRiskobject[]
  - senderRiskDroppedinteger
  - subdomainsobject[]
  - subdomainsDroppedinteger
  - overridesobject[]
  - dailySeriesobject[]Messages the target policy would newly ask receivers to act on, per day, in the same three groups as newlyAffectedBySegment.
- watchobject | nullThe domain's ACTIVE post-flip watch (14 days after a detected policy strengthening), or null. The watch reads receiver reports and alerts on regression with a one-click rollback; it never writes DNS on its own.
  - toPolicystring
  - changeDetectedAtstring
  - watchUntilstring
  - regressionDetectedAtstring | null
  - regressionSenderNamesstring[]
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

GET/v1/domains/{domain}/sendersSender breakdown, with alignment adjusted for unidentified sources

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
rangequery · integer · optionalWindow in days (clamped to 90, default 30)

Responses

200Sender breakdown V1SendersResponse
- domainstring
- rangeDaysinteger
- totalVolumeinteger
- alignmentPctinteger | nullAdjusted for unidentified sources, as the dashboard shows it: on a domain at enforcement, unidentified mail that receivers quarantined or rejected is left out. Never raw aligned over total.
- blockedSpoofinteger
- knownVolumeinteger · optionalPresent only when totalVolume > 0.
- unknownVolumeinteger · optionalPresent only when totalVolume > 0.
- distinctSendersinteger · optionalPresent only when totalVolume > 0.
- sendersV1SenderRow[]
  - ipstring
  - networkstring | nullThe organization behind the IP's network (its ASN).
  - volumeinteger
  - alignedPctinteger
  - knownboolean
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

GET/v1/domains/{domain}/protocolRecorded authentication status and evidence for a domain

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Authentication records V1ProtocolResponse
- domainstring
- dmarcobject | null
  - policystring
  - pctinteger | null
  - testMode"y" | "n" | nullDMARCbis test flag. With t=y, reject requests quarantine and quarantine requests no enforcement; legacy receivers may ignore the flag.
  - npstring | nullDMARCbis non-existent-subdomain policy.
  - reportsToUsboolean | null
  - multiRecordboolean | null
- spfobject | null
  - lookupCountinteger | nullLast recorded DNS lookup count, not proof that recursive SPF evaluation completed.
  - allQualifierstring | nullThe qualifier on the final all mechanism (~, -, +, ?).
  - multiRecordboolean | null
- dkimSelectorsintegerCount of found selector records, including records without a usable key measurement.
- dkimMinKeyBitsinteger | nullSmallest valid measured retained key size, or null when none can be measured. Numeric lengths across algorithms do not rank cryptographic strength.
- mtaStsstring | nullUsable active MTA-STS mode (testing or enforce). Null can mean inactive, unavailable, invalid or absent; consult observations.
- dkimMeasuredSelectorsinteger · optionalFound selector records with a valid measured key, excluding revoked and unknown keys.
- observationsobject · optional
  - dmarcobject
  - spfobject
  - mtaStsobject
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

GET/v1/domains/{domain}/dkim-rotationsDKIM key rotation state for a domain

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200DKIM rotation state V1DkimRotationsResponse
- domainstring
- activeobject[]Non-terminal rotations, oldest first (the wizard's render order).
  - idstring (uuid)
  - oldSelectorstring
  - newSelectorstring
  - vendorstring | nullVendor label of the old selector at rotation start; null = long-tail self-hosted.
  - custody"self_hosted" | "esp"
  - state"planned" | "new_key_published" | "new_key_signing" | "old_key_retired"
  - createdAtstring (date-time)
  - newKeyPublishedAtstring (date-time) | null
  - newKeySigningAtstring (date-time) | null
  - oldKeyRetiredAtstring (date-time) | null
  - ruaEvidenceobject | nullRUA-observed signing evidence for the new selector; populated only in state new_key_published (reports lag 1-2 days).
- lastCompletedobject | null
  - oldSelectorstring
  - newSelectorstring
  - completedAtstring (date-time) | null
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

GET/v1/domains/{domain}/subdomainsSubdomains sending as a domain, bucketed

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
rangequery · integer · optionalWindow in whole UTC days, any value from 1 to 90 (larger values are clamped to 90; default 30). The dashboard offers 7, 30 and 90; any other value here counts the same day-snapped way.

Responses

200Subdomain breakdown V1SubdomainsResponse
- domainstring
- rangeDaysinteger
- subdomainCountintegerDistinct subdomains in the returned rows; the full observed count is coverage.matchedSubdomainCount when supplied.
- truncatedboolean · optionalWhen supplied, true if more matching reported subdomains exist than the returned rows.
- coverageobject · optionalWhen supplied, distinguishes the full observed population in the selected period from the highest-volume returned subset. Volumes are reported message counts; bucket counts describe returned rows.
  - matchedSubdomainCountinteger · optionalAll matching reported subdomains before the row limit, when supplied.
  - returnedSubdomainCountinteger · optionalNumber of returned subdomains, when supplied.
  - matchedVolumeinteger · optionalReported message count across all matching subdomains, when supplied.
  - returnedVolumeinteger · optionalReported message count across returned subdomains, when supplied.
  - rowLimitinteger · optionalMaximum number of returned subdomains, when supplied.
- knownCountinteger · optionalPresent only when subdomainCount > 0.
- worthALookCountinteger · optionalPresent only when subdomainCount > 0.
- nonexistentCountinteger · optionalPresent only when subdomainCount > 0.
- unrecognizedCountinteger · optionalPresent only when subdomainCount > 0.
- totalVolumeinteger · optionalPresent only when subdomainCount > 0.
- nxdomainPolicystring | null · optionalWhat a non-existent subdomain resolves to (np ?? sp ?? p). Present only when subdomainCount > 0.
- extendedSubdomainCountintegerDistinct subdomains over a wider 90-day lookback (subdomain abuse is bursty).
- subdomainsV1SubdomainRow[]
  - subdomainstring
  - labelstringThe relative label (e.g. "marketing" for marketing.acme.com).
  - status"Known" | "Review" | "Not in DNS"
  - bucket"known" | "worth_a_look" | "nonexistent"
  - volumeinteger
  - alignmentPctinteger | nullAdjusted for unidentified sources, as the dashboard shows it. Null when none of the subdomain's own mail can be measured.
  - spoofVolumeinteger
  - blockedSpoofinteger
  - distinctSendersinteger
  - lastSeenstring (date-time) | null
  - inDnsboolean | nulltrue = the subdomain resolves; false = NXDOMAIN; null = inconclusive.
  - verdictstring
  - whatItMeansstring
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

GET/v1/domains/{domain}/spoof-activityUnidentified failures acted on and top sources over a window

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
rangequery · integer · optionalWindow in days (clamped to 90, default 30)

Responses

200Spoof activity V1SpoofActivityResponse
- domainstring
- rangeDaysinteger
- blockedSpoofinteger
- blockedSpoofPriorinteger
- topSourcesV1SpoofSource[]
  - ipstring
  - attemptsinteger
  - networkstring | null
  - countrystring | null
  - dispositionstringThe outcome from this source's largest individual report row, retained for compatibility. It is not the outcome of most messages after aggregation; use quarantined and rejected for outcome totals.
  - quarantinedintegerMessages from this source receivers reported quarantining in the selected window.
  - rejectedintegerMessages from this source receivers reported rejecting in the selected window.
- dailyobject[]
  - daystring (date)UTC report day, oldest first.
  - blockedintegerMessages receivers reported quarantining or rejecting from unidentified, unaligned sources.
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

Reports2 endpoints

GET/v1/domains/{domain}/reportsRecent aggregate (RUA) reports for one domain

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
limitquery · integer · optionalMax reports (clamped to 200, default 50)

Responses

200Recent reports V1DomainReportsResponse
- domainstring
- reportsV1ReportRow[]
  - idstring (uuid)
  - reporterstringThe receiver's name, derived from the authenticated sender of the report (never from the report body).
  - reporterDomainstring | nullThe authenticated reporter domain; null on reports ingested before sender authentication existed.
  - reportingOrgstringThe organization name the report body claims for itself. A claim, not an identity.
  - rangeStartstring (date-time)
  - rangeEndstring (date-time)
  - volumeinteger
  - passinginteger
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

GET/v1/reports/{id}Drill into one aggregate (RUA) report

Read key · Bearer

Parameters

idpath · string · requiredaggregate-report id (from .../reports; workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Report detail V1ReportDetailResponse
- reportIdstring (uuid)
- externalReportIdstring
- reporterstringThe receiver's name, derived from the authenticated sender of the report (never from the report body).
- reporterDomainstring | nullThe authenticated reporter domain; null on reports ingested before sender authentication existed.
- reportingOrgstringThe organization name the report body claims for itself. A claim, not an identity.
- domainstring
- rangeStartstring (date-time)
- rangeEndstring (date-time)
- outcomeV1ReportOutcome
  - alignedinteger
  - dkimOnlyinteger
  - spfOnlyinteger
  - failedinteger
  - totalinteger
  - alignmentPctinteger | nullRaw aligned over total, the report's own composition as received.
  - spoofVolumeinteger
  - adjustedPctinteger | nullAlignment after exclusions; null when no denominator remains. Exclusion does not establish authorization.
  - recordCountinteger
- failureGroupsV1FailureGroup[]
  - senderstring
  - vendorNamestring | null
  - ipCountinteger
  - failedVolumeinteger
  - class"forwarding" | "esp_misconfig" | "spoof_likely" | "unknown"
  - diagnosisstring
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Report not found in the caller's workspace
429Rate limited

Issues4 endpoints

GET/v1/issuesOpen issues across the workspace

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Open issues V1IssuesResponse
- issuesV1Issue[]
  - keystring
  - typestringThe anomaly type id (the issue's stable machine key).
  - severity"opportunity" | "warn" | "crit"
  - headlinestring
  - whystring
  - domainstring
  - firstSeenAtstring (date-time)
  - impactstring | null
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
429Rate limited

GET/v1/domains/{domain}/issuesOpen issues for one domain

Read key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Open issues for the domain V1DomainIssuesResponse
- domainstring
- issuesV1Issue[]
  - keystring
  - typestringThe anomaly type id (the issue's stable machine key).
  - severity"opportunity" | "warn" | "crit"
  - headlinestring
  - whystring
  - domainstring
  - firstSeenAtstring (date-time)
  - impactstring | null
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the caller's workspace
429Rate limited

POST/v1/domains/{domain}/issues/{type}/dismissDismiss or snooze an open issue

Write key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
typepath · string · requiredthe issue type to hide, e.g. `tls_rpt_missing`
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Request body (optional)

permanentboolean · optionaltrue = dismiss indefinitely; false (default) = snooze 7 days.

Responses

200Issue dismissed or snoozed V1DismissIssueResponse
- domainstring
- typestring
- mode"dismiss" | "snooze"
- dismissedtrue
400invalid_request (unknown issue type)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
404Domain not found in the caller's workspace
429Rate limited

POST/v1/domains/{domain}/issues/{type}/restoreRestore a dismissed or snoozed issue

Write key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
typepath · string · requiredthe issue (anomaly) type to restore
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Issue restored V1RestoreIssueResponse
- domainstring
- typestring
- restoredtrue
400invalid_request (unknown issue type)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
404Domain not found in the caller's workspace
429Rate limited

DNS fixes3 endpoints

POST/v1/domains/{domain}/dns-fixesStage a one-click DNS fix for an issue

Write key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Request body

typestringA one-click-fixable issue type, e.g. `dmarc_np_missing`.

Responses

200Nothing to stage (the fix is already in place)
201Fix staged; body carries the change id, record, and apply time V1StageFixResponse
- domainstring
- typestring
- stagedtrue
- changeIdstring (uuid)
- recordNamestring
- newValuestring
- applyAtstring (date-time)
- warningstring · optional
- or
- domainstring
- typestring
- stagedfalse
- alreadyAppliedtrue
400invalid_request (not a one-click-fixable type, or invalid input)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
404Domain not found in the caller's workspace
409conflict (no provider connected, already pending, etc.)
429Rate limited (per key, or the staging cap of 5 changes per 24 hours)

GET/v1/changesStaged and recently applied DNS changes for the workspace

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Staged and recently applied changes V1ChangesResponse
- changesV1Change[]
  - idstring (uuid)
  - domainstring | null
  - fixTypestring
  - recordNamestring
  - recordTypestring
  - statusstringstaged, applied, canceled, etc.
  - stagedAtstring (date-time)
  - applyAtstring (date-time) | null
  - undoablebooleanTrue for an applied change to an existing record. It can be undone in the app at any time, as long as the record still holds the value we wrote. A change that created a record, or one that is itself an undo, is never undoable (run the fix again instead).
  - undoUntilnullAlways null. An undo has no deadline; read undoable instead.
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
429Rate limited

DELETE/v1/changes/{id}Cancel a staged DNS change

Write key · Bearer

Parameters

idpath · string · requiredthe staged change id (from GET /v1/changes)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Change canceled V1CancelChangeResponse
- canceledtrue
- changeV1Change | nullA staged or recently-applied one-click DNS change. The email cancel secret is never exposed.
  - idstring (uuid)
  - domainstring | null
  - fixTypestring
  - recordNamestring
  - recordTypestring
  - statusstringstaged, applied, canceled, etc.
  - stagedAtstring (date-time)
  - applyAtstring (date-time) | null
  - undoablebooleanTrue for an applied change to an existing record. It can be undone in the app at any time, as long as the record still holds the value we wrote. A change that created a record, or one that is itself an undo, is never undoable (run the fix again instead).
  - undoUntilnullAlways null. An undo has no deadline; read undoable instead.
400invalid_request (malformed id)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
404No staged change with that id in the caller's workspace
409conflict (the change is no longer staged)
429Rate limited

Delivery Diagnosis3 endpoints

GET/v1/diagnosisList Delivery Diagnosis cases

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
limitquery · integer · optional

Responses

200Recent diagnosis cases V1DiagnosisListResponse
- casesV1DiagnosisCaseSummary[]
  - idstring
  - createdAtstring
  - status"received" | "analyzing" | "diagnosed" | "needs_headers" | "refused" | "failed"
  - source"email" | "paste"
  - subjectstring | null
  - domainstring | null
  - causestring | null
  - causeLabelstring | null
  - confidencestring | null
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
429Rate limited

POST/v1/diagnosisDiagnose pasted message headers

Write key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Request body

headersstringThe original message's full header block (max 64 KiB).

Responses

201The diagnosed case V1DiagnosisCaseDetail
- idstring
- createdAtstring
- status"received" | "analyzing" | "diagnosed" | "needs_headers" | "refused" | "failed"
- source"email" | "paste"
- artifactKindstring | null
- domainstring | null
- subjectstring | null
- forwarderEmailstring | null
- replySentAtstring | null
- refusalReasonstring | null
- verdictV1DiagnosisVerdict | null
  - cause"authentication" | "reputation" | "forwarding" | "transport" | "recipient_issue" | "policy_block" | "unclear"
  - confidencestring | null
  - causeLabelstring | null
  - narrativestring | null
  - providersAffectedstring[]
  - ruledOutobject[]
  - actionsobject[]
  - bounceStatusstring | null
  - bounceReplyLinestring | null
- evidenceV1DiagnosisEvidenceRow[]
  - sourcestring
  - statestring
  - stateLabelstring
  - findingstring
- fixobject
  - changeIdstring | null
  - changeStatusstring | null
- watchUntilstring | null
- recoveryConfirmedAtstring | null
400invalid_request (missing or oversized headers)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer) or plan_required
409conflict (duplicate submission) or plan_limit (monthly quota)
422invalid_request (`needs_headers`, or `foreign_domain` when the headers are not for a verified domain in the workspace; the case is still saved and its id is in the body)
429Rate limited (incl. the per-workspace daily cap)

GET/v1/diagnosis/{id}One Delivery Diagnosis case in full

Read key · Bearer

Parameters

idpath · string · requiredthe case id (from GET /v1/diagnosis)
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200The case detail V1DiagnosisCaseDetail
- idstring
- createdAtstring
- status"received" | "analyzing" | "diagnosed" | "needs_headers" | "refused" | "failed"
- source"email" | "paste"
- artifactKindstring | null
- domainstring | null
- subjectstring | null
- forwarderEmailstring | null
- replySentAtstring | null
- refusalReasonstring | null
- verdictV1DiagnosisVerdict | null
  - cause"authentication" | "reputation" | "forwarding" | "transport" | "recipient_issue" | "policy_block" | "unclear"
  - confidencestring | null
  - causeLabelstring | null
  - narrativestring | null
  - providersAffectedstring[]
  - ruledOutobject[]
  - actionsobject[]
  - bounceStatusstring | null
  - bounceReplyLinestring | null
- evidenceV1DiagnosisEvidenceRow[]
  - sourcestring
  - statestring
  - stateLabelstring
  - findingstring
- fixobject
  - changeIdstring | null
  - changeStatusstring | null
- watchUntilstring | null
- recoveryConfirmedAtstring | null
400invalid_request (malformed id)
401Missing or invalid API key
404No case with that id in the caller's workspace
429Rate limited

Mandate Monitor2 endpoints

GET/v1/domains/{domain}/mandateMandate Monitor status for a domain

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
domainpath · string · required

Responses

200Mandate Monitor status V1MandateStatusResponse
- domainstring
- hasCapabilityboolean
- probeMintedboolean
- gradedCountinteger
- steadyboolean
- checksV1MandateCheck[]
  - idstring
  - labelstring
  - sourcestring
  - passedinteger
  - applicableinteger
  - worststring | null
- streamsV1MandateStream[]
  - idstring
  - fromAddressstring
  - dkimDomainstring
  - dkimSelectorstring
  - classificationstring
  - classificationSourcestring
  - messageCountinteger
  - worstVerdictstring | null
  - lastSeenAtstring
- microsoft515Count30dinteger
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the workspace (or the feature is switched off)
429Rate limited

GET/v1/mandate/messagesList probe-graded messages

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
domainquery · string · optional
limitquery · integer · optional

Responses

200Graded messages V1MandateMessagesResponse
- messagesV1MandateMessage[]
  - idstring
  - receivedAtstring
  - domainstring | null
  - subjectstring | null
  - fromAddressstring
  - verdictstring
  - rulebookVersioninteger
  - checksobject[]
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
429Rate limited

Lookalike Domains2 endpoints

GET/v1/domains/{domain}/lookalikesLookalike domains found for a domain

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
domainpath · string · required

Responses

200Lookalike domains for the domain V1LookalikeDomainsResponse
- domainstring
- hasCapabilitybooleanLite+ has the permutation scan; Free sees receiver-reported rows only.
- activeCountinteger
- registeredCountinteger
- ignoredCountinteger
- scanV1LookalikeScanState | null
  - candidatesGeneratedinteger
  - lastDnsPassCompletedstring | null
  - lastCtOkstring | null
  - lastCtErrorstring | null
- activeV1LookalikeRow[]
  - idstring (uuid)
  - namestringThe lookalike in ASCII (punycode) form, the stored identity.
  - displaystringUnicode form for display; equals name for plain ASCII.
  - isIdnboolean
  - rulestringThe generator rule that produced it (`homoglyph`, `tld_swap`, `keyword_affix`, and so on), or `rua_evidence` for a name a receiver reported.
  - ruleLabelstring
  - status"active" | "registered" | "ignored"
  - ignoreReasonstring | nullours, partner or other when ignored.
  - hasNsboolean
  - hasMxboolean
  - hasSpfboolean
  - hasDmarcboolean
  - parkedbooleanName servers or MX at a parking or for-sale service; registered but not set up to send, never active.
  - ctFirstSeenstring | nullEarliest certificate-transparency cert seen for the name (confirmation only).
  - ruaMessages90dintegerMessages receivers reported in the last 90 days with this name as the envelope or header From.
  - ruaLastSeenstring | null
  - registrarstring | null
  - registeredAtstring | nullRegistration date per RDAP, when known.
  - abuseEmailstring | nullThe registrar's abuse contact per RDAP, for the evidence pack.
  - firstSeenstring
  - lastSeenstring
- registeredV1LookalikeRow[]
  - idstring (uuid)
  - namestringThe lookalike in ASCII (punycode) form, the stored identity.
  - displaystringUnicode form for display; equals name for plain ASCII.
  - isIdnboolean
  - rulestringThe generator rule that produced it (`homoglyph`, `tld_swap`, `keyword_affix`, and so on), or `rua_evidence` for a name a receiver reported.
  - ruleLabelstring
  - status"active" | "registered" | "ignored"
  - ignoreReasonstring | nullours, partner or other when ignored.
  - hasNsboolean
  - hasMxboolean
  - hasSpfboolean
  - hasDmarcboolean
  - parkedbooleanName servers or MX at a parking or for-sale service; registered but not set up to send, never active.
  - ctFirstSeenstring | nullEarliest certificate-transparency cert seen for the name (confirmation only).
  - ruaMessages90dintegerMessages receivers reported in the last 90 days with this name as the envelope or header From.
  - ruaLastSeenstring | null
  - registrarstring | null
  - registeredAtstring | nullRegistration date per RDAP, when known.
  - abuseEmailstring | nullThe registrar's abuse contact per RDAP, for the evidence pack.
  - firstSeenstring
  - lastSeenstring
- ignoredV1LookalikeRow[]
  - idstring (uuid)
  - namestringThe lookalike in ASCII (punycode) form, the stored identity.
  - displaystringUnicode form for display; equals name for plain ASCII.
  - isIdnboolean
  - rulestringThe generator rule that produced it (`homoglyph`, `tld_swap`, `keyword_affix`, and so on), or `rua_evidence` for a name a receiver reported.
  - ruleLabelstring
  - status"active" | "registered" | "ignored"
  - ignoreReasonstring | nullours, partner or other when ignored.
  - hasNsboolean
  - hasMxboolean
  - hasSpfboolean
  - hasDmarcboolean
  - parkedbooleanName servers or MX at a parking or for-sale service; registered but not set up to send, never active.
  - ctFirstSeenstring | nullEarliest certificate-transparency cert seen for the name (confirmation only).
  - ruaMessages90dintegerMessages receivers reported in the last 90 days with this name as the envelope or header From.
  - ruaLastSeenstring | null
  - registrarstring | null
  - registeredAtstring | nullRegistration date per RDAP, when known.
  - abuseEmailstring | nullThe registrar's abuse contact per RDAP, for the evidence pack.
  - firstSeenstring
  - lastSeenstring
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the workspace (or the feature is switched off)
429Rate limited

POST/v1/domains/{domain}/lookalikes/{id}/ignoreIgnore a lookalike domain

Write key · Bearer

Parameters

domainpath · string · requireddomain name (workspace-scoped)
idpath · string (uuid) · requiredthe lookalike row id from GET /v1/domains/{domain}/lookalikes
workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Request body

reason"ours" | "partner" | "other"

Responses

200Ignored V1IgnoreLookalikeResponse
- domainstring
- idstring (uuid)
- reason"ours" | "partner" | "other"
- ignoredboolean
400invalid_request (unknown reason) or workspace_required
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
404Domain or lookalike row not found in the caller's workspace (or the feature is switched off)
429Rate limited

Sender Authorization Review1 endpoint

GET/v1/domains/{domain}/sender-reviewSender authorization review for a domain

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
domainpath · string · required

Responses

200The sender authorization review V1SenderReviewResponse
- domainstring
- windowDaysinteger
- status"ok" | "not_enough_history"The >=90-day history honesty gate's verdict; not_enough_history means findings are suppressed, never guessed.
- historyDaysinteger | null
- treeResolvedboolean
- hasSpfRecordboolean
- spfRecordstring | null
- trafficCompletebooleanFalse when the traffic read hit its row cap; unused claims are suppressed then.
- dkimObservationCompletebooleanFalse when grouped signing observations exceeded the observation cap. Signed counts are then lower bounds; missing observations cannot establish idle keys, and idle-key findings are suppressed.
- findingsLockedbooleanTrue when the plan does not include the findings. findings and dkimIdle are then null, not empty, so no claim is made.
- findingsV1SenderReviewFinding[] | null
  - type"spf_include_unused" | "spf_include_unrecognized"
  - includestring
  - vendorstring | null
  - rangeCountinteger
- dkimIdleobject[] | null
  - selectorstring
- grantsV1SenderReviewGrant[]
  - keystringStable grant identity, e.g. include:sendgrid.net or ip4:203.0.113.0/24.
  - kind"include" | "redirect" | "ip4" | "ip6" | "a" | "mx" | "exists" | "ptr"
  - qualifier"+" | "-" | "~" | "?"SPF qualifier as written: `+` means pass, `-` fail, `~` softfail, and `?` neutral. An omitted qualifier or a redirect serializes as `+`. Non-pass terms are preserved as SPF terms, not permission to send.
  - valuestring
  - vendorstring | nullVendor name when the include matches the anchor catalog; null = unrecognized (never guessed).
  - rangeCountinteger
  - attributedVolumenumberMessages attributed to this grant's ranges in the window (an IP under two grants credits both).
  - attributedIpsinteger
  - lastAttributedAtstring | null
  - reviewability"reviewable" | "macro" | "non_enumerable" | "truncated" | "unresolved" | "no_ranges" | "mail_host" | "mail_host_unknown" | "not_include"Why the grant can or cannot be judged for usage; anything but reviewable is never flagged unused.
- selectorsV1SenderReviewSelector[]
  - selectorstring
  - vendorstring | null
  - algostring | null
  - keyBitsinteger | null
  - source"auto" | "user"
  - signedVolumenumberMessages reported carrying this selector in the window (pass + fail). A lower bound when dkimObservationComplete is false; zero then cannot establish that the key was idle.
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Domain not found in the workspace
429Rate limited

Senders4 endpoints

GET/v1/sendersList your custom senders

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200The workspace's custom senders V1CustomSendersResponse
- countinteger
- sendersobject[]
  - senderIdstring (uuid)
  - namestring
  - category"email_provider" | "esp_marketing" | "esp_transactional" | "security" | "infrastructure" | "crm" | "other"
  - rangesstring[]
  - iconUrlstring | null
  - volume30dnumber
  - lastSeenstring | null
  - createdAtstring
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
403Plan does not include API access
429Rate limited

POST/v1/sendersIdentify a sending IP or CIDR range as a named vendor

Write key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Request body

ipOrCidrstringAn IP or CIDR, e.g. 198.2.132.1 or 198.2.128.0/18.
namestringThe vendor or sender name, e.g. Mailchimp.
category"email_provider" | "esp_marketing" | "esp_transactional" | "security" | "infrastructure" | "crm" | "other"

Responses

201Sender identified V1IdentifySenderResponse
- senderIdstring (uuid)
- namestring
- category"email_provider" | "esp_marketing" | "esp_transactional" | "security" | "infrastructure" | "crm" | "other"
- ipOrCidrstring
400invalid_request (missing name, invalid category or invalid CIDR)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
409conflict (a sender with that name already exists)
429Rate limited

PATCH/v1/senders/{id}Update a custom sender

Write key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
idpath · string (uuid) · required
Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Request body

namestring · optional
category"email_provider" | "esp_marketing" | "esp_transactional" | "security" | "infrastructure" | "crm" | "other" · optional
addRangestring · optionalAn IP or CIDR to add (widest /24 IPv4, /48 IPv6; max 16 ranges per sender).
removeRangestring · optionalAn existing range to remove. The last range is refused; delete the sender instead.

Responses

200Sender updated V1UpdateSenderResponse
- senderIdstring (uuid)
- namestring
- corpusOverlapsobject[]Input ranges that sit inside a global catalog vendor's published ranges (warn-and-allow).
  - rangestring
  - corpusSenderstring
400invalid_request (nothing to do, invalid category, invalid or too-wide CIDR, or range not found)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer)
404Not this workspace's custom sender (catalog vendors are never editable)
409conflict (duplicate name or range, overlap with your own sender, range cap, last range)
429Rate limited

DELETE/v1/senders/{id}Delete a custom sender

Write key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
idpath · string (uuid) · required
Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Responses

200Sender deleted V1DeleteSenderResponse
- senderIdstring (uuid)
- namestring
- deletedboolean
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is not an admin or owner; deleting is reserved for admins and owners)
404Not this workspace's custom sender
429Rate limited

Webhooks4 endpoints

GET/v1/webhooksList your outbound webhook endpoints

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200The workspace's webhook endpoints V1WebhooksResponse
- countinteger
- webhooksobject[]
  - idstring (uuid)
  - urlstring
  - descriptionstring | null
  - secretPrefixstring
  - eventTypesstring[] | null
  - status"active" | "disabled"
  - consecutiveFailuresinteger
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
403Plan does not include outbound webhooks
429Rate limited

POST/v1/webhooksRegister an outbound webhook endpoint

Write key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Request body

urlstringThe https endpoint URL to POST events to.
descriptionstring · optionalOptional label, e.g. Prod SIEM.
eventTypes("anomaly.crit" | "dns_fix.applied" | "dns_fix.reverted" | "dns_fix.failed" | "diagnosis.completed" | "diagnosis.recovery_confirmed" | "enforcement.regression_detected" | "enforcement.watch_all_clear" | "mandate.gap_detected" | "mandate.gap_resolved")[] · optionalWhich events to receive; omit for all.

Responses

201Endpoint created (signing secret returned once) V1CreateWebhookResponse
- idstring (uuid)
- secretstring | nullThe signing secret, returned once and never again. Null on an Idempotency-Key replay (the secret is never persisted for replay).
- secretPrefixstring
400invalid_request (invalid URL, not https, private address or unknown event type)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is a viewer), or plan_required
409conflict (endpoint limit reached)
429Rate limited

DELETE/v1/webhooks/{id}Delete an outbound webhook endpoint

Write key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
idpath · string (uuid) · required
Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Responses

200Endpoint deleted V1DeleteWebhookResponse
- idstring (uuid)
- deletedboolean
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
403forbidden (a read-only key, or a key whose creator is not an admin or owner; deleting is reserved for admins and owners)
404Not this workspace's webhook endpoint
429Rate limited

GET/v1/webhooks/{id}/deliveriesRecent delivery attempts for an endpoint

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.
idpath · string (uuid) · required

Responses

200Recent delivery attempts V1WebhookDeliveriesResponse
- endpointIdstring (uuid)
- countinteger
- deliveriesobject[]
  - idstring (uuid)
  - eventTypestring
  - status"pending" | "delivered" | "failed"
  - responseCodeinteger | null
  - errorstring | null
  - attemptinteger
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
404Not this workspace's webhook endpoint
429Rate limited

Workspace1 endpoint

GET/v1/workspace/healthWorkspace-wide health summary

Read key · Bearer

Parameters

workspacequery · string (uuid) · optionalOrganization keys only (the MSP partner API): the client workspace this call acts on. Ids come from GET /v1/msp/clients, or the Client workspace IDs table on /msp/api. Required with an organization key, which answers 400 workspace_required without it. A workspace outside the key's own organization answers 404, which says nothing about whether it exists. A workspace key ignores this parameter and stays pinned to its own workspace.

Responses

200Workspace health summary V1WorkspaceHealth
- alignmentPctinteger | nullWorkspace alignment percentage, adjusted for unidentified sources as the dashboard shows it.
- trendDeltaPpinteger | nullChange in points vs the prior window.
- totalMessagesinteger
- totalReportsinteger
- totalDomainsinteger
400workspace_required (an organization key called without ?workspace=)
401Missing or invalid API key
429Rate limited

MSP20 endpoints

GET/v1/msp/clientsThe MSP book of business

Organization key with msp:read · Bearer

Responses

200The book of business V1MspClientsResponse
- clientsV1MspClientRow[]
  - workspaceIdstring
  - namestring
  - createdAtstring (date-time)
  - archivedAtstring (date-time) | null
  - contactEmailstring | null
  - domainsTotalinteger
  - domainsVerifiedinteger
  - sendingDomainsinteger
  - enforcedSendingDomainsinteger
  - openCritsinteger
  - blockedSpoof30dinteger
  - dataThroughstring | nullRUA data-through timestamp; null = no reports yet.
- archivedV1MspClientRow[]
  - workspaceIdstring
  - namestring
  - createdAtstring (date-time)
  - archivedAtstring (date-time) | null
  - contactEmailstring | null
  - domainsTotalinteger
  - domainsVerifiedinteger
  - sendingDomainsinteger
  - enforcedSendingDomainsinteger
  - openCritsinteger
  - blockedSpoof30dinteger
  - dataThroughstring | nullRUA data-through timestamp; null = no reports yet.
- summaryobject
  - clientCountinteger
  - domainCountinteger
  - sendingDomainsinteger
  - enforcedSendingDomainsinteger
  - openCritsinteger
  - blockedSpoof30dinteger
  - workspaceLimitinteger | null
401Missing or invalid API key
403org_key_required (workspace key) or plan_required
429Rate limited

POST/v1/msp/clientsCreate a client workspace

Organization key with msp:write · Bearer

Parameters

Idempotency-Keyheader · string · optionalOptional client key; a retry with the same value replays the original response.

Request body

namestringThe client's display name, e.g. Acme Roofing.

Responses

201Client workspace created V1MspCreateClientResponse
- workspaceIdstring
- namestring
- slugstring
400invalid_request (missing or over-long name)
401Missing or invalid API key
403forbidden (no msp:write, or the creator's role cannot manage the org)
409plan_limit (workspace ceiling)
429Rate limited

GET/v1/msp/clients/{id}One client workspace's posture

Organization key with msp:read · Bearer

Parameters

idpath · string · requiredthe client workspace id (from GET /v1/msp/clients)

Responses

200The client detail V1MspClientDetail
- workspaceIdstring
- namestring
- createdAtstring (date-time)
- archivedAtstring (date-time) | null
- internalboolean
- contactEmailstring | null
- domainsobject[]
  - namestring
  - statusstring
  - purpose"sending" | "monitor_only"
  - policystring | null
  - pctinteger | null
  - testModebooleanTrue only when the published DMARC record carries `t=y`. A `t=n` record, or one with no `t` tag, is not in test mode.
  - enforcedboolean
- membersobject[]
  - emailstring
  - rolestring
  - createdAtstring (date-time)
- orgLevelMemberCountinteger
- pendingInvitesobject[]
  - emailstring
  - rolestring
  - expiresAtstring (date-time)
401Missing or invalid API key
403org_key_required or plan_required
404No client workspace with that id in the key's organization
429Rate limited

POST/v1/msp/clients/{id}/archiveArchive a client

Organization key with msp:write · Bearer

Parameters

idpath · string · required

Responses

200Archived V1MspArchiveResponse
- workspaceIdstring
- archivedboolean
401Missing or invalid API key
403forbidden (scope or role)
404Unknown or foreign client id
429Rate limited

POST/v1/msp/clients/{id}/restoreRestore an archived client

Organization key with msp:write · Bearer

Parameters

idpath · string · required

Responses

200Restored V1MspArchiveResponse
- workspaceIdstring
- archivedboolean
401Missing or invalid API key
403forbidden (scope or role)
404Unknown or foreign client id
429Rate limited

POST/v1/msp/clients/{id}/domainsBulk-add domains to a client

Organization key with msp:write · Bearer

Parameters

idpath · string · required
Idempotency-Keyheader · string · optional

Request body

domainsstring[]Domain names to add.
purpose"sending" | "monitor_only" · optionalDefaults to sending.

Responses

200Per-row outcomes V1MspBulkAddResponse
- addedinteger
- itemsobject[]
  - inputstring
  - outcome"added" | "restored" | "duplicate" | "invalid" | "aup_blocked" | "plan_limit" | "failed"
  - domainstring | null
400invalid_request (empty, over 200 rows, or a non-string entry)
401Missing or invalid API key
403forbidden (scope or role)
404Unknown or foreign client id
409conflict (client is archived)
429Rate limited

POST/v1/msp/clients/{id}/invitesInvite a client user

Organization key with msp:write · Bearer

Parameters

idpath · string · required

Request body

emailstring
role"viewer" | "member"

Responses

201Invite sent V1MspInviteResponse
- workspaceIdstring
- emailstring
- rolestring
400invalid_request (email or role)
401Missing or invalid API key
403forbidden (scope or role)
404Unknown or foreign client id
409conflict (already a member, already invited, or archived) or plan_limit (seats)
429rate_limited (too many requests, or too many invite emails from this organization)

GET/v1/msp/usageA month of the usage ledger

Organization key with msp:read · Bearer

Parameters

monthquery · string · optionalCalendar month, YYYY-MM (UTC). Defaults to the current month.

Responses

200The month's ledger V1MspUsageMonth
- monthstringYYYY-MM (UTC calendar month).
- daysobject[]
  - usageDatestring
  - billableintegerRetained daily high-water billable quantity.
  - freeMonitorinteger
  - nfrinteger
- monthPeakBillableintegerMonth high-water including retained event reservations; a projection, not a paid-invoice receipt.
- perClientSnapshotKnownbooleanWhether the latest monthly per-client snapshot is valid; false distinguishes unavailable history from a genuine empty snapshot.
- perClientobject[]
  - workspaceIdstring
  - namestring
  - billableintegerBillable count in the latest per-client snapshot for this month.
  - freeMonitorinteger
  - nfrinteger
  - sendinginteger · optionalBillable SENDING domains alone, excluding monitor-only domains that overflowed the free allowance and are being billed. Optional: ledger rows written before 2026-08-17 do not carry it. When present it explains the `billable` figure: `billable - sending` is the overflow, and it is the count the free-monitor allowance anchors to (in the internal workspace, its free domain also counts when it sends).
400invalid_request (malformed month)
401Missing or invalid API key
403org_key_required or plan_required
429Rate limited

GET/v1/msp/brandThe white-label brand profile

Organization key with msp:read · Bearer

Responses

200The brand profile V1MspBrand
- configuredboolean
- productNamestring | null
- colorsobject | null
  - primarystring · optional
  - accentstring · optional
- emailFromNamestring | null
- emailFromAddressstring | null
- emailDomainStatusstring
- portalHostnamestring | null
- portalHostnameStatusstring
- skinOwnDashboardboolean
- supportUrlstring | null
- supportEmailstring | null
- privacyUrlstring | null
- termsUrlstring | null
401Missing or invalid API key
403org_key_required or plan_required
429Rate limited

GET/v1/msp/alert-policyThe account alert policy

Organization key with msp:read · Bearer

Responses

200The alert policy V1MspAlertPolicy
- severity"crit" | "crit_warn"
- delivery"instant" | "hourly"
- newSourcesBlockedboolean
- storedbooleanFalse until the account saved its settings once; the defaults apply until then.
- updatedAtstring (date-time) | null
- clientsobject[]
  - workspaceIdstring
  - namestring
  - archivedboolean
  - override"muted" | "crit" | "crit_warn" | nullnull means the account policy applies to this client.
- recipientsV1MspAlertRecipient[]
  - idstring
  - addressstring
  - state"awaiting" | "confirmed" | "expired" | "unsubscribed"awaiting: the confirmation link was sent and not clicked yet. expired: the link lapsed unclicked. Only a confirmed recipient receives alerts.
  - confirmExpiresAtstring (date-time) | null
  - confirmedAtstring (date-time) | null
  - unsubscribedAtstring (date-time) | null
  - createdAtstring (date-time)
- maxRecipientsinteger
- routeobjectThe account's own Slack channel and webhook endpoint, for every client.
  - slackobject | null
  - webhookobject | null
401Missing or invalid API key
403org_key_required or plan_required
429Rate limited

PUT/v1/msp/alert-policyReplace the account alert policy

Organization key with msp:write · Bearer

Request body

severity"crit" | "crit_warn"crit alerts on critical findings only; crit_warn adds warnings.
delivery"instant" | "hourly"instant emails each alert as it fires; hourly sends one roll-up an hour.
newSourcesBlockedbooleanAlert when receivers block a wave of mail from sources new to a domain.

Responses

200Saved V1MspAlertPolicySettings
- severity"crit" | "crit_warn"crit alerts on critical findings only; crit_warn adds warnings.
- delivery"instant" | "hourly"instant emails each alert as it fires; hourly sends one roll-up an hour.
- newSourcesBlockedbooleanAlert when receivers block a wave of mail from sources new to a domain.
400invalid_request (a field is missing or not one of its values)
401Missing or invalid API key
403forbidden (scope or role, or a suspended account)
429Rate limited

PUT/v1/msp/alert-policy/clients/{id}Set or clear one client's alert override

Organization key with msp:write · Bearer

Parameters

idpath · string · required

Request body

mode"muted" | "crit" | "crit_warn" | null

Responses

200Saved V1MspAlertOverrideResponse
- workspaceIdstring
- override"muted" | "crit" | "crit_warn" | null
400invalid_request (mode missing or not one of its values)
401Missing or invalid API key
403forbidden (scope or role, or a suspended account turning alerts up)
404Unknown or foreign client id
429Rate limited

GET/v1/msp/alert-policy/recipientsThe extra alert recipients

Organization key with msp:read · Bearer

Responses

200The recipients V1MspAlertRecipients
- recipientsV1MspAlertRecipient[]
  - idstring
  - addressstring
  - state"awaiting" | "confirmed" | "expired" | "unsubscribed"awaiting: the confirmation link was sent and not clicked yet. expired: the link lapsed unclicked. Only a confirmed recipient receives alerts.
  - confirmExpiresAtstring (date-time) | null
  - confirmedAtstring (date-time) | null
  - unsubscribedAtstring (date-time) | null
  - createdAtstring (date-time)
- maxRecipientsintegerThe most extra recipients an account may have.
401Missing or invalid API key
403org_key_required or plan_required
429Rate limited

POST/v1/msp/alert-policy/recipientsAdd an extra alert recipient

Organization key with msp:write · Bearer

Parameters

Idempotency-Keyheader · string · optional

Request body

addressstring

Responses

201Added; the confirmation email was sent V1MspAlertRecipientAdded
- idstring
- addressstring
- state"awaiting"
400invalid_request (not a valid email address)
401Missing or invalid API key
403forbidden (scope or role, or a suspended account)
409conflict (already listed, a member, suppressed, unsubscribed, or the list is full)
429rate_limited (too many requests, or too many confirmation emails from this account)
502email_failed (saved, but the confirmation email did not send; the body carries the id)

DELETE/v1/msp/alert-policy/recipients/{id}Remove an extra alert recipient

Organization key with msp:write · Bearer

Parameters

idpath · string · required
Idempotency-Keyheader · string · optional

Responses

200Removed
- idstring
- removedboolean
401Missing or invalid API key
403forbidden (scope or role)
404Unknown or foreign recipient id
429Rate limited

POST/v1/msp/alert-policy/recipients/{id}/resendResend a recipient's confirmation link

Organization key with msp:write · Bearer

Parameters

idpath · string · required
Idempotency-Keyheader · string · optional

Responses

200Sent
- idstring
- resentboolean
401Missing or invalid API key
403forbidden (scope or role, or a suspended account)
404Unknown or foreign recipient id
409conflict (the recipient is not waiting to confirm)
429rate_limited (too many requests, or too many confirmation emails from this account)
502email_failed (the confirmation email did not send)

POST/v1/msp/alert-policy/webhookCreate the account webhook endpoint

Organization key with msp:write · Bearer

Parameters

Idempotency-Keyheader · string · optional

Request body

urlstring
descriptionstring · optionalA label, up to 80 characters.

Responses

201Created; the secret is shown once V1MspAlertWebhookCreated
- idstring
- secretstring | nullThe signing secret, shown once. A replay with the same Idempotency-Key answers null.
- secretPrefixstring
400invalid_request (the URL was refused; reason says why)
401Missing or invalid API key
403forbidden (scope or role, or a suspended account) or plan_required
409conflict (the account already has an endpoint)
429Rate limited

DELETE/v1/msp/alert-policy/webhookDelete the account webhook endpoint

Organization key with msp:write · Bearer

Parameters

Idempotency-Keyheader · string · optional

Responses

200Deleted
- deletedboolean
401Missing or invalid API key
403forbidden (scope or role)
404The account has no webhook endpoint
429Rate limited

POST/v1/msp/alert-policy/webhook/enableTurn the account webhook endpoint on

Organization key with msp:write · Bearer

Responses

200Turned on V1MspAlertWebhookStatus
- status"active" | "disabled"
401Missing or invalid API key
403forbidden (scope or role, or a suspended account)
404The account has no webhook endpoint
429Rate limited

POST/v1/msp/alert-policy/webhook/disableTurn the account webhook endpoint off

Organization key with msp:write · Bearer

Responses

200Turned off V1MspAlertWebhookStatus
- status"active" | "disabled"
401Missing or invalid API key
403forbidden (scope or role)
404The account has no webhook endpoint
429Rate limited

A signed post when something changes. Check it with one HMAC.

Register an endpoint and we post each event as JSON. Every delivery is signed with your endpoint's whsec_ secret, so you can verify it came from us and reject a replay.

Signature: X-TYI-Signature: sha256=<hex>HMAC-SHA256 over timestamp.rawBody with your secret.
Timestamp: X-TYI-TimestampUnix seconds, in its own header, so you can refuse a stale one.
Event id: X-TYI-Event-Id
Plan: Pro and up

anomaly.crit
dns_fix.applied
dns_fix.reverted
dns_fix.failed
diagnosis.completed
diagnosis.recovery_confirmed
enforcement.regression_detected
enforcement.watch_all_clear
mandate.gap_detected
mandate.gap_resolved

Or ask an assistant. The same data over MCP.

Claude, Cursor or any MCP client can read your workspace and, with a write token, do what you could do yourself: dismiss an issue, re-check DNS, stage a one-click fix.

Create a tokenIn the app under Settings, Integrations, MCP. You see it once; store it like a password and revoke it there any time.
Add the serverURL https://mcp.trustyourinbox.com, with the token as a Bearer credential.
AskStart with "list my domains". A read token answers; a write token acts, and every change it makes carries the token's name in your audit log.

Start with one domain. Add a key when you need one.

Free for one domain, no card. API keys and webhooks come with the Pro plan.