Developers
The trustyourinbox API
Pull your domains, reports, senders, and issues into your own scripts and dashboards, automate fixes, and register outbound webhooks for a signed push the moment something breaks. Authenticate with a workspace API key over HTTPS; every response is JSON.
Authentication
Every request authenticates with a workspace API key sent as a bearer token in the Authorization header. Keys are header-only, never a cookie, and there is no browser CORS, so calls are made server-to-server.
Mint a key in the app under Settings, Integrations, API keys. A key carries a read scope and, optionally, a write scope; a write also requires that the creator's role still allows edits, so revoking a role revokes the key's writes live. API keys are available on the Pro plan and up.
Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxxBase URL and versioning
The base URL is https://api.trustyourinbox.com/v1. The /v1 path is a versioned, stable contract: existing fields will not change shape, and new fields are added without a version bump. Every response is JSON with Cache-Control: no-store.
Rate limits
Requests are rate-limited per key (120 requests per 60 seconds). When the limit is exceeded the API returns 429 with a Retry-After header (seconds); back off for that long and retry. Staging DNS fixes has a separate, stricter cap (five changes per 24 hours).
Errors
Errors use a stable envelope: an error machine code and a human-readable message. A 429 also carries retryAfterSec. Switch on error, not the message text.
{ "error": "invalid_request", "message": "name is required" }| Code | When |
|---|---|
unauthorized | The API key is missing, malformed, revoked, or expired. |
forbidden | A read-only key (or a role without edit rights) attempted a write. |
plan_required | API keys need the Pro plan or higher; the workspace is below it. |
not_found | The domain, report, or change is not in the key's workspace. |
invalid_request | The body or a parameter failed validation. |
conflict | The resource already exists, or its state blocks the action. |
plan_limit | A plan cap was reached (for example the domain limit). |
aup_block | The domain fails the acceptable use policy. |
idempotency_in_progress | A request with the same Idempotency-Key is still running. |
idempotency_key_reused | The Idempotency-Key was reused for a different request body. |
rate_limited | The per-key rate limit was exceeded; honor Retry-After. |
internal | An unexpected server error. Safe to retry. |
Idempotency
Creating writes (add a domain, stage a DNS fix, identify a sender) accept an optional Idempotency-Key header. A retry with the same key replays the original response instead of acting twice. Reusing a key for a different body returns idempotency_key_reused; keys are remembered for 24 hours.
Ranges
Endpoints over a time window take a range query parameter in days (default 30, clamped to 90). The reports endpoint takes limit instead (default 50, clamped to 200).
Quickstart
Mint a Pro-plan API key, then call the workspace health endpoint to confirm it works:
curl https://api.trustyourinbox.com/v1/workspace/health \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"alignmentPct": 98,
"trendDeltaPp": 2,
"totalMessages": 14820,
"totalReports": 36,
"totalDomains": 6
}Prefer a GUI? Use Open in Postman above to download a ready-to-import collection of every endpoint, then import it into Postman (File, then Import). Set the apiKey collection variable to your key once and every request sends it. The API has no browser CORS, so requests run from Postman, curl, or your server, not from this page.
Domains#
List the domains in the workspace (public REST API) #
Public REST API. Served at https://api.trustyourinbox.com/v1/domains (the api host rewrites /v1/* to /api/v1/*). Bearer API key; read scope; scoped to the key's workspace. Rate-limited (120/60s per key).
Requires a read-scoped key (Bearer).curl https://api.trustyourinbox.com/v1/domains \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domains": [
{
"name": "acme.com",
"status": "pending",
"purpose": "sending",
"dnsProvider": "cloudflare",
"createdAt": "2026-06-01T00:00:00Z"
},
{
"name": "shop.acme.com",
"status": "pending",
"purpose": "sending",
"dnsProvider": "cloudflare",
"createdAt": "2026-06-08T00:00:00Z"
}
]
}Add a domain to the workspace (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope (the key carries `write` AND the creator's live role allows edits). Reuses the same add-domain core the dashboard uses - validation, the plan domain cap, the AUP gate, provider detection, insert, and audit. Honors an optional Idempotency-Key header (a retry replays the created domain). Audited "via API key X".
Requires a write-scoped key (Bearer).Optional client key; a retry with the same value replays the original response.
The domain to add, e.g. acme.com
Defaults to sending.
curl -X POST https://api.trustyourinbox.com/v1/domains \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6" \
-d '{
"name": "acme.com",
"purpose": "sending"
}'{
"domain": "acme.com",
"status": "verified",
"purpose": "sending",
"verification": {
"recordType": "TXT",
"recordName": "_dmarc.acme.com",
"recordValue": "v=DMARC1; p=reject; rua=mailto:dmarc@acme.com"
},
"dnsProvider": "cloudflare"
}Re-detect the domain's DNS provider now (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Re-runs DNS-provider detection immediately instead of waiting for the daily sweep (after moving DNS / connecting a provider). No body. Reuses refreshDnsProviderForDomain; audited "via API key X" only when the provider flips.
Requires a write-scoped key (Bearer).domain name (workspace-scoped)
Present only when detected is true.
curl -X POST https://api.trustyourinbox.com/v1/domains/acme.com/recheck \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"detected": true,
"provider": "cloudflare",
"providerName": "Mailchimp",
"changed": false
}Authentication & deliverability#
The four mandate compliance tiles for one domain (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope; the domain must belong to the key's workspace.
Requires a read-scoped key (Bearer).domain name (workspace-scoped)
One mandate tile (Google/Yahoo, Microsoft, BIMI, or TLS) for a domain.
One mandate tile (Google/Yahoo, Microsoft, BIMI, or TLS) for a domain.
One mandate tile (Google/Yahoo, Microsoft, BIMI, or TLS) for a domain.
One mandate tile (Google/Yahoo, Microsoft, BIMI, or TLS) for a domain.
curl https://api.trustyourinbox.com/v1/domains/acme.com/compliance \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"compliance": {
"google": {
"id": "google",
"title": "Google and Yahoo bulk-sender requirements",
"tier": "pass",
"compliantCount": 3,
"totalScored": 14,
"noun": "domains"
},
"microsoft": {
"id": "google",
"title": "Google and Yahoo bulk-sender requirements",
"tier": "pass",
"compliantCount": 3,
"totalScored": 14,
"noun": "domains"
},
"bimi": {
"id": "google",
"title": "Google and Yahoo bulk-sender requirements",
"tier": "pass",
"compliantCount": 3,
"totalScored": 14,
"noun": "domains"
},
"tls": {
"id": "google",
"title": "Google and Yahoo bulk-sender requirements",
"tier": "pass",
"compliantCount": 3,
"totalScored": 14,
"noun": "domains"
}
}
}Sender breakdown with spoofer-adjusted alignment (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope; workspace-scoped domain. The alignment headline is spoofer-adjusted (the Q12 invariant) - it matches the dashboard, not raw aligned/total.
Requires a read-scoped key (Bearer).domain name (workspace-scoped)
Window in days (clamped to 90, default 30)
Spoofer-adjusted (never raw aligned/total).
Present only when totalVolume > 0.
Present only when totalVolume > 0.
Present only when totalVolume > 0.
The ASN / org name for the IP.
curl https://api.trustyourinbox.com/v1/domains/acme.com/senders?range=30 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"rangeDays": 30,
"totalVolume": 1240,
"alignmentPct": 98,
"blockedSpoof": 318,
"knownVolume": 0,
"unknownVolume": 0,
"distinctSenders": 0,
"senders": [
{
"ip": "203.0.113.10",
"network": "Google LLC",
"volume": 1240,
"alignedPct": 98,
"known": true
},
{
"ip": "198.51.100.24",
"network": "Amazon.com, Inc.",
"volume": 360,
"alignedPct": 94,
"known": true
}
]
}Published authentication records for a domain (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope; workspace-scoped domain. The DMARC / SPF / DKIM / MTA-STS records and what's wrong with them - mirrors the MCP get_protocol_status payload.
Requires a read-scoped key (Bearer).domain name (workspace-scoped)
DMARCbis t= - "y" means published but receivers don't enforce.
DMARCbis non-existent-subdomain policy.
DNS lookups consumed vs the RFC 7208 limit of 10.
The qualifier on the final all mechanism (~, -, +, ?).
Count of published selectors found.
Smallest published key size in bits.
MTA-STS mode (testing / enforce), or null when not published.
curl https://api.trustyourinbox.com/v1/domains/acme.com/protocol \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"dmarc": {
"policy": "reject",
"pct": 98,
"testMode": "y",
"np": "reject",
"reportsToUs": true,
"multiRecord": false
},
"spf": {
"lookupCount": 7,
"allQualifier": "~",
"multiRecord": false
},
"dkimSelectors": 2,
"dkimMinKeyBits": 2048,
"mtaSts": "enforce"
}Subdomains sending as a domain, bucketed (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope; workspace-scoped domain. One row per sending subdomain with its spoofer-adjusted alignment and a Known / Review / Not in DNS bucket - mirrors the MCP get_subdomain_breakdown payload. Probes live DNS for the "Not in DNS" split.
Requires a read-scoped key (Bearer).domain name (workspace-scoped)
Window in days (clamped to 90, default 30)
Present only when subdomainCount > 0.
Present only when subdomainCount > 0.
Present only when subdomainCount > 0.
Present only when subdomainCount > 0.
Present only when subdomainCount > 0.
What a non-existent subdomain resolves to (np ?? sp ?? p). Present only when subdomainCount > 0.
Distinct subdomains over a wider 90-day lookback (subdomain abuse is bursty).
The relative label (e.g. "marketing" for marketing.acme.com).
Spoofer-adjusted; null when no legit mail is measurable.
true = the subdomain resolves; false = NXDOMAIN; null = inconclusive.
curl https://api.trustyourinbox.com/v1/domains/acme.com/subdomains?range=30 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"rangeDays": 30,
"subdomainCount": 3,
"knownCount": 3,
"worthALookCount": 3,
"nonexistentCount": 3,
"unrecognizedCount": 3,
"totalVolume": 1240,
"nxdomainPolicy": "example",
"extendedSubdomainCount": 3,
"subdomains": [
{
"subdomain": "marketing.acme.com",
"label": "marketing",
"status": "Known",
"bucket": "known",
"volume": 1240,
"alignmentPct": 98,
"spoofVolume": 318,
"blockedSpoof": 318,
"distinctSenders": 0,
"lastSeen": "2026-06-01T00:00:00Z",
"inDns": true,
"verdict": "Known sender",
"whatItMeans": "This subdomain is recognized and aligned."
},
{
"subdomain": "news.acme.com",
"label": "news",
"status": "Known",
"bucket": "known",
"volume": 360,
"alignmentPct": 94,
"spoofVolume": 42,
"blockedSpoof": 42,
"distinctSenders": 0,
"lastSeen": "2026-06-08T00:00:00Z",
"inDns": true,
"verdict": "Known sender",
"whatItMeans": "This subdomain is recognized and aligned."
}
]
}Blocked-spoof volume and top sources over a window (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope; workspace-scoped domain. Uses the canonical blocked-spoof filter.
Requires a read-scoped key (Bearer).domain name (workspace-scoped)
Window in days (clamped to 90, default 30)
curl https://api.trustyourinbox.com/v1/domains/acme.com/spoof-activity?range=30 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"rangeDays": 30,
"blockedSpoof": 318,
"blockedSpoofPrior": 0,
"topSources": [
{
"ip": "203.0.113.10",
"attempts": 512,
"network": "Google LLC",
"country": "US",
"disposition": "reject"
},
{
"ip": "198.51.100.24",
"attempts": 87,
"network": "Amazon.com, Inc.",
"country": "DE",
"disposition": "reject"
}
],
"daily": [
{
"date": "2026-06-01T00:00:00Z",
"volume": 1240
},
{
"date": "2026-06-08T00:00:00Z",
"volume": 360
}
]
}Reports#
Recent aggregate (RUA) reports for one domain (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope; workspace-scoped domain. Newest first.
Requires a read-scoped key (Bearer).domain name (workspace-scoped)
Max reports (clamped to 200, default 50)
curl https://api.trustyourinbox.com/v1/domains/acme.com/reports?limit=50 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"reports": [
{
"id": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"reportingOrg": "google.com",
"rangeStart": "2026-06-01T00:00:00Z",
"rangeEnd": "2026-06-01T00:00:00Z",
"volume": 1240,
"passing": 1198
},
{
"id": "2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
"reportingOrg": "Yahoo Inc.",
"rangeStart": "2026-06-08T00:00:00Z",
"rangeEnd": "2026-06-08T00:00:00Z",
"volume": 360,
"passing": 352
}
]
}Drill into one aggregate (RUA) report (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope. The report's provider, window, outcome composition, and diagnosed failing senders - mirrors the MCP get_report payload. A report id from another tenant returns 404 with no existence leak.
Requires a read-scoped key (Bearer).aggregate-report id (from .../reports; workspace-scoped)
Raw aligned/total - the report's factual composition.
Verdict-grade alignment of the legitimate mail; null for an all-spoof report.
curl https://api.trustyourinbox.com/v1/reports/1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"reportId": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"externalReportId": "1a2b3c4d5e6f",
"reportingOrg": "google.com",
"domain": "acme.com",
"rangeStart": "2026-06-01T00:00:00Z",
"rangeEnd": "2026-06-01T00:00:00Z",
"outcome": {
"aligned": 1198,
"dkimOnly": 22,
"spfOnly": 8,
"failed": 12,
"total": 1240,
"alignmentPct": 98,
"spoofVolume": 318,
"adjustedPct": 98,
"recordCount": 9
},
"failureGroups": [
{
"sender": "example",
"vendorName": "Mailchimp",
"ipCount": 4,
"failedVolume": 318,
"class": "forwarding",
"diagnosis": "Receivers cannot report TLS delivery problems for this domain."
},
{
"sender": "example",
"vendorName": "Mailchimp",
"ipCount": 1,
"failedVolume": 42,
"class": "forwarding",
"diagnosis": "Receivers cannot report TLS delivery problems for this domain."
}
]
}Issues#
Open issues across the workspace (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope. Open (non-dismissed) issues across every domain, worst-first. Rate-limited (120/60s per key).
Requires a read-scoped key (Bearer).The anomaly type id (the issue's stable machine key).
curl https://api.trustyourinbox.com/v1/issues \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"issues": [
{
"key": "tls_rpt_missing:acme.com",
"type": "tls_rpt_missing",
"severity": "opportunity",
"headline": "TLS reporting is not configured",
"why": "Receivers cannot report TLS delivery problems for this domain.",
"domain": "acme.com",
"firstSeenAt": "2026-06-01T00:00:00Z",
"impact": "Low"
},
{
"key": "tls_rpt_missing:acme.com",
"type": "tls_rpt_missing",
"severity": "opportunity",
"headline": "TLS reporting is not configured",
"why": "Receivers cannot report TLS delivery problems for this domain.",
"domain": "acme.com",
"firstSeenAt": "2026-06-08T00:00:00Z",
"impact": "Low"
}
]
}Open issues for one domain (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope; workspace-scoped domain. Dismissal-aware (the same source the action inbox and digest read).
Requires a read-scoped key (Bearer).domain name (workspace-scoped)
The anomaly type id (the issue's stable machine key).
curl https://api.trustyourinbox.com/v1/domains/acme.com/issues \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"issues": [
{
"key": "tls_rpt_missing:acme.com",
"type": "tls_rpt_missing",
"severity": "opportunity",
"headline": "TLS reporting is not configured",
"why": "Receivers cannot report TLS delivery problems for this domain.",
"domain": "acme.com",
"firstSeenAt": "2026-06-01T00:00:00Z",
"impact": "Low"
},
{
"key": "tls_rpt_missing:acme.com",
"type": "tls_rpt_missing",
"severity": "opportunity",
"headline": "TLS reporting is not configured",
"why": "Receivers cannot report TLS delivery problems for this domain.",
"domain": "acme.com",
"firstSeenAt": "2026-06-08T00:00:00Z",
"impact": "Low"
}
]
}Dismiss / snooze an open issue (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Hides the issue: body { "permanent": false } snoozes 7 days (default), true dismisses indefinitely. Reverse with .../restore. Reuses dismissAnomalyCore (the same core the dashboard + MCP use); audited "via API key X".
Requires a write-scoped key (Bearer).domain name (workspace-scoped)
the issue (anomaly) type to hide, e.g. tls_rpt_missing
true = dismiss indefinitely; false (default) = snooze 7 days.
curl -X POST https://api.trustyourinbox.com/v1/domains/acme.com/issues/tls_rpt_missing/dismiss \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"permanent": true
}'{
"domain": "acme.com",
"type": "tls_rpt_missing",
"mode": "dismiss",
"dismissed": true
}Restore a dismissed / snoozed issue (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Un-hides the issue so it returns to the open inbox. The inverse of .../dismiss. Reuses restoreAnomalyCore; audited "via API key X".
Requires a write-scoped key (Bearer).domain name (workspace-scoped)
the issue (anomaly) type to restore
curl -X POST https://api.trustyourinbox.com/v1/domains/acme.com/issues/tls_rpt_missing/restore \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "acme.com",
"type": "tls_rpt_missing",
"restored": true
}DNS fixes#
Stage a one-click DNS fix for an issue (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Body { "type": "<issue_type>" } for a one-click-fixable issue. The fix is STAGED (not applied immediately) through the same 5-minute-delay / email-with-one-click-cancel / 24-hour-undo safety pipeline the dashboard + MCP use - no second DNS-write path. Reuses stageFixForAnomalyById; audited "via API key X". Honors Idempotency-Key (no double-stage).
Requires a write-scoped key (Bearer).domain name (workspace-scoped)
Optional client key; a retry with the same value replays the original response.
A one-click-fixable issue type, e.g. dmarc_np_missing.
curl -X POST https://api.trustyourinbox.com/v1/domains/acme.com/dns-fixes \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6" \
-d '{
"type": "tls_rpt_missing"
}'{}Staged / in-undo-window DNS changes for the workspace (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope. The read half of the staged-fix loop - DNS fixes currently staged (in the 5-minute pre-apply window) or recently applied but still inside the 24-hour undo window. Cancel one via DELETE /v1/changes/{id}.
Requires a read-scoped key (Bearer).staged, applied, canceled, etc.
curl https://api.trustyourinbox.com/v1/changes \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"changes": [
{
"id": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"domain": "acme.com",
"fixType": "dmarc.add_np_reject",
"recordName": "_dmarc.acme.com",
"recordType": "TXT",
"status": "verified",
"stagedAt": "2026-06-01T00:00:00Z",
"applyAt": "2026-06-01T00:00:00Z",
"undoUntil": "2026-06-01T00:00:00Z"
},
{
"id": "2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
"domain": "acme.com",
"fixType": "dmarc.add_np_reject",
"recordName": "_dmarc.acme.com",
"recordType": "TXT",
"status": "verified",
"stagedAt": "2026-06-08T00:00:00Z",
"applyAt": "2026-06-08T00:00:00Z",
"undoUntil": "2026-06-08T00:00:00Z"
}
]
}Cancel a staged DNS change (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Cancels a fix that is still staged (inside the 5-minute pre-apply window); an applied change has the 24-hour undo in the app. Reuses cancelStagedChange, workspace-scoped so a foreign change id can't be canceled. Audited "via API key X".
Requires a write-scoped key (Bearer).the staged change id (from GET /v1/changes)
A staged or recently-applied one-click DNS change. The email cancel secret is never exposed.
staged, applied, canceled, etc.
curl -X DELETE https://api.trustyourinbox.com/v1/changes/1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"canceled": true,
"change": {
"id": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"domain": "acme.com",
"fixType": "dmarc.add_np_reject",
"recordName": "_dmarc.acme.com",
"recordType": "TXT",
"status": "verified",
"stagedAt": "2026-06-01T00:00:00Z",
"applyAt": "2026-06-01T00:00:00Z",
"undoUntil": "2026-06-01T00:00:00Z"
}
}Senders#
List your custom senders (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope. Every custom (source "user") sender in the workspace - including ones with no observed traffic yet - with ranges, optional icon URL, and trailing-30-day attributed volume. The same loader the dashboard's management card reads.
Requires a read-scoped key (Bearer).curl https://api.trustyourinbox.com/v1/senders \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"count": 3,
"senders": [
{
"senderId": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"name": "acme.com",
"category": "email_provider",
"ranges": [
"example",
"example"
],
"iconUrl": "example",
"volume30d": 0,
"lastSeen": "example",
"createdAt": "example"
},
{
"senderId": "2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
"name": "shop.acme.com",
"category": "email_provider",
"ranges": [
"example",
"example"
],
"iconUrl": "example",
"volume30d": 0,
"lastSeen": "example",
"createdAt": "example"
}
]
}Identify a sending IP / CIDR as a named vendor (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Body { "ipOrCidr", "name", "category" } - labels a source so it counts as a known sender instead of an unknown source. Reuses identifySenderCore; audited "via API key X". Honors Idempotency-Key.
Requires a write-scoped key (Bearer).Optional client key; a retry with the same value replays the original response.
An IP or CIDR, e.g. 198.2.132.1 or 198.2.128.0/18.
The vendor / sender name, e.g. Mailchimp.
curl -X POST https://api.trustyourinbox.com/v1/senders \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6" \
-d '{
"ipOrCidr": "198.2.132.0/24",
"name": "acme.com",
"category": "email_provider"
}'{
"senderId": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"name": "acme.com",
"category": "email_provider",
"ipOrCidr": "198.2.132.0/24"
}Update a custom sender (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Partial update of a custom sender you created - rename, recategorize, add an IP range (how you register a second IP of the same server), or remove one. Removing a range re-attributes its traffic (past reports included) back to the catalog vendor underneath, or back to unknown. Reuses modifySenderCore (the SAME composition the dashboard + MCP update_sender use); audited "via API key X". Honors Idempotency-Key.
Requires a write-scoped key (Bearer).Optional client key; a retry with the same value replays the original response.
An IP or CIDR to add (widest /24 IPv4, /48 IPv6; max 16 ranges per sender).
An existing range to remove (refused for the last range - delete the sender instead).
Input ranges that sit inside a global catalog vendor's published ranges (warn-and-allow).
curl -X PATCH https://api.trustyourinbox.com/v1/senders/1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6" \
-d '{
"name": "acme.com",
"category": "email_provider",
"addRange": "example",
"removeRange": "example"
}'{
"senderId": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"name": "acme.com",
"corpusOverlaps": [
{
"range": "example",
"corpusSender": "example"
},
{
"range": "example",
"corpusSender": "example"
}
]
}Delete a custom sender (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Deletes a custom sender you created; its traffic - past reports included - re-attributes to the catalog vendor underneath, or back to unknown, and the workspace known-IP set reconverges. Reuses deleteSenderCore; audited "via API key X". Honors Idempotency-Key.
Requires a write-scoped key (Bearer).Optional client key; a retry with the same value replays the original response.
curl -X DELETE https://api.trustyourinbox.com/v1/senders/1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"senderId": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"name": "acme.com",
"deleted": true
}Webhooks#
List your outbound webhook endpoints (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope. Every outbound webhook endpoint in the workspace, with its URL, event filter, status, and failure streak. Never returns the signing secret, only its masked prefix. Requires the outboundWebhooks plan capability (Pro and up).
Requires a read-scoped key (Bearer).curl https://api.trustyourinbox.com/v1/webhooks \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"count": 3,
"webhooks": [
{
"id": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"url": "example",
"description": "example",
"secretPrefix": "example",
"eventTypes": [
"example",
"example"
],
"status": "active",
"consecutiveFailures": 0
},
{
"id": "2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
"url": "example",
"description": "example",
"secretPrefix": "example",
"eventTypes": [
"example",
"example"
],
"status": "active",
"consecutiveFailures": 0
}
]
}Register an outbound webhook endpoint (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Registers an https endpoint we POST a signed payload to on each critical event. Body { "url", "description"?, "eventTypes"? } - eventTypes omitted means all types. Returns the signing secret ONCE. Reuses createWebhookEndpointCore; audited "via API key X". Honors Idempotency-Key. Requires the outboundWebhooks capability (Pro and up).
Requires a write-scoped key (Bearer).Optional client key; a retry with the same value replays the original response.
The https endpoint URL to POST events to.
Optional label, e.g. Prod SIEM.
Which events to receive; omit for all.
The signing secret - returned ONCE, not retrievable later.
curl -X POST https://api.trustyourinbox.com/v1/webhooks \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6" \
-d '{
"url": "example",
"description": "example",
"eventTypes": [
"anomaly.crit",
"anomaly.crit"
]
}'{
"id": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"secret": "example",
"secretPrefix": "example"
}Delete an outbound webhook endpoint (public REST API, write) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; WRITE scope. Removes an endpoint; we stop delivering to it immediately and its delivery log is cascaded. Reuses deleteWebhookEndpointCore; audited "via API key X". Honors Idempotency-Key.
Requires a write-scoped key (Bearer).Optional client key; a retry with the same value replays the original response.
curl -X DELETE https://api.trustyourinbox.com/v1/webhooks/1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6 \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"id": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"deleted": true
}Recent delivery attempts for an endpoint (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope. The most recent delivery attempts for one endpoint (newest first) - the event type, status, HTTP response code, failure reason, and attempt number - for debugging your receiver.
Requires a read-scoped key (Bearer).curl https://api.trustyourinbox.com/v1/webhooks/1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6/deliveries \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"endpointId": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"count": 3,
"deliveries": [
{
"id": "1f2e3d4c-5b6a-7c8d-9e0f-a1b2c3d4e5f6",
"eventType": "example",
"status": "pending",
"responseCode": 0,
"error": "invalid_request",
"attempt": 0
},
{
"id": "2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
"eventType": "example",
"status": "pending",
"responseCode": 0,
"error": "invalid_request",
"attempt": 0
}
]
}Workspace#
Workspace-wide health summary (public REST API) #
Public REST API (api.trustyourinbox.com/v1). Bearer API key; read scope. Spoofer-adjusted alignment, trend, and totals - the same loader the dashboard hero uses. Rate-limited (120/60s per key).
Requires a read-scoped key (Bearer).Spoofer-adjusted workspace alignment %.
Change in points vs the prior window.
curl https://api.trustyourinbox.com/v1/workspace/health \
-H "Authorization: Bearer tyi_api_xxxxxxxxxxxxxxxxxxxxxxxx"{
"alignmentPct": 98,
"trendDeltaPp": 2,
"totalMessages": 1240,
"totalReports": 14,
"totalDomains": 6
}