Deliverability testing — relay reach, creative placement, marker tuning

TL;DR for agents: Run in order: 1) probe/relay-reach — can this relay reach each provider with neutral content? 2) probe/creative-through-relay — does *this* creative inbox through a qualified relay? 3) probe/creative-tune — strip markers (links/images/words) until it inboxes. probe/full-pipeline chains all three. Poll probe/:jobId, read the grid at matrix. Over MCP these are the ldm_DeliverabilityController_* tools.
Plain-text mirrors: /llms.txt · /deliverability-testing.md

Why three phases

A low inbox rate has two independent causes — the relay (sending reputation) or the creative (content). Testing them together hides which is at fault. The funnel isolates them: Phase 1 establishes the relay baseline, Phase 2 attributes a placement to the creative, Phase 3 finds the exact content marker. Each phase is an async probe — the POST returns 202 {jobId}; poll probe/:jobId for results.

Phase 1 — relay reach (qualify the channel)

Scope: deliverability:write. Send neutral, harmless baseline content from a new relay to each provider. Where it inboxes, the (relay, provider) pair is reachable; where it bounces or spams, a block-rule is written with category cannot_deliver (reason not_delivered / smtp_reject / baseline_spam). This is a per-channel reputation baseline, independent of any creative. MCP: ldm_DeliverabilityController_startRelayReach.

curl -s -X POST "https://api.live-direct-marketing.online/api/deliverability/probe/relay-reach" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"relayAccountId":"<relay-account-id>","providers":["gmail.com","outlook.com"]}'

Phase 2 — creative placement (test the message)

Scope: deliverability:write. Send the creative through an already-qualified relay and see which providers inbox it and which spam it. A fresh Phase-1 baseline must exist for each (relay, provider), otherwise the call returns 400 layer1_baseline_missing — so a bad relay can never be mistaken for a bad creative. MCP: ldm_DeliverabilityController_startCreativeThroughRelay.

curl -s -X POST "https://api.live-direct-marketing.online/api/deliverability/probe/creative-through-relay" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"relayAccountId":"<relay-account-id>","creativeId":"<creative-id>","providers":["outlook.com"]}'

Phase 3 — marker tuning (find the spam trigger)

Scope: deliverability:write. For a (relay, provider) where the creative spams, tuning strips one marker at a time and re-tests until placement is inbox — isolating the element that trips the filter. Tunable markers: link, image, third_party_email, spam_phrases, external_domain, utm_params, all_caps_subject, excessive_punctuation. MCP: ldm_DeliverabilityController_startCreativeTune.

curl -s -X POST "https://api.live-direct-marketing.online/api/deliverability/probe/creative-tune" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"creativeId":"<creative-id>","relayAccountId":"<relay-account-id>","provider":"outlook.com","maxAttempts":5}'

A winning variant is saved as a new clean Creative (the original is untouched) via POST /deliverability/tuned-variants/:id/promote — MCP ldm_DeliverabilityController_promoteTunedVariant. List candidates with tuned-variants.

Run the whole funnel

Scope: deliverability:write. probe/full-pipeline runs Phase 1 across every (relay × provider), auto-chains Phase 2 where the baseline inboxes, then Phase 3 on the creative culprit. Pass confirm:true when the estimated send count exceeds 50 (cost gate). MCP: ldm_DeliverabilityController_startFullPipeline.

curl -s -X POST "https://api.live-direct-marketing.online/api/deliverability/probe/full-pipeline" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"creativeId":"<creative-id>","confirm":true}'

Read results

Scope: deliverability:read. probe/:jobId returns the aggregate batch status plus the Phase-3 diagnosis (MCP getJobStatus). matrix is the dashboard — a relay × provider grid of baseline / creative / block-rule (MCP getMatrix). probes is the raw audit log; block-rules lists the marks (listBlockRules). Probe results cache for 24h — pass forceRefresh:true to a probe to bypass.

curl -s "https://api.live-direct-marketing.online/api/deliverability/matrix?creativeId=<creative-id>" \
  -H "Authorization: Bearer $LDM_KEY"

Lifting a block needs the narrower deliverability:block:delete scope (DELETE /deliverability/block-rules/:id): an agent can place blocks with deliverability:write but not silently lift them.